1299 lines
28 KiB
Markdown
1299 lines
28 KiB
Markdown
# 配置选项字典（当前实现版）
|
||
> 文档版本：v1.0
|
||
> 最后更新：2026-04-02 08:28:05
|
||
|
||
|
||
本文档用于整理 **当前客户端已经消费或已经预留承载的配置项**，作为事件配置、后台配置和联调时的统一参考。
|
||
|
||
目标：
|
||
|
||
- 明确目前哪些字段已经真正生效
|
||
- 明确每个字段的含义、类型、默认逻辑
|
||
- 给后续扩展留下统一维护入口
|
||
|
||
说明：
|
||
|
||
- 本文档优先以“当前代码真实实现”为准
|
||
- 未列出的字段，不代表未来不能加，只代表当前客户端未正式消费
|
||
- 后续每次新增配置能力，都应同步补充本文件
|
||
|
||
---
|
||
|
||
## 1. 顶层结构
|
||
|
||
当前推荐结构：
|
||
|
||
```json
|
||
{
|
||
"schemaVersion": "1",
|
||
"version": "2026.03.31",
|
||
"app": {},
|
||
"settings": {},
|
||
"map": {},
|
||
"playfield": {},
|
||
"game": {},
|
||
"resources": {},
|
||
"debug": {}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 顶层字段字典
|
||
|
||
### `schemaVersion`
|
||
|
||
- 类型：`string`
|
||
- 说明：配置结构版本
|
||
- 建议默认值：`"1"`
|
||
|
||
### `version`
|
||
|
||
- 类型：`string`
|
||
- 说明：当前配置内容版本
|
||
- 建议默认值：日期或发布版本号，例如 `2026.03.27`
|
||
|
||
### `app`
|
||
|
||
- 类型：`object`
|
||
- 说明：活动级基础信息
|
||
|
||
### `settings`
|
||
|
||
- 类型：`object`
|
||
- 说明：系统设置页默认值与锁态配置
|
||
- 备注：只控制设置页公共项，不属于具体玩法规则本体
|
||
|
||
### `map`
|
||
|
||
- 类型：`object`
|
||
- 说明：地图底座信息
|
||
|
||
### `playfield`
|
||
|
||
- 类型：`object`
|
||
- 说明：玩法空间对象与内容覆盖
|
||
|
||
### `game`
|
||
|
||
- 类型：`object`
|
||
- 说明：玩法规则与局流程
|
||
|
||
### `resources`
|
||
|
||
- 类型：`object`
|
||
- 说明：资源 profile 引用
|
||
|
||
### `debug`
|
||
|
||
- 类型：`object`
|
||
- 说明：调试开关
|
||
|
||
---
|
||
|
||
## `settings` 字段补充
|
||
|
||
推荐结构：
|
||
|
||
```json
|
||
{
|
||
"settings": {
|
||
"autoRotateEnabled": {
|
||
"value": true,
|
||
"isLocked": false
|
||
},
|
||
"trackDisplayMode": {
|
||
"value": "tail",
|
||
"isLocked": true
|
||
},
|
||
"gpsMarkerStyle": {
|
||
"value": "beacon",
|
||
"isLocked": false
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
规则：
|
||
|
||
- `value` 表示该设置项的活动默认值
|
||
- `isLocked` 表示该设置项是否允许玩家修改
|
||
- `value` 会和玩家本地持久化值一起参与解析
|
||
- `isLocked` 不持久化，只受系统默认值和活动配置控制
|
||
- 玩家不能在页面里修改锁态
|
||
- `isLocked` 只在当前游戏配置运行生命周期内生效；本局结束或主动退出后失效
|
||
|
||
---
|
||
|
||
## 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.controlDefaults` / `playfield.controlOverrides`
|
||
|
||
推荐优先使用：
|
||
|
||
- `playfield.controlDefaults`：活动级默认
|
||
- `playfield.controlOverrides`：单点重载
|
||
|
||
默认覆盖顺序：
|
||
|
||
`系统默认值 -> 玩法默认值 -> playfield.controlDefaults -> playfield.controlOverrides`
|
||
|
||
### 6.1 `playfield.controlDefaults`
|
||
|
||
- 类型：`object`
|
||
- 说明：普通检查点的活动级默认配置
|
||
- 适用：普通检查点，不直接作用于起点和终点
|
||
|
||
当前支持字段：
|
||
|
||
- `score`
|
||
- `template`
|
||
- `title`
|
||
- `body`
|
||
- `clickTitle`
|
||
- `clickBody`
|
||
- `autoPopup`
|
||
- `once`
|
||
- `priority`
|
||
- `ctas`
|
||
- `contentExperience`
|
||
- `clickExperience`
|
||
- `pointStyle`
|
||
- `pointColorHex`
|
||
- `pointSizeScale`
|
||
- `pointAccentRingScale`
|
||
- `pointGlowStrength`
|
||
- `pointLabelScale`
|
||
- `pointLabelColorHex`
|
||
|
||
### 6.2 `playfield.controlOverrides`
|
||
|
||
`playfield.controlOverrides` 用于对起点、检查点、终点做单点覆盖。
|
||
|
||
### 6.3 key 命名规则
|
||
|
||
- 起点：`start-1`
|
||
- 普通检查点：`control-1`、`control-2`、`control-3`
|
||
- 终点：`finish-1`
|
||
|
||
### 6.4 当前支持字段
|
||
|
||
#### `score`
|
||
|
||
- 类型：`number`
|
||
- 说明：积分赛控制点分值
|
||
- 适用：积分赛
|
||
- 备注：如果同时配置了 `playfield.controlDefaults.score`，则当前点以单点值为准
|
||
|
||
#### `title`
|
||
|
||
- 类型：`string`
|
||
- 说明：打点完成后自动弹出的标题
|
||
|
||
#### `template`
|
||
|
||
- 类型：`string`
|
||
- 说明：原生内容卡模板
|
||
- 当前支持：
|
||
- `minimal`
|
||
- `story`
|
||
- `focus`
|
||
- 建议默认值：
|
||
- 起点/终点：`focus`
|
||
- 普通点：`story`
|
||
|
||
#### `body`
|
||
|
||
- 类型：`string`
|
||
- 说明：打点完成后自动弹出的正文
|
||
|
||
#### `clickTitle`
|
||
|
||
- 类型：`string`
|
||
- 说明：点击控制点时弹出的标题
|
||
- 默认逻辑：最小模板下默认不启用；仅在显式配置点击内容能力时生效
|
||
|
||
#### `clickBody`
|
||
|
||
- 类型：`string`
|
||
- 说明：点击控制点时弹出的正文
|
||
- 默认逻辑：最小模板下默认不启用；仅在显式配置点击内容能力时生效
|
||
|
||
#### `autoPopup`
|
||
|
||
- 类型：`boolean`
|
||
- 说明：完成该点后是否自动弹出内容卡
|
||
- 建议默认值：最小模板下 `false`
|
||
- 特殊逻辑：如果当前玩法是自动打点，即 `game.punch.policy = "enter"`，则无论这里如何配置，**都不自动弹出**
|
||
- 补充说明：该字段只控制内容卡弹出
|
||
- 补充说明：系统默认白卡已改为“显式配置启用”，未开启 `autoPopup` 时，起点和普通点完成后不弹白卡
|
||
|
||
#### `once`
|
||
|
||
- 类型：`boolean`
|
||
- 说明：该内容是否本局只自动展示一次
|
||
- 建议默认值：`false`
|
||
|
||
#### `priority`
|
||
|
||
- 类型：`number`
|
||
- 说明：内容优先级，越大越高
|
||
- 建议默认值：
|
||
- 普通点：`1`
|
||
- 终点：`2`
|
||
|
||
#### `contentExperience`
|
||
|
||
- 类型：`object`
|
||
- 说明：打点完成后使用的体验承载配置
|
||
- 当前支持：
|
||
- `native`
|
||
- `h5`
|
||
|
||
#### `contentExperience.type`
|
||
|
||
- 类型：`string`
|
||
- 说明：自动弹出内容的承载方式
|
||
- 当前支持：
|
||
- `native`
|
||
- `h5`
|
||
|
||
#### `contentExperience.url`
|
||
|
||
- 类型：`string`
|
||
- 说明：当 `type = "h5"` 时对应的 H5 页面地址
|
||
|
||
#### `contentExperience.bridge`
|
||
|
||
- 类型：`string`
|
||
- 说明：H5 bridge 版本
|
||
- 建议默认值：`"content-v1"`
|
||
|
||
#### `contentExperience.presentation`
|
||
|
||
- 类型：`string`
|
||
- 说明：H5 内容的展示形态
|
||
- 当前运行建议：
|
||
- `fullscreen`
|
||
- 兼容历史值：
|
||
- `sheet`
|
||
- `dialog`
|
||
- 建议默认值：`fullscreen`
|
||
- 备注：经过真机验证，`web-view` 不再承担局部弹窗职责；当前应按“原生内容卡 + H5 全屏详情页/任务页”理解。
|
||
|
||
#### `clickExperience`
|
||
|
||
- 类型：`object`
|
||
- 说明：点击控制点时使用的体验承载配置
|
||
- 当前支持：
|
||
- `native`
|
||
- `h5`
|
||
|
||
#### `clickExperience.type`
|
||
|
||
- 类型：`string`
|
||
- 说明：点击内容的承载方式
|
||
- 当前支持：
|
||
- `native`
|
||
- `h5`
|
||
|
||
#### `clickExperience.url`
|
||
|
||
- 类型：`string`
|
||
- 说明：当 `type = "h5"` 时对应的 H5 页面地址
|
||
|
||
#### `clickExperience.bridge`
|
||
|
||
- 类型：`string`
|
||
- 说明：H5 bridge 版本
|
||
- 建议默认值：`"content-v1"`
|
||
|
||
#### `clickExperience.presentation`
|
||
|
||
- 类型：`string`
|
||
- 说明：点击内容的展示形态
|
||
- 当前运行建议：
|
||
- `fullscreen`
|
||
- 兼容历史值：
|
||
- `sheet`
|
||
- `dialog`
|
||
- 建议默认值：`fullscreen`
|
||
- 备注：点击详情页当前统一按整页 H5 处理，不再把 `web-view` 作为局部弹窗承载。
|
||
|
||
#### `pointStyle`
|
||
|
||
- 类型：`string`
|
||
- 说明：单个控制点的样式覆盖，仅影响当前控制点
|
||
- 支持值：
|
||
- `classic-ring`
|
||
- `solid-dot`
|
||
- `double-ring`
|
||
- `badge`
|
||
- `pulse-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`
|
||
- 备注：未配置时回退到样式系统默认标签颜色逻辑
|
||
|
||
### 6.3 示例
|
||
|
||
```json
|
||
"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": "fullscreen"
|
||
},
|
||
"clickExperience": {
|
||
"type": "h5",
|
||
"url": "https://example.com/content/control-2-click",
|
||
"bridge": "content-v1",
|
||
"presentation": "fullscreen"
|
||
}
|
||
},
|
||
"finish-1": {
|
||
"template": "focus",
|
||
"title": "比赛结束",
|
||
"body": "恭喜完成本次路线。",
|
||
"autoPopup": false,
|
||
"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`
|
||
- 说明：是否需要手动点击开始
|
||
- 建议默认值：
|
||
- 顺序赛：`false`
|
||
- 积分赛：`false`
|
||
- 备注：
|
||
- 进入页面后先进入待起跑态，通过开始点打卡正式开赛
|
||
|
||
### `game.session.requiresStartPunch`
|
||
|
||
- 类型：`boolean`
|
||
- 说明：是否必须完成起点打卡
|
||
- 建议默认值：
|
||
- 顺序赛：`true`
|
||
- 积分赛：`true`
|
||
|
||
### `game.session.requiresFinishPunch`
|
||
|
||
- 类型：`boolean`
|
||
- 说明：是否必须完成终点打卡
|
||
- 建议默认值：
|
||
- 顺序赛：`true`
|
||
- 积分赛：`false`
|
||
|
||
### `game.session.autoFinishOnLastControl`
|
||
|
||
- 类型：`boolean`
|
||
- 说明：是否打完最后控制点自动结束
|
||
- 建议默认值：`false`
|
||
|
||
### `game.session.minCompletedControlsBeforeFinish`
|
||
|
||
- 类型：`number`
|
||
- 说明：终点生效前至少需要完成的普通检查点数量
|
||
- 建议默认值：
|
||
- 顺序赛：`0`
|
||
- 积分赛：`1`
|
||
|
||
### `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`
|
||
- 说明：是否允许跳点
|
||
- 建议默认值：
|
||
- 顺序赛：`true`
|
||
- 积分赛：`false`
|
||
|
||
### `game.sequence.skip.radiusMeters`
|
||
|
||
- 类型：`number`
|
||
- 说明：跳点半径
|
||
- 建议默认值：
|
||
- 顺序赛：`game.punch.radiusMeters * 2`
|
||
|
||
### `game.sequence.skip.requiresConfirm`
|
||
|
||
- 类型：`boolean`
|
||
- 说明：跳点是否需要确认
|
||
- 建议默认值：`false`
|
||
|
||
---
|
||
|
||
## 11. `game.scoring`
|
||
|
||
### `game.scoring.type`
|
||
|
||
- 类型：`string`
|
||
- 说明：积分模型
|
||
- 当前推荐值：`score`
|
||
|
||
### `game.scoring.defaultControlScore`
|
||
|
||
- 类型：`number`
|
||
- 说明：普通控制点未单独配置时的默认基础分
|
||
- 建议默认值：
|
||
- 顺序赛：`1`
|
||
- 积分赛：`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`
|
||
|
||
### `game.audio.distantDistanceMeters`
|
||
|
||
- 类型：`number`
|
||
- 说明：远距离提示音的最大生效距离，超出该距离默认静默
|
||
- 建议默认值：`80`
|
||
|
||
### `game.audio.approachDistanceMeters`
|
||
|
||
- 类型：`number`
|
||
- 说明：接近提示音的最大生效距离
|
||
- 建议默认值：`20`
|
||
|
||
### `game.audio.readyDistanceMeters`
|
||
|
||
- 类型：`number`
|
||
- 说明：可打点提示音的最大生效距离
|
||
- 建议默认值：`5`
|
||
- 备注：
|
||
- 运行时不会小于 `game.punch.radiusMeters`
|
||
|
||
### `game.audio.cues["guidance:distant"].loopGapMs`
|
||
|
||
- 类型：`number`
|
||
- 说明：远距离提示音循环间隔，单位毫秒
|
||
- 建议默认值：`4800`
|
||
|
||
### `game.audio.cues["guidance:approaching"].loopGapMs`
|
||
|
||
- 类型：`number`
|
||
- 说明：接近提示音循环间隔，单位毫秒
|
||
- 建议默认值：`950`
|
||
|
||
### `game.audio.cues["guidance:ready"].loopGapMs`
|
||
|
||
- 类型：`number`
|
||
- 说明：可打点提示音循环间隔，单位毫秒
|
||
- 建议默认值：`650`
|
||
|
||
### `game.audio.cues["guidance:distant" | "guidance:approaching" | "guidance:ready"].volume`
|
||
|
||
- 类型：`number`
|
||
- 说明：三档距离提示音各自音量
|
||
- 建议范围：`0 ~ 1`
|
||
|
||
---
|
||
|
||
## 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-core`
|
||
- `colorHex`：十六进制颜色，例如 `#cc006b`
|
||
- `sizeScale`：点位尺寸倍率
|
||
- `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-leg`
|
||
- `colorHex`：十六进制颜色
|
||
- `widthScale`：路线腿宽度倍率
|
||
- `glowStrength`：路线腿光晕强度
|
||
- 备注：
|
||
- 默认建议使用传统定向运动紫红色系
|
||
- 默认配合电流动效使用
|
||
|
||
### `game.presentation.sequential.legs.completed`
|
||
|
||
- 类型：`object`
|
||
- 说明：顺序赛已完成路线腿样式
|
||
|
||
### `playfield.legOverrides`
|
||
|
||
- 类型：`object`
|
||
- 说明：对指定路线腿做局部样式覆盖
|
||
- 建议：优先使用 `playfield.legDefaults` 写整场腿线默认，再用 `legOverrides` 写单腿例外
|
||
|
||
### `playfield.legDefaults`
|
||
|
||
- 类型：`object`
|
||
- 说明：腿线的活动级默认样式
|
||
- 当前支持字段：
|
||
- `style`
|
||
- `colorHex`
|
||
- `widthScale`
|
||
- `glowStrength`
|
||
- 键名建议：
|
||
- `leg-1`
|
||
- `leg-2`
|
||
- `leg-3`
|
||
|
||
- 字段：
|
||
- `style`：`classic-leg | dashed-leg | glow-leg | progress-leg`
|
||
- `colorHex`：十六进制颜色
|
||
- `widthScale`：路线腿宽度倍率
|
||
- `glowStrength`：路线腿光晕强度
|
||
|
||
- 示例：
|
||
|
||
```json
|
||
"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-core`
|
||
- `colorHex`：十六进制颜色
|
||
- `sizeScale`：该积分档位的点位尺寸倍率
|
||
- `accentRingScale`：该积分档位的强调环倍率
|
||
- `glowStrength`：该积分档位的光晕强度
|
||
- `labelScale`：该积分档位的编号文字尺寸倍率
|
||
- `labelColorHex`：该积分档位的编号文字颜色
|
||
|
||
- 示例：
|
||
|
||
```json
|
||
"presentation": {
|
||
"scoreO": {
|
||
"controls": {
|
||
"scoreBands": [
|
||
{ "min": 0, "max": 19, "style": "classic-ring", "colorHex": "#56ccf2" },
|
||
{ "min": 20, "max": 49, "style": "classic-ring", "colorHex": "#f2c94c" },
|
||
{ "min": 50, "max": 999999, "style": "double-ring", "colorHex": "#eb5757" }
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 20. `game.presentation.track`
|
||
|
||
- 类型：`object`
|
||
- 说明：用户轨迹显示策略与样式配置
|
||
|
||
### `game.presentation.track.mode`
|
||
|
||
- 类型：`string`
|
||
- 说明：轨迹显示模式
|
||
- 当前支持：
|
||
- `none`：不显示轨迹
|
||
- `tail`：彗尾拖尾
|
||
- `full`：全轨迹
|
||
- 建议默认值：
|
||
- 顺序赛：`full`
|
||
- 积分赛：`tail`
|
||
|
||
### `game.presentation.track.style`
|
||
|
||
- 类型：`string`
|
||
- 说明：轨迹风格 profile
|
||
- 当前支持：
|
||
- `classic`
|
||
- `neon`
|
||
- 当前默认值：`neon`
|
||
|
||
### `game.presentation.track.tailLength`
|
||
|
||
- 类型：`string`
|
||
- 说明：拖尾基础长度档位
|
||
- 当前支持：
|
||
- `short`
|
||
- `medium`
|
||
- `long`
|
||
- 备注：
|
||
- 实际显示长度会继续按移动速度动态变化
|
||
- 跑得越快，尾巴越长
|
||
- 跑得越慢，尾巴越短
|
||
|
||
### `game.presentation.track.colorPreset`
|
||
|
||
- 类型：`string`
|
||
- 说明：轨迹亮色调色盘
|
||
- 当前支持：
|
||
- `mint`
|
||
- `cyan`
|
||
- `sky`
|
||
- `blue`
|
||
- `violet`
|
||
- `pink`
|
||
- `orange`
|
||
- `yellow`
|
||
- 备注：
|
||
- 运行时会在此基础上根据速度和心率张力自动提亮头部颜色与光晕
|
||
|
||
### `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 点基础样式
|
||
- 当前支持：
|
||
- `dot`
|
||
- `beacon`
|
||
- `disc`
|
||
- `badge`
|
||
- 当前默认值：`beacon`
|
||
|
||
### `game.presentation.gpsMarker.size`
|
||
|
||
- 类型：`string`
|
||
- 说明：GPS 点整体大小档位
|
||
- 当前支持：
|
||
- `small`
|
||
- `medium`
|
||
- `large`
|
||
- 当前默认值：`medium`
|
||
|
||
### `game.presentation.gpsMarker.colorPreset`
|
||
|
||
- 类型：`string`
|
||
- 说明：GPS 点亮色调色盘
|
||
- 当前支持：
|
||
- `mint`
|
||
- `cyan`
|
||
- `sky`
|
||
- `blue`
|
||
- `violet`
|
||
- `pink`
|
||
- `orange`
|
||
- `yellow`
|
||
- 当前默认值：`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
|
||
- 当前支持：
|
||
- `minimal`
|
||
- `dynamic-runner`
|
||
- `warning-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`
|
||
|
||
也就是说：
|
||
|
||
**大部分配置项都不是强制必填，先保证主骨架完整即可。**
|
||
|
||
### 22.1 顺序赛最小模板默认流程
|
||
|
||
如果只提供顺序赛最小模板，系统默认按以下流程处理：
|
||
|
||
- 进入游戏后只显示开始点，提示玩家先打开始点
|
||
- 成功打开始点后，显示全部普通控制点、终点和腿线，并正式开始计时
|
||
- 开始点和结束点默认不弹题，只弹提示信息
|
||
- 普通控制点默认允许跳点
|
||
- 默认跳点半径为打点半径的 `2` 倍
|
||
- 普通控制点成功打点后立即获得 `1` 分基础分
|
||
- 最小模板下默认不弹题
|
||
- 如需答题，需显式为对应点位配置 `quiz` CTA
|
||
- 跳过点不弹题、不得分
|
||
- 成功打结束点后停止计时，弹出结束提示，随后进入默认结算页
|
||
|
||
### 22.2 顺序赛最小模板默认表现
|
||
|
||
- 起跑前只显示开始点
|
||
- 打完开始点后显示完整路线
|
||
- 默认路线主色参考传统定向运动紫红色
|
||
- 默认腿线带电流动效
|
||
- 开始点、结束点、当前目标点都应有动效强调
|
||
- 已完成点默认变灰
|
||
- 已跳过点默认使用另一套区分色
|
||
|
||
### 22.3 积分赛最小模板默认流程
|
||
|
||
如果只提供积分赛最小模板，系统默认按以下流程处理：
|
||
|
||
- 进入游戏后只显示开始点，提示玩家先打开始点
|
||
- 成功打开始点后，显示全部积分点和结束点，并正式开始计时
|
||
- 开始点和结束点默认不弹题，只弹提示信息
|
||
- 玩家默认不需要先点击积分点
|
||
- 底部 HUD 信息面板默认显示当前目标摘要、目标距离和总分 / 收集进度摘要
|
||
- 任意未收集积分点进入范围时都可生效
|
||
- 成功打点后默认立即获得该点基础分
|
||
- 最小模板下默认不弹题
|
||
- 如需答题，需显式为对应点位配置 `quiz` CTA
|
||
- 默认至少完成 `1` 个普通积分点后，结束点才解锁，且不需要先设为目标点
|
||
- 成功打结束点后停止计时，弹出结束提示，随后进入默认结算页
|
||
|
||
### 22.4 积分赛最小模板默认表现
|
||
|
||
- 起跑前只显示开始点
|
||
- 打完开始点后显示全部积分点和结束点
|
||
- 当前目标点默认要有更强高亮和动效
|
||
- 默认所有积分点显示分值标签
|
||
- 已收集点默认变灰
|
||
- 默认不显示腿线
|
||
|
||
---
|
||
|
||
## 23. 维护约定
|
||
|
||
后续每次新增配置项时，应同步更新：
|
||
|
||
1. 本文档
|
||
2. 默认模板文档
|
||
3. `event` 目录下的配置样例
|
||
|
||
这样可以保证：
|
||
|
||
- 服务端可对照
|
||
- 后台可录入
|
||
- 客户端联调时有统一参考
|
||
|
||
|