Files
cmr-mini/doc/games/顺序打点/游戏配置项.md

364 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 顺序打点游戏配置项
> 文档版本v1.0
> 最后更新2026-04-02 08:28:05
本文档用于汇总当前系统对 `classic-sequential` 的**已支持可配置项**,便于产品、客户端、服务端、后台录入和联调统一对照。
目标:
- 列出顺序打点当前可配置的字段名
- 说明每个字段的作用
- 说明字段可选项或取值范围
- 标注推荐默认值或当前默认逻辑
说明:
- 本文档只聚焦 `classic-sequential`
- 以当前实现和现有文档口径为准
- 如果你需要看跨玩法的完整字段字典,请继续参考 [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md)
---
## 1. 顶层结构
```json
{
"schemaVersion": "1",
"version": "2026.03.31",
"app": {},
"map": {},
"playfield": {},
"game": {},
"resources": {},
"debug": {}
}
```
---
## 2. 顶层字段
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `schemaVersion` | 配置结构版本 | 当前建议:`"1"` | 建议固定写 `"1"` |
| `version` | 当前配置内容版本号 | 任意版本字符串,例如日期版号 | 建议按发布日期维护 |
| `app` | 活动级基础信息 | `object` | 必填 |
| `map` | 地图底座信息 | `object` | 必填 |
| `playfield` | 场地对象、路线和点位内容覆盖 | `object` | 必填 |
| `game` | 顺序打点规则与局流程 | `object` | 必填 |
| `resources` | 资源 profile 引用 | `object` | 选填 |
| `debug` | 调试开关 | `object` | 选填 |
---
## 3. `app`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `app.id` | 活动或配置实例 ID | 任意字符串 | 建议全局唯一 |
| `app.title` | 活动标题 / 比赛名称 | 任意字符串 | 建议必填 |
| `app.locale` | 语言环境 | 当前常用:`zh-CN` | 默认建议:`zh-CN` |
---
## 4. `map`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `map.tiles` | 瓦片根路径 | 路径字符串 | 必填 |
| `map.mapmeta` | 地图元数据路径 | 路径字符串 | 必填 |
| `map.declination` | 磁偏角 | `number` | 未配置时按 `0` 处理 |
| `map.initialView.zoom` | 初始缩放级别 | `number` | 默认由客户端初始视口逻辑接管,建议值 `17` |
---
## 5. `playfield`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `playfield.kind` | 场地对象类型 | 顺序打点固定使用:`course` | 顺序打点建议固定 `course` |
| `playfield.source.type` | 场地来源类型 | 当前支持:`kml` | 建议固定 `kml` |
| `playfield.source.url` | KML 路径 | 路径字符串 | 必填 |
| `playfield.CPRadius` | 地图上控制点绘制半径 | `number` | 建议默认值:`6` |
| `playfield.metadata.title` | 路线标题 | 任意字符串 | 选填 |
| `playfield.metadata.code` | 路线编码 | 任意字符串 | 选填 |
---
## 6. `playfield.controlOverrides`
`playfield.controlOverrides` 用于对指定起点、普通控制点、终点做内容和样式覆盖。
### 6.1 Key 命名
| Key 模式 | 作用 |
| --- | --- |
| `start-1` | 起点 |
| `control-1``control-2``control-3` | 普通控制点 |
| `finish-1` | 终点 |
### 6.2 内容与交互字段
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `playfield.controlOverrides.<key>.template` | 原生内容卡模板 | `minimal` `story` `focus` | 起点/终点建议 `focus`,普通点建议 `story` |
| `playfield.controlOverrides.<key>.title` | 打点后自动弹出的标题 | 任意字符串 | 未配置时走默认文案 |
| `playfield.controlOverrides.<key>.body` | 打点后自动弹出的正文 | 任意字符串 | 未配置时走默认文案 |
| `playfield.controlOverrides.<key>.clickTitle` | 点击点位时弹出的标题 | 任意字符串 | 最小模板下默认关闭,需显式配置 |
| `playfield.controlOverrides.<key>.clickBody` | 点击点位时弹出的正文 | 任意字符串 | 最小模板下默认关闭,需显式配置 |
| `playfield.controlOverrides.<key>.autoPopup` | 打点后是否自动弹内容卡 | `true` / `false` | 默认 `true`;自动打点模式下不自动弹内容卡;普通控制点默认题卡仍按玩法规则自动进入 |
| `playfield.controlOverrides.<key>.once` | 自动内容是否本局只展示一次 | `true` / `false` | 默认 `false` |
| `playfield.controlOverrides.<key>.priority` | 内容优先级 | `number` | 普通点默认 `1`,终点默认 `2` |
### 6.3 H5 / 原生体验承载字段
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `playfield.controlOverrides.<key>.contentExperience.type` | 打点后内容承载方式 | `native` `h5` | 当前支持两种 |
| `playfield.controlOverrides.<key>.contentExperience.url` | 打点后 H5 地址 | URL 字符串 | 仅 `type = "h5"` 时生效 |
| `playfield.controlOverrides.<key>.contentExperience.bridge` | 打点后 H5 bridge 版本 | 当前建议:`content-v1` | 默认建议:`content-v1` |
| `playfield.controlOverrides.<key>.contentExperience.presentation` | 打点后 H5 展示形态 | `sheet` `dialog` `fullscreen` | 默认建议:`sheet` |
| `playfield.controlOverrides.<key>.clickExperience.type` | 点击内容承载方式 | `native` `h5` | 当前支持两种 |
| `playfield.controlOverrides.<key>.clickExperience.url` | 点击 H5 地址 | URL 字符串 | 仅 `type = "h5"` 时生效 |
| `playfield.controlOverrides.<key>.clickExperience.bridge` | 点击 H5 bridge 版本 | 当前建议:`content-v1` | 默认建议:`content-v1` |
| `playfield.controlOverrides.<key>.clickExperience.presentation` | 点击 H5 展示形态 | `sheet` `dialog` `fullscreen` | 默认建议:`sheet` |
### 6.4 点位样式覆盖字段
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `playfield.controlOverrides.<key>.pointStyle` | 单点样式覆盖 | `classic-ring` `solid-dot` `double-ring` `badge` `pulse-core` | 未配置时回退到玩法样式 |
| `playfield.controlOverrides.<key>.pointColorHex` | 单点颜色覆盖 | 十六进制颜色字符串 | 例如 `#27ae60` |
| `playfield.controlOverrides.<key>.pointSizeScale` | 单点尺寸倍率 | 建议 `0.6 ~ 1.4` | 默认 `1` |
| `playfield.controlOverrides.<key>.pointAccentRingScale` | 单点强调环倍率 | 建议 `1.0 ~ 1.6` | 未配置时回退到玩法样式 |
| `playfield.controlOverrides.<key>.pointGlowStrength` | 单点光晕强度 | 建议 `0 ~ 1` | 默认 `0` |
| `playfield.controlOverrides.<key>.pointLabelScale` | 单点标签字号倍率 | 建议 `0.7 ~ 1.3` | 默认 `1` |
| `playfield.controlOverrides.<key>.pointLabelColorHex` | 单点标签颜色覆盖 | 十六进制颜色字符串 | 例如 `#ffffff` |
---
## 7. `playfield.legOverrides`
`playfield.legOverrides` 用于对指定腿线做局部样式覆盖。
### 7.1 Key 命名
| Key 模式 | 作用 |
| --- | --- |
| `leg-1``leg-2``leg-3` | 指定路线腿段 |
### 7.2 字段
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `playfield.legOverrides.<key>.style` | 局部腿线样式 | `classic-leg` `dashed-leg` `glow-leg` `progress-leg` | 未配置时回退到玩法样式 |
| `playfield.legOverrides.<key>.colorHex` | 局部腿线颜色 | 十六进制颜色字符串 | 例如 `#27ae60` |
| `playfield.legOverrides.<key>.widthScale` | 局部腿线宽度倍率 | `number` | 选填 |
| `playfield.legOverrides.<key>.glowStrength` | 局部腿线光晕强度 | 建议 `0 ~ 1` | 选填 |
---
## 8. `game`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `game.mode` | 玩法类型 | 顺序打点固定:`classic-sequential` | 建议固定写死 |
| `game.rulesVersion` | 规则版本 | 任意字符串,当前建议 `1` | 建议随规则迭代维护 |
---
## 9. `game.session`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `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` |
---
## 10. `game.punch`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `game.punch.policy` | 打点策略 | `enter-confirm` `enter` | 默认 `enter-confirm` |
| `game.punch.radiusMeters` | 打点判定半径 | `number` | 默认建议 `5` |
| `game.punch.requiresFocusSelection` | 是否必须先聚焦目标再打点 | `true` / `false` | 顺序打点默认 `false` |
---
## 11. `game.sequence.skip`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `game.sequence.skip.enabled` | 是否允许跳点 | `true` / `false` | 顺序打点默认 `true` |
| `game.sequence.skip.radiusMeters` | 跳点判定半径 | `number` | 顺序打点默认 `game.punch.radiusMeters * 2` |
| `game.sequence.skip.requiresConfirm` | 跳点是否需要确认 | `true` / `false` | 顺序打点默认 `false` |
---
## 12. `game.guidance`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `game.guidance.showLegs` | 是否显示路线腿线 | `true` / `false` | 顺序打点默认 `true` |
| `game.guidance.legAnimation` | 是否开启腿线动画 | `true` / `false` | 顺序打点默认 `true` |
| `game.guidance.allowFocusSelection` | 是否允许地图点击选点 | `true` / `false` | 顺序打点默认 `false` |
---
## 13. `game.visibility`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `game.visibility.revealFullPlayfieldAfterStartPunch` | 起点打卡后是否显示完整路线与控制点 | `true` / `false` | 顺序打点默认 `true` |
---
## 14. `game.finish`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `game.finish.finishControlAlwaysSelectable` | 终点是否始终可生效 | `true` / `false` | 顺序打点默认 `false`,默认要求中间点都已“成功”或“跳过” |
---
## 15. `game.telemetry.heartRate`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `game.telemetry.heartRate.age` | 年龄 | `number` | 建议默认 `30` |
| `game.telemetry.heartRate.restingHeartRateBpm` | 静息心率 | `number` | 建议默认 `62` |
| `game.telemetry.heartRate.userWeightKg` | 体重kg | `number` | 建议默认 `65` |
---
## 16. `game.feedback`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `game.feedback.audioProfile` | 音效反馈配置档 | `string` | 默认 `default` |
| `game.feedback.hapticsProfile` | 震动反馈配置档 | `string` | 默认 `default` |
| `game.feedback.uiEffectsProfile` | UI 动效配置档 | `string` | 默认 `default` |
---
## 17. `game.presentation.sequential.controls`
以下字段分别作用于不同控制点状态:`default``current``completed``skipped``start``finish`
### 17.1 状态节点
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `game.presentation.sequential.controls.default` | 普通未完成控制点样式 | `object` | 建议使用传统定向紫红色 |
| `game.presentation.sequential.controls.current` | 当前目标点样式 | `object` | 建议强化动效和光晕 |
| `game.presentation.sequential.controls.completed` | 已完成点样式 | `object` | 默认建议灰色态 |
| `game.presentation.sequential.controls.skipped` | 已跳过点样式 | `object` | 默认建议橙色态 |
| `game.presentation.sequential.controls.start` | 起点样式 | `object` | 建议带明显开赛强调 |
| `game.presentation.sequential.controls.finish` | 终点样式 | `object` | 建议带明显收尾强调 |
### 17.2 每个状态对象内可配置字段
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `<state>.style` | 点位样式 | `classic-ring` `solid-dot` `double-ring` `badge` `pulse-core` | 按状态选择 |
| `<state>.colorHex` | 点位主色 | 十六进制颜色字符串 | 例如 `#cc006b` |
| `<state>.sizeScale` | 点位尺寸倍率 | `number` | 选填 |
| `<state>.accentRingScale` | 强调环倍率 | `number` | 选填 |
| `<state>.glowStrength` | 光晕强度 | 建议 `0 ~ 1` | 选填 |
| `<state>.labelScale` | 标签尺寸倍率 | `number` | 选填 |
| `<state>.labelColorHex` | 标签颜色 | 十六进制颜色字符串 | 选填 |
---
## 18. `game.presentation.sequential.legs`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `game.presentation.sequential.legs.default.style` | 默认腿线样式 | `classic-leg` `dashed-leg` `glow-leg` `progress-leg` | 建议顺序打点使用 `classic-leg` |
| `game.presentation.sequential.legs.default.colorHex` | 默认腿线主色 | 十六进制颜色字符串 | 建议传统定向紫红色 |
| `game.presentation.sequential.legs.default.widthScale` | 默认腿线宽度倍率 | `number` | 选填 |
| `game.presentation.sequential.legs.default.glowStrength` | 默认腿线光晕强度 | 建议 `0 ~ 1` | 选填 |
| `game.presentation.sequential.legs.completed.style` | 已完成腿线样式 | `classic-leg` `dashed-leg` `glow-leg` `progress-leg` | 建议弱化样式 |
| `game.presentation.sequential.legs.completed.colorHex` | 已完成腿线颜色 | 十六进制颜色字符串 | 建议灰色系 |
| `game.presentation.sequential.legs.completed.widthScale` | 已完成腿线宽度倍率 | `number` | 选填 |
| `game.presentation.sequential.legs.completed.glowStrength` | 已完成腿线光晕强度 | 建议 `0 ~ 1` | 选填 |
---
## 19. `game.presentation.track`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `game.presentation.track.mode` | 轨迹显示模式 | `none` `tail` `full` | 顺序打点默认建议 `full` |
| `game.presentation.track.style` | 轨迹风格 | `classic` `neon` | 当前默认 `neon` |
| `game.presentation.track.tailLength` | 拖尾长度档位 | `short` `medium` `long` | 仅 `tail` 模式重点使用 |
| `game.presentation.track.colorPreset` | 轨迹预设色盘 | `mint` `cyan` `sky` `blue` `violet` `pink` `orange` `yellow` | 未显式配置颜色时可走预设 |
| `game.presentation.track.tailMeters` | 拖尾长度(米) | `number` | 可覆盖 `tailLength` |
| `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` | 轨迹主色 | 十六进制颜色字符串 | 未配置时回退到 `colorPreset` |
| `game.presentation.track.headColorHex` | 轨迹头部高亮色 | 十六进制颜色字符串 | 未配置时回退到 `colorPreset` |
| `game.presentation.track.widthPx` | 轨迹基础宽度 | `number` | 选填 |
| `game.presentation.track.headWidthPx` | 轨迹头部宽度 | `number` | 选填 |
| `game.presentation.track.glowStrength` | 轨迹光晕强度 | 建议 `0 ~ 1` | 选填 |
---
## 20. `game.presentation.gpsMarker`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `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 点主色 | 十六进制颜色字符串 | 未配置时回退到 `colorPreset` |
| `game.presentation.gpsMarker.ringColorHex` | GPS 点外环颜色 | 十六进制颜色字符串 | 未配置时回退到 `colorPreset` |
| `game.presentation.gpsMarker.indicatorColorHex` | 朝向指示颜色 | 十六进制颜色字符串 | 未配置时回退到 `colorPreset` |
| `game.presentation.gpsMarker.showHeadingIndicator` | 是否显示朝向小三角 | `true` / `false` | 默认 `true` |
| `game.presentation.gpsMarker.animationProfile` | GPS 点动画 profile | `minimal` `dynamic-runner` `warning-reactive` | 当前默认 `dynamic-runner` |
| `game.presentation.gpsMarker.logoUrl` | 中心贴片 logo 地址 | URL 字符串 | 选填 |
| `game.presentation.gpsMarker.logoMode` | logo 嵌入方式 | `center-badge` | 当前支持该值 |
---
## 21. `resources`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `resources.audioProfile` | 音效资源档 | `string` | 默认 `default` |
| `resources.contentProfile` | 内容资源档 | `string` | 默认 `default` |
| `resources.themeProfile` | 主题资源档 | `string` | 默认 `default-race` |
---
## 22. `debug`
| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
| --- | --- | --- | --- |
| `debug.allowModeSwitch` | 是否允许玩法切换调试 | `true` / `false` | 默认 `false` |
| `debug.allowMockInput` | 是否允许模拟输入 | `true` / `false` | 默认 `false` |
| `debug.allowSimulator` | 是否允许模拟器 | `true` / `false` | 默认 `false` |
---
## 23. 推荐阅读顺序
如果你是为了推进顺序打点开发,建议按这个顺序阅读:
1. [顺序打点规则说明文档](D:/dev/cmr-mini/doc/games/顺序打点/规则说明文档.md)
2. 本文档
3. [顺序打点最小配置模板](D:/dev/cmr-mini/doc/games/顺序打点/最小配置模板.md)
4. [当前最全配置模板](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
5. [顺序赛样例配置](D:/dev/cmr-mini/event/classic-sequential.json)