全局规则与配置维度清单

本文档用于定义当前系统中跨玩法共用的全局规则块和配置维度，作为后续所有玩法设计文档、配置文件设计、后台录入和联调的统一骨架。

目标：

统一“一个玩法设计文档至少要覆盖哪些公共规则块”
统一“一个游戏配置文件通常会包含哪些跨玩法公共配置”
为后续新增系统能力时提供持续维护入口

说明：

本文档讲的是全局规则块
它不替代具体玩法规则文档
它也不替代具体玩法的可配置项清单
推荐和顺序打点规则说明文档、顺序打点游戏配置项、配置选项字典配合阅读
后续玩法设计建议统一使用玩法设计文档模板

1. 设计原则

后续每个玩法设计文档，至少建议覆盖以下三层：

玩法专属规则
全局规则块选型
配置落点与默认值

也就是说，后续写一个新玩法时，不应该只写：

怎么玩
怎么赢

还应该明确：

用哪套定位点样式
用哪套轨迹策略
是否启用腿线动画
是否启用内容弹层
是否启用音效、震动和 HUD 反馈
哪些沿用系统默认值，哪些做玩法覆盖

2. 推荐公共骨架

当前推荐所有玩法配置继续沿用以下顶层骨架：

{
  "schemaVersion": "1",
  "version": "2026.03.31",
  "app": {},
  "map": {},
  "playfield": {},
  "game": {},
  "resources": {},
  "debug": {}
}

其中：

app 管活动级基础信息
map 管地图底图和视口底座
playfield 管场地对象、路线和点位内容
game 管玩法规则和全局运行规则
resources 管资源档和主题档
debug 管调试与模拟能力

3. 全局规则块总表

规则块	建议落点	作用	是否建议每个玩法都明确
活动基础信息	`app.*`	定义活动身份、标题和语言环境	是
地图底座	`map.*`	定义地图来源、磁偏角和初始视口	是
场地对象	`playfield.*`	定义路线、控制点、对象集和内容覆盖	是
对局流程	`game.session.*`	定义开局、结束、时长和起终点要求	是
打点判定	`game.punch.*`	定义打点触发方式和判定半径	是
顺序推进 / 跳点	`game.sequence.*`	定义顺序赛推进和跳点规则	顺序类玩法必须明确
计分模型	`game.scoring.*`	定义分值模型和点位得分规则	有计分时必须明确
引导显示	`game.guidance.*`	定义腿线、目标聚焦和地图引导	是
可见性策略	`game.visibility.*`	定义开局是否隐藏对象、何时揭示全场	是
完赛规则	`game.finish.*`	定义终点生效条件和结束逻辑	是
内容体验	`playfield.controlOverrides.*`	定义点位弹窗、H5、点击内容	有内容玩法建议明确
点位表现	`game.presentation.*.controls`	定义控制点不同状态样式	是
腿线表现	`game.presentation.*.legs`	定义路线连接线样式和动效	有路线玩法建议明确
轨迹表现	`game.presentation.track.*`	定义玩家轨迹展示策略	是
定位点表现	`game.presentation.gpsMarker.*`	定义 GPS 点样式和动画	是
遥测参数	`game.telemetry.*`	定义心率等计算参数，作为活动默认值	用到相关能力时明确
反馈系统	`game.feedback.*`	定义音效、震动、UI 动效	是
资源档	`resources.*`	定义音频、主题、内容资源档	是
调试能力	`debug.*`	定义模拟输入和调试开关	开发阶段建议明确

4. 各规则块说明

4.1 活动基础信息

名称	字段	说明	可选项 / 取值	默认值
活动 ID	`app.id`	活动或配置实例唯一标识	任意字符串	无，建议必填
活动标题	`app.title`	页面展示和结算展示的标题	任意字符串	无，建议必填
语言环境	`app.locale`	文案和内容环境	当前常用：`zh-CN`	`zh-CN`

4.2 地图底座

名称	字段	说明	可选项 / 取值	默认值
瓦片路径	`map.tiles`	地图瓦片资源位置	路径字符串	无，建议必填
地图元数据	`map.mapmeta`	地图 meta 文件	路径字符串	无，建议必填
磁偏角	`map.declination`	影响真北/磁北换算	`number`	`0`
初始缩放	`map.initialView.zoom`	地图初始缩放级别	`number`	由客户端初始视口逻辑接管，建议 `17`

