# 顺序打点游戏配置项
> 文档版本：v1.0
> 最后更新：2026-04-02


本文档用于汇总当前系统对 `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)