359 lines
18 KiB
Markdown
359 lines
18 KiB
Markdown
# 顺序打点游戏配置项
|
||
|
||
本文档用于汇总当前系统对 `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)
|
||
|