4.3 场地对象

名称	字段	说明	可选项 / 取值	默认值
场地类型	`playfield.kind`	定义玩法使用的对象集合类型	`course` `control-set`	由玩法决定，顺序赛常用 `course`
场地来源类型	`playfield.source.type`	定义空间底稿来源	当前支持：`kml`	`kml`
场地来源地址	`playfield.source.url`	KML 或其他空间资源地址	路径字符串	无，建议必填
控制点绘制半径	`playfield.CPRadius`	影响地图上控制点圈的展示大小	`number`	`6`
路线标题	`playfield.metadata.title`	路线或对象集标题	任意字符串	无
路线编码	`playfield.metadata.code`	路线或对象集编码	任意字符串	无

4.4 对局流程

名称	字段	说明	可选项 / 取值	默认值
手动开始	`game.session.startManually`	是否需要玩家主动点开始按钮	`true` `false`	顺序赛默认 `false`
必须打起点	`game.session.requiresStartPunch`	是否要求起点打卡后才正式开赛	`true` `false`	顺序赛默认 `true`
必须打终点	`game.session.requiresFinishPunch`	是否要求终点打卡才能完赛	`true` `false`	顺序赛默认 `true`
最后点自动结束	`game.session.autoFinishOnLastControl`	最后一个普通点完成后是否直接结束	`true` `false`	`false`
最大时长	`game.session.maxDurationSec`	单局允许的最大比赛时长	`number`	`5400`

4.5 打点判定

名称	字段	说明	可选项 / 取值	默认值
打点策略	`game.punch.policy`	控制进入范围后如何完成打点	`enter-confirm` `enter`	`enter-confirm`
打点半径	`game.punch.radiusMeters`	打点命中的半径阈值	`number`	`5`
必须先聚焦目标	`game.punch.requiresFocusSelection`	是否必须先选中目标点才能打卡	`true` `false`	顺序赛默认 `false`，积分赛默认 `true`

4.6 顺序推进 / 跳点

名称	字段	说明	可选项 / 取值	默认值
是否允许跳点	`game.sequence.skip.enabled`	顺序玩法是否允许跳过当前目标点	`true` `false`	顺序赛默认 `true`
跳点半径	`game.sequence.skip.radiusMeters`	触发跳点的距离阈值	`number`	`game.punch.radiusMeters * 2`
跳点确认	`game.sequence.skip.requiresConfirm`	触发跳点时是否需要二次确认	`true` `false`	`false`

4.7 计分模型

名称	字段	说明	可选项 / 取值	默认值
计分模型	`game.scoring.type`	定义玩法采用哪种积分模型	当前建议：`score`	`score`
默认控制点分值	`game.scoring.defaultControlScore`	普通点未单独配置时的默认分值	`number`	顺序赛默认 `1`，积分赛默认 `10`

备注：

顺序赛当前基础分、答题奖励分等更细规则仍以玩法规则文档为准，但系统默认基础分已按 1 落地
后续如果顺序赛积分逻辑进一步配置化，应优先补到 game.scoring 下

4.8 引导显示

名称	字段	说明	可选项 / 取值	默认值
显示腿线	`game.guidance.showLegs`	是否绘制路线连接线	`true` `false`	顺序赛默认 `true`
腿线动画	`game.guidance.legAnimation`	是否启用腿线动画效果	`true` `false`	顺序赛默认 `true`
允许地图选点	`game.guidance.allowFocusSelection`	是否允许用户点击地图切换目标	`true` `false`	顺序赛默认 `false`

补充说明：

黑色顶部引导提示条属于公共引导层。
当前默认在引导文案发生有效变化时，提示条会播放一次轻量入场动画，并辅以一次轻震动。
当内容卡、答题卡或结果页出现时，引导提示条默认让位。
顶部引导提示条的反馈与距离引导反馈分离管理，不能互相替代。
当前距离引导反馈默认分为三档：
- 远距离：弱提醒，间隔更长
- 接近目标：提醒频率提升
- 可打点：高频确认提醒

4.9 可见性策略

名称	字段	说明	可选项 / 取值	默认值
起点后揭示全场	`game.visibility.revealFullPlayfieldAfterStartPunch`	打完起点后是否显示全部控制点与路线	`true` `false`	`true`

4.10 完赛规则

