config-option-dictionary.md 12 KB
配置选项字典（当前实现版）
本文档用于整理 当前客户端已经消费或已经预留承载的配置项，作为事件配置、后台配置和联调时的统一参考。
目标：
- 明确目前哪些字段已经真正生效
- 明确每个字段的含义、类型、默认逻辑
- 给后续扩展留下统一维护入口
说明：
- 本文档优先以“当前代码真实实现”为准
- 未列出的字段，不代表未来不能加，只代表当前客户端未正式消费
- 后续每次新增配置能力，都应同步补充本文件
1. 顶层结构
当前推荐结构：
{
"schemaVersion": "1",
"version": "2026.03.27",
"app": {},
"map": {},
"playfield": {},
"game": {},
"resources": {},
"debug": {}
}
2. 顶层字段字典
schemaVersion
- 类型：
string - 说明：配置结构版本
- 建议默认值：
"1"
version
- 类型：
string - 说明：当前配置内容版本
- 建议默认值：日期或发布版本号，例如
2026.03.27
app
- 类型：
object - 说明：活动级基础信息
map
- 类型：
object - 说明：地图底座信息
playfield
- 类型：
object - 说明：玩法空间对象与内容覆盖
game
- 类型：
object - 说明：玩法规则与局流程
resources
- 类型：
object - 说明：资源 profile 引用
debug
- 类型：
object - 说明：调试开关
3. app 字段
app.id
- 类型：
string - 说明：活动或配置实例 id
- 示例：
"sample-classic-001"
app.title
- 类型：
string - 说明：活动标题 / 比赛名称
- 示例：
"顺序赛示例"
app.locale
- 类型：
string - 说明：语言环境
- 建议默认值：
"zh-CN"
4. map 字段
map.tiles
- 类型：
string - 说明：瓦片根路径
- 必填：是
map.mapmeta
- 类型：
string - 说明：地图 meta 文件地址
- 必填：是
map.declination
- 类型：
number - 说明：磁偏角
- 示例：
6.91 - 备注：当前会影响真北/磁北换算
map.initialView.zoom
- 类型：
number - 说明：初始缩放级别
- 建议默认值：
17
5. playfield 字段
playfield.kind
- 类型：
string - 说明：空间对象类型
- 当前推荐值：
coursecontrol-set
playfield.source.type
- 类型：
string - 说明：空间底稿来源类型
- 当前推荐值：
kml
playfield.source.url
- 类型：
string - 说明：KML 地址
- 必填：是
playfield.CPRadius
- 类型：
number - 说明：检查点绘制半径
- 建议默认值：
6
playfield.metadata.title
- 类型：
string - 说明：路线或控制点集标题
playfield.metadata.code
- 类型：
string - 说明：路线或控制点集编码
6. playfield.controlOverrides
playfield.controlOverrides 用于对起点、检查点、终点做内容或分值覆盖。
6.1 key 命名规则
- 起点：
start-1 - 普通检查点：
control-1、control-2、control-3 - 终点：
finish-1
6.2 当前支持字段
score
- 类型：
number - 说明：积分赛控制点分值
- 适用：积分赛
title
- 类型：
string - 说明：打点完成后自动弹出的标题
template
- 类型：
string - 说明：原生内容卡模板
- 当前支持：
minimalstoryfocus
- 建议默认值：
- 起点/终点：
focus - 普通点：
story
- 起点/终点：
body
- 类型：
string - 说明：打点完成后自动弹出的正文
clickTitle
- 类型：
string - 说明：点击控制点时弹出的标题
- 默认逻辑：未配置时回退到
title
clickBody
- 类型：
string - 说明：点击控制点时弹出的正文
- 默认逻辑：未配置时回退到
body
autoPopup
- 类型：
boolean - 说明：完成该点后是否自动弹出内容
- 建议默认值：
true - 特殊逻辑：如果当前玩法是自动打点，即
game.punch.policy = "enter"，则无论这里如何配置，都不自动弹出
once
- 类型：
boolean - 说明：该内容是否本局只自动展示一次
- 建议默认值：
false
priority
- 类型：
number - 说明：内容优先级，越大越高
- 建议默认值：
- 普通点：
1 - 终点：
2
- 普通点：
contentExperience
- 类型：
object - 说明：打点完成后使用的体验承载配置
- 当前支持：
nativeh5
contentExperience.type
- 类型：
string - 说明：自动弹出内容的承载方式
- 当前支持：
nativeh5
contentExperience.url
- 类型：
string - 说明：当
type = "h5"时对应的 H5 页面地址
contentExperience.bridge
- 类型：
string - 说明：H5 bridge 版本
- 建议默认值：
"content-v1"
contentExperience.presentation
- 类型：
string - 说明：H5 内容的展示形态
- 当前支持：
sheetdialogfullscreen
- 建议默认值：
sheet
clickExperience
- 类型：
object - 说明：点击控制点时使用的体验承载配置
- 当前支持：
nativeh5
clickExperience.type
- 类型：
string - 说明：点击内容的承载方式
- 当前支持：
nativeh5
clickExperience.url
- 类型：
string - 说明：当
type = "h5"时对应的 H5 页面地址
clickExperience.bridge
- 类型：
string - 说明：H5 bridge 版本
- 建议默认值：
"content-v1"
clickExperience.presentation
- 类型：
string - 说明：点击内容的展示形态
- 当前支持：
sheetdialogfullscreen
- 建议默认值：
sheet
6.3 示例
"controlOverrides": {
"start-1": {
"template": "focus",
"title": "比赛开始",
"body": "从这里出发，先熟悉地图方向。",
"autoPopup": true,
"once": true,
"priority": 1,
"clickTitle": "起点说明",
"clickBody": "点击起点可再次查看起跑说明。"
},
"control-2": {
"template": "minimal",
"score": 20,
"title": "教学楼南侧",
"body": "这里是重要转折点。",
"autoPopup": false,
"once": true,
"priority": 1,
"clickTitle": "教学楼南侧",
"clickBody": "这个点配置成点击查看。",
"contentExperience": {
"type": "h5",
"url": "https://example.com/content/control-2",
"bridge": "content-v1",
"presentation": "sheet"
},
"clickExperience": {
"type": "h5",
"url": "https://example.com/content/control-2-click",
"bridge": "content-v1",
"presentation": "dialog"
}
},
"finish-1": {
"template": "focus",
"title": "比赛结束",
"body": "恭喜完成本次路线。",
"autoPopup": true,
"once": true,
"priority": 2,
"clickTitle": "终点说明",
"clickBody": "点击终点可再次查看结束说明。"
}
}
7. game 字段
game.mode
- 类型：
string - 说明：玩法类型
- 当前支持：
classic-sequentialscore-o
game.rulesVersion
- 类型：
string - 说明：规则版本
- 建议默认值：
"1"
8. game.session
game.session.startManually
- 类型：
boolean - 说明：是否需要手动点击开始
- 建议默认值：
true
game.session.requiresStartPunch
- 类型：
boolean - 说明：是否必须完成起点打卡
- 建议默认值：
- 顺序赛：
true - 积分赛：
true
- 顺序赛：
game.session.requiresFinishPunch
- 类型：
boolean - 说明：是否必须完成终点打卡
- 建议默认值：
- 顺序赛：
true - 积分赛：
false
- 顺序赛：
game.session.autoFinishOnLastControl
- 类型：
boolean - 说明：是否打完最后控制点自动结束
- 建议默认值：
false
game.session.maxDurationSec
- 类型：
number - 说明：最大比赛时长，单位秒
- 建议默认值：
5400
9. game.punch
game.punch.policy
- 类型：
string - 说明：打点策略
- 当前支持：
enter-confirmenter
- 建议默认值：
enter-confirm
game.punch.radiusMeters
- 类型：
number - 说明：打点半径
- 建议默认值：
5
game.punch.requiresFocusSelection
- 类型：
boolean - 说明：积分赛是否需要先选中目标再打卡
- 建议默认值：
- 顺序赛：
false - 积分赛：
false
- 顺序赛：
10. game.sequence.skip
仅顺序赛相关。
game.sequence.skip.enabled
- 类型：
boolean - 说明：是否允许跳点
- 建议默认值：
false
game.sequence.skip.radiusMeters
- 类型：
number - 说明：跳点半径
- 建议默认值：
30
game.sequence.skip.requiresConfirm
- 类型：
boolean - 说明：跳点是否需要确认
- 建议默认值：
true
11. game.scoring
game.scoring.type
- 类型：
string - 说明：积分模型
- 当前推荐值：
score
game.scoring.defaultControlScore
- 类型：
number - 说明：积分赛默认控制点分值
- 建议默认值：
10
12. game.guidance
game.guidance.showLegs
- 类型：
boolean - 说明：是否显示腿线
- 建议默认值：
- 顺序赛：
true - 积分赛：
false
- 顺序赛：
game.guidance.legAnimation
- 类型：
boolean - 说明：是否显示腿线动画
- 建议默认值：
- 顺序赛：
true - 积分赛：
false
- 顺序赛：
game.guidance.allowFocusSelection
- 类型：
boolean - 说明：是否允许地图点击选择目标点
- 建议默认值：
- 顺序赛：
false - 积分赛：
true
- 顺序赛：
13. game.visibility
game.visibility.revealFullPlayfieldAfterStartPunch
- 类型：
boolean - 说明：起点打卡后是否显示完整路线/控制点集合
- 建议默认值：
true
14. game.finish
game.finish.finishControlAlwaysSelectable
- 类型：
boolean - 说明：终点是否始终可选
- 建议默认值：
- 顺序赛：
false - 积分赛：
true
- 顺序赛：
15. game.telemetry.heartRate
age
- 类型：
number - 说明：年龄
- 建议默认值：
30
restingHeartRateBpm
- 类型：
number - 说明：静息心率
- 建议默认值：
62
userWeightKg
- 类型：
number - 说明：体重
- 建议默认值：
65
16. game.feedback
game.feedback.audioProfile
- 类型：
string - 说明：音频反馈 profile
- 建议默认值：
default
game.feedback.hapticsProfile
- 类型：
string - 说明：震动反馈 profile
- 建议默认值：
default
game.feedback.uiEffectsProfile
- 类型：
string - 说明：UI 动效 profile
- 建议默认值：
default
17. resources
resources.audioProfile
- 类型：
string - 建议默认值：
default
resources.contentProfile
- 类型：
string - 建议默认值：
default
resources.themeProfile
- 类型：
string - 建议默认值：
default-race
18. debug
debug.allowModeSwitch
- 类型：
boolean - 建议默认值：
false
debug.allowMockInput
- 类型：
boolean - 建议默认值：
false
debug.allowSimulator
- 类型：
boolean - 建议默认值：
false
19. 当前默认逻辑说明
当前客户端对配置的处理原则是：
- 能有默认值的尽量给默认值
- 控制点内容类字段缺失时走默认文案
clickTitle/clickBody缺失时回退到title/body- 自动打点模式下不自动弹内容
- 内容优先级未配置时使用普通点
1、终点2
也就是说：
大部分配置项都不是强制必填，先保证主骨架完整即可。
20. 维护约定
后续每次新增配置项时，应同步更新：
- 本文档
- 默认模板文档
event目录下的配置样例
这样可以保证：
- 服务端可对照
- 后台可录入
- 客户端联调时有统一参考