顺序打点游戏配置项
文档版本：v1.0
最后更新：2026-04-02 08:28:05
本文档用于汇总当前系统对 classic-sequential 的已支持可配置项，便于产品、客户端、服务端、后台录入和联调统一对照。
目标：
- 列出顺序打点当前可配置的字段名
- 说明每个字段的作用
- 说明字段可选项或取值范围
- 标注推荐默认值或当前默认逻辑
说明：
- 本文档只聚焦
classic-sequential
- 以当前实现和现有文档口径为准
- 如果你需要看跨玩法的完整字段字典，请继续参考 配置选项字典
1. 顶层结构
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. 推荐阅读顺序
如果你是为了推进顺序打点开发，建议按这个顺序阅读：
- 顺序打点规则说明文档
- 本文档
- 顺序打点最小配置模板
- 当前最全配置模板
- 顺序赛样例配置