名称	字段	说明	可选项 / 取值	默认值
终点始终可选	`game.finish.finishControlAlwaysSelectable`	终点是否无条件可生效	`true` `false`	顺序赛默认 `false`

4.11 内容体验

名称	字段	说明	可选项 / 取值	默认值
自动弹窗模板	`playfield.controlOverrides.<key>.template`	点位完成后默认卡片模板	`minimal` `story` `focus`	起终点常用 `focus`，普通点常用 `story`
自动弹窗开关	`playfield.controlOverrides.<key>.autoPopup`	完成点位后是否自动弹内容	`true` `false`	最小模板默认 `false`
自动内容仅一次	`playfield.controlOverrides.<key>.once`	本局是否只自动展示一次	`true` `false`	`false`
内容承载方式	`playfield.controlOverrides.<key>.contentExperience.type`	自动内容使用原生还是 H5	`native` `h5`	当前按点位配置
内容展示形态	`playfield.controlOverrides.<key>.contentExperience.presentation`	H5 内容如何呈现	`sheet` `dialog` `fullscreen`	`sheet`
点击承载方式	`playfield.controlOverrides.<key>.clickExperience.type`	点击点位时使用原生还是 H5	`native` `h5`	当前按点位配置
点击展示形态	`playfield.controlOverrides.<key>.clickExperience.presentation`	点击 H5 如何呈现	`sheet` `dialog` `fullscreen`	`sheet`

说明：

最小模板下，点击检查点默认不弹任何详情卡，也不直接打开答题卡。
最小模板下，起点和普通点完成后默认不弹白色内容卡。
点击内容能力改为显式配置能力；只有配置了 clickTitle / clickBody / clickExperience 之一时，点击点位才会产生内容反馈。
完成后自动弹白卡也改为显式配置能力；只有明确开启 autoPopup = true 时，完成点位后才会弹出白色内容卡。
点击详情卡片当前默认不展示 H5 详情按钮，但 clickExperience 和 CTA 能力保留。
连续点击不同检查点时，新的点击卡片会直接替换当前卡片，不进入手动关闭队列。
黑色顶部提示条只承担操作引导，不承载点位内容或结果信息。
当白色内容卡、答题卡或结果页出现时，黑色顶部提示条默认让位，不与内容层抢注意力。
白色内容卡当前分为两类：
- 浏览型：点击点位查看说明，无按钮，默认约 4 秒自动消失，点击屏幕任意位置可关闭。
- 交互型：打点完成后的即时内容卡，可带 CTA 或进入答题流程。
终点完成默认直接进入原生成绩总览页，不再额外叠加终点白色内容卡；如需再次查看终点说明，需显式配置点击内容能力。

4.12 点位表现

名称	字段	说明	可选项 / 取值	默认值
点位样式	`game.presentation.<mode>.controls.<state>.style`	控制点形状和结构	`classic-ring` `solid-dot` `double-ring` `badge` `pulse-core`	由玩法状态决定
点位主色	`game.presentation.<mode>.controls.<state>.colorHex`	控制点颜色	十六进制颜色字符串	顺序赛默认参考传统定向紫红色
点位尺寸倍率	`game.presentation.<mode>.controls.<state>.sizeScale`	控制点大小缩放	`number`	`1` 或按状态定制
强调环倍率	`game.presentation.<mode>.controls.<state>.accentRingScale`	外环强调强度	`number`	按状态定制
光晕强度	`game.presentation.<mode>.controls.<state>.glowStrength`	点位光晕表现	建议 `0 ~ 1`	按状态定制
标签倍率	`game.presentation.<mode>.controls.<state>.labelScale`	点位编号大小	`number`	`1` 或按状态定制
标签颜色	`game.presentation.<mode>.controls.<state>.labelColorHex`	点位编号颜色	十六进制颜色字符串	按状态定制

状态建议至少考虑：

default
current
completed
skipped
start
finish

4.13 腿线表现

名称	字段	说明	可选项 / 取值	默认值
腿线样式	`game.presentation.<mode>.legs.<state>.style`	连接线风格	`classic-leg` `dashed-leg` `glow-leg` `progress-leg`	顺序赛默认建议 `classic-leg`
腿线主色	`game.presentation.<mode>.legs.<state>.colorHex`	连接线颜色	十六进制颜色字符串	顺序赛默认建议传统定向紫红色
腿线宽度倍率	`game.presentation.<mode>.legs.<state>.widthScale`	连接线粗细	`number`	视玩法决定
腿线光晕强度	`game.presentation.<mode>.legs.<state>.glowStrength`	连接线发光程度	建议 `0 ~ 1`	视玩法决定

