1076 lines
21 KiB
Markdown
1076 lines
21 KiB
Markdown
# 配置选项字典（当前实现版）
|
||
|
||
本文档用于整理 **当前客户端已经消费或已经预留承载的配置项**，作为事件配置、后台配置和联调时的统一参考。
|
||
|
||
目标：
|
||
|
||
- 明确目前哪些字段已经真正生效
|
||
- 明确每个字段的含义、类型、默认逻辑
|
||
- 给后续扩展留下统一维护入口
|
||
|
||
说明：
|
||
|
||
- 本文档优先以“当前代码真实实现”为准
|
||
- 未列出的字段，不代表未来不能加，只代表当前客户端未正式消费
|
||
- 后续每次新增配置能力，都应同步补充本文件
|
||
|
||
---
|
||
|
||
## 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`
|
||
- 说明：打点完成后自动弹出的标题
|
||
|
||
#### `template`
|
||
|
||
- 类型：`string`
|
||
- 说明：原生内容卡模板
|
||
- 当前支持：
|
||
- `minimal`
|
||
- `story`
|
||
- `focus`
|
||
- 建议默认值：
|
||
- 起点/终点：`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`
|
||
- 说明：打点完成后使用的体验承载配置
|
||
- 当前支持：
|
||
- `native`
|
||
- `h5`
|
||
|
||
#### `contentExperience.type`
|
||
|
||
- 类型：`string`
|
||
- 说明：自动弹出内容的承载方式
|
||
- 当前支持：
|
||
- `native`
|
||
- `h5`
|
||
|
||
#### `contentExperience.url`
|
||
|
||
- 类型：`string`
|
||
- 说明：当 `type = "h5"` 时对应的 H5 页面地址
|
||
|
||
#### `contentExperience.bridge`
|
||
|
||
- 类型：`string`
|
||
- 说明：H5 bridge 版本
|
||
- 建议默认值：`"content-v1"`
|
||
|
||
#### `contentExperience.presentation`
|
||
|
||
- 类型：`string`
|
||
- 说明：H5 内容的展示形态
|
||
- 当前支持：
|
||
- `sheet`
|
||
- `dialog`
|
||
- `fullscreen`
|
||
- 建议默认值：`sheet`
|
||
|
||
#### `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`
|
||
- 说明：点击内容的展示形态
|
||
|
||
#### `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`
|
||
- 备注：未配置时回退到样式系统默认标签颜色逻辑
|
||
- 当前支持：
|
||
- `sheet`
|
||
- `dialog`
|
||
- `fullscreen`
|
||
- 建议默认值：`sheet`
|
||
|
||
### 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": "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-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. `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`
|
||
- 说明：对指定路线腿做局部样式覆盖
|
||
- 键名建议：
|
||
- `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": "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
|
||
- 当前支持：
|
||
- `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`
|
||
|
||
也就是说：
|
||
|
||
**大部分配置项都不是强制必填，先保证主骨架完整即可。**
|
||
|
||
---
|
||
|
||
## 23. 维护约定
|
||
|
||
后续每次新增配置项时，应同步更新：
|
||
|
||
1. 本文档
|
||
2. 默认模板文档
|
||
3. `event` 目录下的配置样例
|
||
|
||
这样可以保证：
|
||
|
||
- 服务端可对照
|
||
- 后台可录入
|
||
- 客户端联调时有统一参考
|
||
|