# 游戏配置全量模板（当前开发实现版） 本文档提供一份 **截至当前开发状态，客户端已实现或已正式消费的较完整配置模板**。 目标： - 给后端、后台、联调一份“当前最全可用模板” - 帮助梳理哪些字段已经生效 - 后续新增字段时，以这份模板持续补充 说明： - 本模板优先以**当前客户端代码真实实现**为准 - 不是未来终态，只代表“当前这一版已经能消费的字段” - 以顺序赛为主模板，同时说明积分赛差异点 --- ## 1. 当前最全模板 ```json { "schemaVersion": "1", "version": "2026.03.30", "app": { "id": "sample-full-001", "title": "完整配置示例", "locale": "zh-CN" }, "map": { "tiles": "../map/lxcb-001/tiles/", "mapmeta": "../map/lxcb-001/tiles/meta.json", "declination": 6.91, "initialView": { "zoom": 17 } }, "playfield": { "kind": "course", "source": { "type": "kml", "url": "../kml/lxcb-001/10/c01.kml" }, "CPRadius": 6, "metadata": { "title": "完整路线示例", "code": "full-001" }, "controlOverrides": { "start-1": { "template": "focus", "title": "比赛开始", "body": "从这里触发，先熟悉地图方向。", "clickTitle": "起点说明", "clickBody": "点击起点可再次查看起跑说明。", "autoPopup": true, "once": true, "priority": 1, "contentExperience": { "type": "h5", "url": "https://example.com/content/start-1", "bridge": "content-v1", "presentation": "dialog" }, "clickExperience": { "type": "h5", "url": "https://example.com/content/start-1-click", "bridge": "content-v1", "presentation": "dialog" } }, "control-1": { "template": "story", "score": 10, "title": "第一检查点", "body": "完成该点后继续推进。", "clickTitle": "第一检查点", "clickBody": "点击查看该点的补充说明。", "autoPopup": true, "once": false, "priority": 1, "contentExperience": { "type": "h5", "url": "https://example.com/content/control-1", "bridge": "content-v1", "presentation": "dialog" }, "clickExperience": { "type": "h5", "url": "https://example.com/content/control-1-click", "bridge": "content-v1", "presentation": "dialog" } }, "control-2": { "template": "minimal", "title": "第二检查点", "body": "这个点配置成手动查看内容。", "clickTitle": "第二检查点", "clickBody": "点击查看手动内容。", "autoPopup": false, "once": true, "priority": 1 }, "finish-1": { "template": "focus", "title": "比赛结束", "body": "恭喜完成本次路线。", "clickTitle": "终点说明", "clickBody": "点击终点可再次查看结束说明。", "autoPopup": true, "once": true, "priority": 2, "clickExperience": { "type": "h5", "url": "https://example.com/content/finish-1-click", "bridge": "content-v1", "presentation": "dialog" } } } }, "game": { "mode": "classic-sequential", "rulesVersion": "1", "session": { "startManually": true, "requiresStartPunch": true, "requiresFinishPunch": true, "autoFinishOnLastControl": false, "maxDurationSec": 5400 }, "punch": { "policy": "enter-confirm", "radiusMeters": 5, "requiresFocusSelection": false }, "sequence": { "skip": { "enabled": true, "radiusMeters": 30, "requiresConfirm": true } }, "scoring": { "type": "score", "defaultControlScore": 10 }, "guidance": { "showLegs": true, "legAnimation": true, "allowFocusSelection": false }, "visibility": { "revealFullPlayfieldAfterStartPunch": true }, "finish": { "finishControlAlwaysSelectable": false }, "telemetry": { "heartRate": { "age": 30, "restingHeartRateBpm": 62, "userWeightKg": 65 } }, "feedback": { "audioProfile": "default", "hapticsProfile": "default", "uiEffectsProfile": "default" } }, "resources": { "audioProfile": "default", "contentProfile": "default", "themeProfile": "default-race" }, "debug": { "allowModeSwitch": false, "allowMockInput": false, "allowSimulator": false } } ``` --- ## 2. 顶层字段说明 ### `schemaVersion` - 类型：`string` - 必填：是 - 说明：配置结构版本 - 当前建议值：`"1"` ### `version` - 类型：`string` - 必填：是 - 说明：配置内容版本号 ### `app` - 类型：`object` - 必填：是 - 说明：活动级基础信息 ### `map` - 类型：`object` - 必填：是 - 说明：地图底座信息 ### `playfield` - 类型：`object` - 必填：是 - 说明：点位空间、内容覆盖、点位元信息 ### `game` - 类型：`object` - 必填：是 - 说明：玩法规则与对局流程 ### `resources` - 类型：`object` - 必填：否 - 说明：资源 profile 引用 ### `debug` - 类型：`object` - 必填：否 - 说明：调试开关 --- ## 3. `app` 字段说明 ### `app.id` - 类型：`string` - 说明：活动配置 ID ### `app.title` - 类型：`string` - 说明：活动标题 / 比赛名称 ### `app.locale` - 类型：`string` - 说明：语言环境 - 当前常用值：`zh-CN` --- ## 4. `map` 字段说明 ### `map.tiles` - 类型：`string` - 必填：是 - 说明：瓦片根路径 ### `map.mapmeta` - 类型：`string` - 必填：是 - 说明：地图 meta 文件路径 ### `map.declination` - 类型：`number` - 必填：否 - 说明：磁偏角 - 影响：真北 / 磁北换算 ### `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` 字段说明 ### key 命名规则 - 起点：`start-1` - 普通点：`control-1`、`control-2`、`control-3` - 终点：`finish-1` ### 当前支持字段 #### `template` - 类型：`string` - 说明：原生内容卡模板 - 当前支持： - `minimal` - `story` - `focus` #### `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` #### `contentExperience` - 类型：`object` - 说明：打点完成后的 H5 详情/互动扩展配置 - 注意：当前不是直接顶替原生弹窗，而是通过原生卡片 CTA 进入 #### `contentExperience.type` - 类型：`string` - 说明：内容扩展承载类型 - 当前支持： - `native` - `h5` #### `contentExperience.url` - 类型：`string` - 说明：H5 详情页地址 #### `contentExperience.bridge` - 类型：`string` - 说明：Bridge 协议版本 - 当前推荐值：`content-v1` #### `contentExperience.presentation` - 类型：`string` - 说明：H5 内容页展示形态 - 当前支持值： - `dialog` - `fullscreen` #### `clickExperience` - 类型：`object` - 说明：点击点位时的 H5 详情/互动扩展配置 - 规则同 `contentExperience` --- ## 7. `game` 字段说明 ### `game.mode` - 类型：`string` - 说明：玩法模式 - 当前常用值： - `classic-sequential` - `score-o` ### `game.rulesVersion` - 类型：`string` - 说明：规则版本号 ### `game.session.startManually` - 类型：`boolean` - 说明：是否手动开始 ### `game.session.requiresStartPunch` - 类型：`boolean` - 说明：是否必须打起点 ### `game.session.requiresFinishPunch` - 类型：`boolean` - 说明：是否必须打终点 ### `game.session.autoFinishOnLastControl` - 类型：`boolean` - 说明：最后一个目标完成后是否自动结束 ### `game.session.maxDurationSec` - 类型：`number` - 说明：最大对局时长，单位秒 ### `game.punch.policy` - 类型：`string` - 说明：打点策略 - 当前常用值： - `enter-confirm` - `enter` ### `game.punch.radiusMeters` - 类型：`number` - 说明：打点半径，单位米 ### `game.punch.requiresFocusSelection` - 类型：`boolean` - 说明：是否需要先聚焦/选中目标再打点 ### `game.sequence.skip.enabled` - 类型：`boolean` - 说明：顺序赛是否允许跳点 ### `game.sequence.skip.radiusMeters` - 类型：`number` - 说明：跳点可用半径 ### `game.sequence.skip.requiresConfirm` - 类型：`boolean` - 说明：跳点是否需要二次确认 ### `game.scoring.type` - 类型：`string` - 说明：积分模式类型 - 当前常用值：`score` ### `game.scoring.defaultControlScore` - 类型：`number` - 说明：默认控制点分值 ### `game.guidance.showLegs` - 类型：`boolean` - 说明：是否显示路线腿段 ### `game.guidance.legAnimation` - 类型：`boolean` - 说明：是否开启路线腿段动画 ### `game.guidance.allowFocusSelection` - 类型：`boolean` - 说明：是否允许点击点位选中目标 ### `game.visibility.revealFullPlayfieldAfterStartPunch` - 类型：`boolean` - 说明：打完起点后是否显示完整场地 ### `game.finish.finishControlAlwaysSelectable` - 类型：`boolean` - 说明：终点是否始终可选 ### `game.telemetry.heartRate.age` - 类型：`number` - 说明：用户年龄 ### `game.telemetry.heartRate.restingHeartRateBpm` - 类型：`number` - 说明：静息心率 ### `game.telemetry.heartRate.userWeightKg` - 类型：`number` - 说明：体重，单位公斤 ### `game.feedback.audioProfile` - 类型：`string` - 说明：音效 profile ### `game.feedback.hapticsProfile` - 类型：`string` - 说明：震动 profile ### `game.feedback.uiEffectsProfile` - 类型：`string` - 说明：UI 动效 profile --- ## 8. `resources` 字段说明 ### `resources.audioProfile` - 类型：`string` - 说明：资源音效配置档 ### `resources.contentProfile` - 类型：`string` - 说明：内容资源配置档 ### `resources.themeProfile` - 类型：`string` - 说明：主题配置档 --- ## 9. `debug` 字段说明 ### `debug.allowModeSwitch` - 类型：`boolean` - 说明：是否允许玩法切换调试 ### `debug.allowMockInput` - 类型：`boolean` - 说明：是否允许模拟输入 ### `debug.allowSimulator` - 类型：`boolean` - 说明：是否允许模拟器调试 --- ## 10. 积分赛差异点 如果使用积分赛，通常要修改这几项： ```json { "playfield": { "kind": "control-set" }, "game": { "mode": "score-o", "guidance": { "showLegs": false, "legAnimation": false, "allowFocusSelection": true }, "finish": { "finishControlAlwaysSelectable": true } } } ``` 并在 `playfield.controlOverrides` 中为普通点补： - `score` --- ## 11. 推荐配套阅读 - [D:\dev\cmr-mini\doc\config-template-minimal-game.md](D:/dev/cmr-mini/doc/config-template-minimal-game.md) - [D:\dev\cmr-mini\doc\config-option-dictionary.md](D:/dev/cmr-mini/doc/config-option-dictionary.md) - [D:\dev\cmr-mini\doc\config-docs-index.md](D:/dev/cmr-mini/doc/config-docs-index.md)