状态建议至少考虑：

default
completed

4.14 轨迹表现

名称	字段	说明	可选项 / 取值	默认值
轨迹模式	`game.presentation.track.mode`	决定是否显示轨迹以及显示方式	`none` `tail` `full`	顺序赛建议 `full`
轨迹风格	`game.presentation.track.style`	整体视觉风格	`classic` `neon`	当前默认 `neon`
拖尾档位	`game.presentation.track.tailLength`	拖尾长度档位	`short` `medium` `long`	视玩法决定
预设色盘	`game.presentation.track.colorPreset`	轨迹预设颜色方案	`mint` `cyan` `sky` `blue` `violet` `pink` `orange` `yellow`	按玩法决定
拖尾长度	`game.presentation.track.tailMeters`	实际拖尾长度	`number`	可覆盖档位映射
拖尾时窗	`game.presentation.track.tailMaxSeconds`	最大拖尾时间窗口	`number`	选填
静止淡出	`game.presentation.track.fadeOutWhenStill`	静止时是否逐步淡出	`true` `false`	选填
静止阈值	`game.presentation.track.stillSpeedKmh`	判定静止的速度阈值	`number`	选填
淡出时长	`game.presentation.track.fadeOutDurationMs`	静止后淡出时长	`number`	选填
轨迹主色	`game.presentation.track.colorHex`	主体轨迹颜色	十六进制颜色字符串	未配时回退到预设色盘
轨迹头部色	`game.presentation.track.headColorHex`	轨迹头部高亮颜色	十六进制颜色字符串	未配时回退到预设色盘
轨迹宽度	`game.presentation.track.widthPx`	主体轨迹宽度	`number`	选填
头部宽度	`game.presentation.track.headWidthPx`	头部高亮宽度	`number`	选填
轨迹光晕	`game.presentation.track.glowStrength`	轨迹光晕强度	建议 `0 ~ 1`	选填

4.15 定位点表现

名称	字段	说明	可选项 / 取值	默认值
是否显示定位点	`game.presentation.gpsMarker.visible`	控制 GPS 点是否可见	`true` `false`	`true`
定位点样式	`game.presentation.gpsMarker.style`	GPS 点基础形态	`dot` `beacon` `disc` `badge`	`beacon`
定位点尺寸	`game.presentation.gpsMarker.size`	GPS 点大小档位	`small` `medium` `large`	`medium`
定位点预设色盘	`game.presentation.gpsMarker.colorPreset`	GPS 点默认色彩方案	`mint` `cyan` `sky` `blue` `violet` `pink` `orange` `yellow`	`cyan`
定位点主色	`game.presentation.gpsMarker.colorHex`	GPS 点主体颜色	十六进制颜色字符串	未配时回退到预设色盘
外环颜色	`game.presentation.gpsMarker.ringColorHex`	GPS 点外环颜色	十六进制颜色字符串	未配时回退到预设色盘
朝向指示颜色	`game.presentation.gpsMarker.indicatorColorHex`	小三角或朝向指示颜色	十六进制颜色字符串	未配时回退到预设色盘
显示朝向指示	`game.presentation.gpsMarker.showHeadingIndicator`	是否显示跟随朝向旋转的指示三角	`true` `false`	`true`
定位点动画档	`game.presentation.gpsMarker.animationProfile`	GPS 点动画风格	`minimal` `dynamic-runner` `warning-reactive`	`dynamic-runner`
中心 logo 地址	`game.presentation.gpsMarker.logoUrl`	品牌中心贴片资源	URL 字符串	选填
logo 嵌入方式	`game.presentation.gpsMarker.logoMode`	品牌贴片嵌入方式	`center-badge`	当前支持该值

4.16 遥测参数

名称	字段	说明	可选项 / 取值	默认值
年龄	`game.telemetry.heartRate.age`	心率估算的年龄参数	`number`	`30`
静息心率	`game.telemetry.heartRate.restingHeartRateBpm`	心率估算基础参数	`number`	`62`
体重	`game.telemetry.heartRate.userWeightKg`	卡路里或体征估算参数	`number`	`65`

说明：

这里定义的是活动级默认值
如果后续接入线上玩家身体数据接口，线上数据应覆盖这里的同名字段

