完善样式系统与调试链路底座

2026-03-30 18:19:05 +08:00
parent 2c0fd4c549
commit 3b9117427e
40 changed files with 7526 additions and 389 deletions
--- a/doc/config-option-dictionary.md
+++ b/doc/config-option-dictionary.md
@@ -313,6 +313,61 @@

 - 类型：`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`
@@ -626,7 +681,369 @@

 ---

-## 19. 当前默认逻辑说明
+## 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. 当前默认逻辑说明

 当前客户端对配置的处理原则是：

@@ -642,7 +1059,7 @@

 ---

-## 20. 维护约定
+## 23. 维护约定

 后续每次新增配置项时，应同步更新：