cmr-mini/doc/config/配置选项字典.md

# 配置选项字典（当前实现版）

本文档用于整理 **当前客户端已经消费或已经预留承载的配置项**，作为事件配置、后台配置和联调时的统一参考。

目标：

- 明确目前哪些字段已经真正生效
- 明确每个字段的含义、类型、默认逻辑
- 给后续扩展留下统一维护入口

说明：

- 本文档优先以“当前代码真实实现”为准
- 未列出的字段，不代表未来不能加，只代表当前客户端未正式消费
- 后续每次新增配置能力，都应同步补充本文件

---

## 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` 目录下的配置样例

这样可以保证：

- 服务端可对照
- 后台可录入
- 客户端联调时有统一参考