4.17 HUD 信息面板

名称	字段 / 归属	说明	可选项 / 取值	默认值
HUD 页数	公共 UI 壳子	当前 HUD 固定为 `2` 页	`2`	`2`
HUD 第 1 页	公共 UI 壳子	比赛主信息页，承载动作、时间、里程、目标距离、进度等异型槽位	固定结构	启用
HUD 第 2 页	公共 UI 壳子	心率 / 遥测页，承载心率、卡路里、均速、精度等异型槽位	固定结构	启用
HUD 项目映射	玩法映射	不同玩法可将不同数据映射到相同 HUD 槽位	按玩法定义	按玩法默认
HUD 目标摘要	玩法映射	第 1 页动作区下方的摘要文案，用于显示当前目标或提示信息	`string`	按玩法默认
HUD 进度摘要	玩法映射	第 1 页进度区显示的核心摘要，不同玩法可映射为总分、完成进度、跳点数等	`string`	按玩法默认

说明：

HUD 属于公共层能力，不属于某一个玩法专属规则。
当前系统采用“公共 HUD 壳子 + 玩法项目映射”的方式。
例如：
- 积分赛可将进度位映射为“总分 + 收集进度”
- 顺序打点可将进度位映射为“完成进度 + 跳点数”

4.18 反馈系统

名称	字段	说明	可选项 / 取值	默认值
音效反馈档	`game.feedback.audioProfile`	控制音效方案	`string`	`default`
震动反馈档	`game.feedback.hapticsProfile`	控制震动策略	`string`	`default`
UI 动效档	`game.feedback.uiEffectsProfile`	控制 UI 动效策略	`string`	`default`
距离提示音阈值	`game.audio.*DistanceMeters`	控制远距离 / 接近 / 可打点三档距离提示的生效距离	`number`	远距离 `80`，接近 `20`，可打点 `5`
距离提示音间隔	`game.audio.cues.guidance:.`	控制三档距离提示音的循环间隔、音量和音源	`number` / `string` / `boolean`	远距离 `4800ms`，接近 `950ms`，可打点 `650ms`

说明：

系统当前已支持音效反馈能力。
默认答题正确复用控制点完成音效，答题错误和答题超时复用警告音效。
引导提示条当前默认改用轻震动，不再播放引导提示音。
目标距离引导当前默认分为 distant / approaching / ready 三档，作为独立反馈链路，可使用距离提示音，不与顶部引导提示绑定。
当前三档距离提示已支持分别配置距离阈值与循环间隔。

4.19 资源档

名称	字段	说明	可选项 / 取值	默认值
音效资源档	`resources.audioProfile`	选择音频资源包	`string`	`default`
内容资源档	`resources.contentProfile`	选择内容资源包	`string`	`default`
主题资源档	`resources.themeProfile`	选择主题和视觉资源包	`string`	`default-race`

4.20 调试能力

名称	字段	说明	可选项 / 取值	默认值
允许玩法切换	`debug.allowModeSwitch`	是否允许在调试时切玩法	`true` `false`	`false`
允许模拟输入	`debug.allowMockInput`	是否允许用模拟数据代替真实输入	`true` `false`	`false`
允许模拟器	`debug.allowSimulator`	是否开放调试模拟器面板	`true` `false`	`false`

5. 后续所有玩法设计文档的建议结构

后续每新增一种玩法，设计文档建议至少包含以下章节：

玩法目标与一句话规则
开局流程与结束流程
核心判定与胜负条件
计分规则
对象模型与场地对象要求
全局规则块选型
默认值与玩法覆盖项
最小可跑配置示例

其中第 6 节“全局规则块选型”建议至少回答：

用哪套定位点样式
用哪套轨迹显示策略
是否显示腿线和腿线动画
起点后是否揭示全场
是否需要内容弹层和 H5 承载
用哪套反馈档
是否依赖心率等遥测参数

6. 维护约定

后续每次新增全局系统能力时，建议至少同步更新以下文档：

本文档
配置选项字典
当前最全配置模板
对应能力的专项文档
- 例如轨迹、GPS 点样式、GPS 点动画、内容体验、反馈系统
至少一个玩法的配置样例

这样可以保证：

玩法设计有统一骨架
配置字段有统一归档
后台配置管理有明确输入目标
后续扩展不会只长代码、不长文档

全局规则与配置维度清单.md 23 KB Historia Czysty