cmr-mini/doc/config/全局规则与配置维度清单.md

全局规则与配置维度清单

文档版本：v1.0 最后更新：2026-04-02 08:28:05

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

目标：

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

说明：

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

---

1. 设计原则

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

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

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

• 怎么玩
• 怎么赢

还应该明确：

• 用哪套定位点样式
• 用哪套轨迹策略
• 是否启用腿线动画
• 是否启用内容弹层
• 是否启用音效、震动和 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 内容如何呈现	运行建议 fullscreen；兼容历史值 sheet dialog	fullscreen
点击承载方式	playfield.controlOverrides.<key>.clickExperience.type	点击点位时使用原生还是 H5	native h5	当前按点位配置
点击展示形态	playfield.controlOverrides.<key>.clickExperience.presentation	点击 H5 如何呈现	运行建议 fullscreen；兼容历史值 sheet dialog	fullscreen

说明：

• 最小模板下，点击检查点默认不弹任何详情卡，也不直接打开答题卡。
• 最小模板下，起点和普通点完成后默认不弹白色内容卡。
• 点击内容能力改为显式配置能力；只有配置了 clickTitle / clickBody / clickExperience 之一时，点击点位才会产生内容反馈。
• 完成后自动弹白卡也改为显式配置能力；只有明确开启 autoPopup = true 时，完成点位后才会弹出白色内容卡。
• 点击详情卡片当前默认不展示 H5 详情按钮，但 clickExperience 和 CTA 能力保留。
• 当前真机约束下，web-view 不再承担局部弹窗职责；原生内容卡负责即时弹出，H5 详情统一按整页承载。
• 连续点击不同检查点时，新的点击卡片会直接替换当前卡片，不进入手动关闭队列。
• 黑色顶部提示条只承担操作引导，不承载点位内容或结果信息。
• 当白色内容卡、答题卡或结果页出现时，黑色顶部提示条默认让位，不与内容层抢注意力。
• 白色内容卡当前分为两类：
  • 浏览型：点击点位查看说明，无按钮，默认约 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. 后续所有玩法设计文档的建议结构

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

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

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

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

---

6. 维护约定

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

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

这样可以保证：

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