zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3b9117427e9adb2ed329d6bca9797e57877c1f5d
cmr-mini/doc/config-template-full-current.md

651 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 游戏配置全量模板（当前开发实现版）
本文档提供一份 **截至当前开发状态，客户端已实现或已正式消费的较完整配置模板**。
目标：
- 给后端、后台、联调一份“当前最全可用模板”
- 帮助梳理哪些字段已经生效
- 后续新增字段时，以这份模板持续补充
说明：
- 本模板优先以**当前客户端代码真实实现**为准
- 不是未来终态，只代表“当前这一版已经能消费的字段”
- 以顺序赛为主模板，同时说明积分赛差异点
---
## 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)
Reference in New Issue View Git Blame Copy Permalink