21 KiB
21 KiB
配置选项字典（当前实现版）
本文档用于整理 当前客户端已经消费或已经预留承载的配置项，作为事件配置、后台配置和联调时的统一参考。
目标：
- 明确目前哪些字段已经真正生效
- 明确每个字段的含义、类型、默认逻辑
- 给后续扩展留下统一维护入口
说明：
- 本文档优先以“当前代码真实实现”为准
- 未列出的字段，不代表未来不能加，只代表当前客户端未正式消费
- 后续每次新增配置能力，都应同步补充本文件
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 - 说明：点击内容的展示形态
pointStyle
- 类型：
string - 说明：单个控制点的样式覆盖，仅影响当前控制点
- 支持值：
classic-ringsolid-dotdouble-ringbadgepulse-core
pointColorHex
- 类型：
string - 说明：单个控制点的颜色覆盖，例如
#27ae60 - 备注：通常和
pointStyle一起使用，未配置时回退到玩法样式 profile
pointSizeScale
- 类型：
number - 说明：单个控制点的尺寸倍率覆盖
- 建议范围：
0.6 ~ 1.4 - 建议默认值：
1 - 备注：大于
1会放大点位，小于1会缩小点位
pointAccentRingScale
- 类型：
number - 说明：单个控制点强调环/外环的尺寸倍率
- 建议范围：
1.0 ~ 1.6 - 建议默认值：由样式 profile 决定
- 备注：适合当前点、高分点、终点这类需要更强层次感的点位
pointGlowStrength
- 类型：
number - 说明：单个控制点的光晕强度
- 建议范围：
0 ~ 1 - 建议默认值：
0 - 备注：
0为无光晕，越接近1光晕越明显
pointLabelScale
- 类型：
number - 说明：单个控制点编号文字的尺寸倍率
- 建议范围：
0.7 ~ 1.3 - 建议默认值：
1 - 备注：适合高价值点、终点、特殊活动点的编号强调
pointLabelColorHex
- 类型：
string - 说明：单个控制点编号文字颜色覆盖，例如
#ffffff - 备注：未配置时回退到样式系统默认标签颜色逻辑
- 当前支持：
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. game.presentation
game.presentation.sequential.controls.default
- 类型：
object - 说明：顺序赛普通未完成控制点的默认样式
- 支持字段：
style：classic-ring | solid-dot | double-ring | badge | pulse-corecolorHex：十六进制颜色，例如#cc006bsizeScale：点位尺寸倍率accentRingScale：强调环尺寸倍率glowStrength：点位光晕强度labelScale：编号文字尺寸倍率labelColorHex：编号文字颜色
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 - 说明：顺序赛终点样式
game.presentation.sequential.legs.default
- 类型：
object - 说明：顺序赛默认路线腿样式
- 支持字段：
style：classic-leg | dashed-leg | glow-leg | progress-legcolorHex：十六进制颜色widthScale：路线腿宽度倍率glowStrength：路线腿光晕强度
game.presentation.sequential.legs.completed
- 类型：
object - 说明：顺序赛已完成路线腿样式
playfield.legOverrides
-
类型：
object -
说明：对指定路线腿做局部样式覆盖
-
键名建议：
leg-1leg-2leg-3
-
字段：
style：classic-leg | dashed-leg | glow-leg | progress-legcolorHex：十六进制颜色widthScale：路线腿宽度倍率glowStrength：路线腿光晕强度
-
示例：
"legOverrides": {
"leg-2": {
"style": "glow-leg",
"colorHex": "#27ae60"
}
}
game.presentation.scoreO.controls.default
- 类型：
object - 说明：积分赛默认点位样式
game.presentation.scoreO.controls.focused
- 类型：
object - 说明：积分赛当前聚焦/选中点样式
game.presentation.scoreO.controls.collected
- 类型：
object - 说明：积分赛已收集点样式
game.presentation.scoreO.controls.start
- 类型：
object - 说明：积分赛起点样式
game.presentation.scoreO.controls.finish
- 类型：
object - 说明：积分赛终点样式
game.presentation.scoreO.controls.scoreBands
-
类型：
array -
说明：积分赛按分值档位映射点位颜色和样式
-
数组项字段：
min：分值下界，含max：分值上界，含style：classic-ring | solid-dot | double-ring | badge | pulse-corecolorHex：十六进制颜色sizeScale：该积分档位的点位尺寸倍率accentRingScale：该积分档位的强调环倍率glowStrength：该积分档位的光晕强度labelScale：该积分档位的编号文字尺寸倍率labelColorHex：该积分档位的编号文字颜色
-
示例：
"presentation": {
"scoreO": {
"controls": {
"scoreBands": [
{ "min": 0, "max": 19, "style": "classic-ring", "colorHex": "#56ccf2" },
{ "min": 20, "max": 49, "style": "double-ring", "colorHex": "#f2c94c" },
{ "min": 50, "max": 999999, "style": "badge", "colorHex": "#eb5757" }
]
}
}
}
20. game.presentation.track
- 类型：
object - 说明：用户轨迹显示策略与样式配置
game.presentation.track.mode
- 类型：
string - 说明：轨迹显示模式
- 当前支持：
none：不显示轨迹tail：彗尾拖尾full：全轨迹
- 建议默认值：
- 顺序赛：
full - 积分赛：
tail
- 顺序赛：
game.presentation.track.style
- 类型：
string - 说明：轨迹风格 profile
- 当前支持：
classicneon
- 当前默认值：
neon
game.presentation.track.tailLength
- 类型：
string - 说明：拖尾基础长度档位
- 当前支持：
shortmediumlong
- 备注：
- 实际显示长度会继续按移动速度动态变化
- 跑得越快，尾巴越长
- 跑得越慢，尾巴越短
game.presentation.track.colorPreset
- 类型：
string - 说明：轨迹亮色调色盘
- 当前支持：
mintcyanskybluevioletpinkorangeyellow
- 备注：
- 运行时会在此基础上根据速度和心率张力自动提亮头部颜色与光晕
game.presentation.track.tailMeters
- 类型：
number - 说明：拖尾基础长度（米）
- 备注：
- 若未显式配置，则按
tailLength自动映射
- 若未显式配置，则按
game.presentation.track.tailMaxSeconds
- 类型：
number - 说明：拖尾最大时间窗口（秒）
game.presentation.track.fadeOutWhenStill
- 类型：
boolean - 说明：静止后是否逐步收尾消失
game.presentation.track.stillSpeedKmh
- 类型：
number - 说明：低于该速度时进入静止收尾逻辑
game.presentation.track.fadeOutDurationMs
- 类型：
number - 说明：静止后拖尾完全淡出的时长（毫秒）
game.presentation.track.colorHex
- 类型：
string - 说明：轨迹主色
- 备注：
- 未配置时按
colorPreset自动映射
- 未配置时按
game.presentation.track.headColorHex
- 类型：
string - 说明：轨迹头部高亮颜色
- 备注：
- 未配置时按
colorPreset自动映射
- 未配置时按
game.presentation.track.widthPx
- 类型：
number - 说明：轨迹基础宽度
game.presentation.track.headWidthPx
- 类型：
number - 说明：轨迹头部高亮宽度
game.presentation.track.glowStrength
- 类型：
number - 说明：轨迹光晕强度
- 备注：
standard / lite会自动做 glow 强度降级
21. game.presentation.gpsMarker
- 类型：
object - 说明：GPS 定位点显示、尺寸、颜色、朝向指示和品牌化扩展配置
game.presentation.gpsMarker.visible
- 类型：
boolean - 说明：是否显示 GPS 定位点
- 当前默认值：
true
game.presentation.gpsMarker.style
- 类型：
string - 说明：GPS 点基础样式
- 当前支持：
dotbeacondiscbadge
- 当前默认值：
beacon
game.presentation.gpsMarker.size
- 类型：
string - 说明：GPS 点整体大小档位
- 当前支持：
smallmediumlarge
- 当前默认值：
medium
game.presentation.gpsMarker.colorPreset
- 类型：
string - 说明：GPS 点亮色调色盘
- 当前支持：
mintcyanskybluevioletpinkorangeyellow
- 当前默认值：
cyan
game.presentation.gpsMarker.colorHex
- 类型：
string - 说明：GPS 点主色
- 备注：
- 未配置时按
colorPreset自动映射
- 未配置时按
game.presentation.gpsMarker.ringColorHex
- 类型：
string - 说明：GPS 点外圈颜色
- 备注：
- 未配置时按
colorPreset自动映射
- 未配置时按
game.presentation.gpsMarker.indicatorColorHex
- 类型：
string - 说明：朝向小三角颜色
- 备注：
- 未配置时按
colorPreset自动映射
- 未配置时按
game.presentation.gpsMarker.showHeadingIndicator
- 类型：
boolean - 说明：是否显示跟随朝向旋转的小三角
- 当前默认值：
true - 备注：
- 运行时会结合朝向可信度自动降低透明度
game.presentation.gpsMarker.animationProfile
- 类型：
string - 说明：GPS 点动画 profile
- 当前支持：
minimaldynamic-runnerwarning-reactive
- 当前默认值：
dynamic-runner - 备注：
- 第一阶段主要影响静止、移动、高速和高压状态下的动势强弱
- 未配置时使用系统默认动画逻辑
game.presentation.gpsMarker.logoUrl
- 类型：
string - 说明：品牌 logo 资源地址
- 当前状态：已支持中心贴片
- 备注：
- logo 作为中心贴片嵌入 GPS 点，不直接替代定位点
- 建议使用透明背景正方形资源
game.presentation.gpsMarker.logoMode
- 类型：
string - 说明：logo 嵌入方式
- 当前支持：
center-badge
- 当前状态：已支持
22. 当前默认逻辑说明
当前客户端对配置的处理原则是：
- 能有默认值的尽量给默认值
- 控制点内容类字段缺失时走默认文案
clickTitle/clickBody缺失时回退到title/body- 自动打点模式下不自动弹内容
- 内容优先级未配置时使用普通点
1、终点2
也就是说：
大部分配置项都不是强制必填，先保证主骨架完整即可。
23. 维护约定
后续每次新增配置项时，应同步更新：
- 本文档
- 默认模板文档
event目录下的配置样例
这样可以保证：
- 服务端可对照
- 后台可录入
- 客户端联调时有统一参考