# 配置选项字典（当前实现版） 本文档用于整理 **当前客户端已经消费或已经预留承载的配置项**，作为事件配置、后台配置和联调时的统一参考。 目标： - 明确目前哪些字段已经真正生效 - 明确每个字段的含义、类型、默认逻辑 - 给后续扩展留下统一维护入口 说明： - 本文档优先以“当前代码真实实现”为准 - 未列出的字段，不代表未来不能加，只代表当前客户端未正式消费 - 后续每次新增配置能力，都应同步补充本文件 --- ## 1. 顶层结构 当前推荐结构： ```json { "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` - 说明：空间对象类型 - 当前推荐值： - `course` - `control-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` - 说明：打点完成后自动弹出的标题 #### `body` - 类型：`string` - 说明：打点完成后自动弹出的正文 #### `clickTitle` - 类型：`string` - 说明：点击控制点时弹出的标题 - 默认逻辑：未配置时回退到 `title` #### `clickBody` - 类型：`string` - 说明：点击控制点时弹出的正文 - 默认逻辑：未配置时回退到 `body` #### `autoPopup` - 类型：`boolean` - 说明：完成该点后是否自动弹出内容 - 建议默认值：`true` - 特殊逻辑：如果当前玩法是自动打点，即 `game.punch.policy = "enter"`，则无论这里如何配置，**都不自动弹出** #### `once` - 类型：`boolean` - 说明：该内容是否本局只自动展示一次 - 建议默认值：`false` #### `priority` - 类型：`number` - 说明：内容优先级，越大越高 - 建议默认值： - 普通点：`1` - 终点：`2` ### 6.3 示例 ```json "controlOverrides": { "start-1": { "title": "比赛开始", "body": "从这里出发，先熟悉地图方向。", "autoPopup": true, "once": true, "priority": 1, "clickTitle": "起点说明", "clickBody": "点击起点可再次查看起跑说明。" }, "control-2": { "score": 20, "title": "教学楼南侧", "body": "这里是重要转折点。", "autoPopup": false, "once": true, "priority": 1, "clickTitle": "教学楼南侧", "clickBody": "这个点配置成点击查看。" }, "finish-1": { "title": "比赛结束", "body": "恭喜完成本次路线。", "autoPopup": true, "once": true, "priority": 2, "clickTitle": "终点说明", "clickBody": "点击终点可再次查看结束说明。" } } ``` --- ## 7. `game` 字段 ### `game.mode` - 类型：`string` - 说明：玩法类型 - 当前支持： - `classic-sequential` - `score-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-confirm` - `enter` - 建议默认值：`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. 维护约定 后续每次新增配置项时，应同步更新： 1. 本文档 2. 默认模板文档 3. `event` 目录下的配置样例 这样可以保证： - 服务端可对照 - 后台可录入 - 客户端联调时有统一参考