整理中文文档结构与索引

2026-03-30 18:49:22 +08:00
parent 3b9117427e
commit 24bc60bc7f
49 changed files with 462 additions and 136 deletions
--- a/doc/rendering/GPS点动画系统方案.md
+++ b/doc/rendering/GPS点动画系统方案.md
@@ -0,0 +1,211 @@
+# GPS 点动画系统方案
+
+## 目标
+
+把 GPS 点从“静态定位点”升级成**状态驱动的动态标记系统**：
+
+- 停止时是一种动画
+- 移动时是一种动画
+- 高速时是一种动画
+- 高压/危险状态时还能叠加额外张力
+
+原则：
+
+- 优先程序化动画，不先上重资源
+- 不破坏当前位置识别性
+- 必须兼容 `standard / lite`
+- 品牌 logo 只是贴片，不替代定位点本体和朝向三角
+
+## 状态分层
+
+### 1. 运动状态
+
+- `idle`
+  - 基本静止
+  - 轻呼吸
+  - 不拖尾
+- `moving`
+  - 正常行走/跑动
+  - 有轻微动势和尾迹
+- `fast-moving`
+  - 明显高速
+  - 更强脉冲
+  - 更长尾迹
+  - 朝向更锐利
+
+### 2. 危险/高压状态
+
+- `warning`
+  - 由心率/张力状态触发
+  - 不替代运动判断，而是在视觉上给 GPS 点额外警示感
+  - 更暖的色彩张力
+  - 更强的外环脉冲
+
+## 第一阶段实现范围
+
+### 默认动画 profile
+
+- `dynamic-runner`
+
+后续预留：
+
+- `minimal`
+- `warning-reactive`
+
+### 第一阶段具体表现
+
+#### `idle`
+
+- 慢节奏呼吸
+- 基本无拖尾
+- 方向三角稍收敛
+
+#### `moving`
+
+- 普通脉冲
+- 后侧轻尾迹
+- 方向三角略放大
+
+#### `fast-moving`
+
+- 更快脉冲
+- 更长尾迹
+- 本体略放大
+- 方向三角更强
+
+#### `warning`
+
+- 保留运动态基础
+- 外环增加暖色警示张力
+- 脉冲节奏更急
+
+## 第一阶段配置字段
+
+入口：
+
+```json
+"game": {
+  "presentation": {
+    "gpsMarker": {}
+  }
+}
+```
+
+新增字段：
+
+```json
+{
+  "animationProfile": "dynamic-runner"
+}
+```
+
+说明：
+
+- `minimal`
+  - 更轻、更克制
+  - 适合低配或保守活动风格
+- `dynamic-runner`
+  - 默认值
+  - 强调移动感
+- `warning-reactive`
+  - 更强调高压/危险张力
+
+## 运行时内部字段
+
+这些字段不建议先暴露给活动配置，而是由运行时自动计算：
+
+- `motionState`
+- `motionIntensity`
+- `wakeStrength`
+- `warningGlowStrength`
+- `indicatorScale`
+- `logoScale`
+
+这样可以保证：
+
+- 配置简单
+- 逻辑稳定
+- 真机调完后再决定哪些值得开放
+
+## 运行时判定建议
+
+### 运动状态
+
+- `< 1.0 km/h`：`idle`
+- `1.0 ~ 6.8 km/h`：`moving`
+- `>= 6.8 km/h`：`fast-moving`
+
+### 高压状态
+
+参考现有 telemetry tone：
+
+- `yellow`
+- `orange`
+- `red`
+
+其中：
+
+- `orange / red`
+  优先进入 `warning`
+- `yellow`
+  作为较轻的张力增强
+
+## 渲染拆分
+
+### WebGL 主体
+
+负责：
+
+- 本体
+- 外环
+- 脉冲
+- 尾迹
+- 朝向三角
+
+### 2D 叠加层
+
+负责：
+
+- logo 中心贴片
+
+logo 不参与主几何动画，只跟随缩放强度和尺寸变化。
+
+## 性能策略
+
+### `standard`
+
+- 完整脉冲
+- 完整尾迹
+- 警示外环
+
+### `lite`
+
+- 减弱尾迹
+- 降低 glow
+- 降低 warning 外环强度
+- 保留最基本的移动/静止差异
+
+## 后续第二阶段
+
+- logo 贴片本身的轻动画
+- 事件动作
+  - 打点成功跳动
+  - 锁定开启反馈
+  - 高压进入反馈
+- mascot/角色化 GPS 点
+
+## 结论
+
+GPS 点动画不应该做成单一固定动画，而应该做成：
+
+**状态驱动的动态标记系统**
+
+第一阶段先把：
+
+- `idle`
+- `moving`
+- `fast-moving`
+- `warning`
+
+这 4 种状态的程序化动画跑通，再决定后续是否继续开放更细粒度配置。
+
--- a/doc/rendering/GPS点样式系统方案.md
+++ b/doc/rendering/GPS点样式系统方案.md
@@ -0,0 +1,114 @@
+# GPS 点样式系统方案
+
+## 目标
+
+把当前“粗糙蓝点”升级成正式的 GPS 点样式系统，满足：
+
+- 默认样式更精致
+- 显示/隐藏可控
+- 大小可调
+- 颜色可调
+- 带跟随朝向旋转的小三角
+- 后续可承接品牌 logo 定制
+
+## 分层
+
+### 1. 显示策略
+
+- `visible`
+- `size`
+- `colorPreset`
+
+### 2. 基础样式
+
+第一阶段支持：
+
+- `dot`
+- `beacon`
+- `disc`
+- `badge`
+
+默认：
+
+- `beacon`
+
+### 3. 朝向指示
+
+GPS 点上方增加一个小三角：
+
+- 跟随朝向旋转
+- 朝向可信度高时更明显
+- 朝向可信度低时自动降低透明度
+
+### 4. 品牌化扩展
+
+后续通过：
+
+- `logoUrl`
+- `logoMode`
+
+把商家 logo 作为中心贴片嵌入 GPS 点，不直接替代定位点本体。
+
+## 第一阶段默认值
+
+```json
+{
+  "visible": true,
+  "style": "beacon",
+  "size": "medium",
+  "colorPreset": "cyan",
+  "showHeadingIndicator": true,
+  "logoUrl": "",
+  "logoMode": "center-badge"
+}
+```
+
+## 用户设置建议
+
+系统设置先开放：
+
+- GPS 点显示：`显示 / 隐藏`
+- GPS 点大小：`小 / 中 / 大`
+- GPS 点颜色：8 种亮色
+
+品牌 logo 先不进用户设置，只保留给活动配置。
+
+## 配置入口
+
+建议统一放在：
+
+```json
+"game": {
+  "presentation": {
+    "gpsMarker": {}
+  }
+}
+```
+
+## 长期演进
+
+### 第二阶段
+
+- logo 中心贴片
+- 不同玩法默认 GPS 点 profile
+- 更强的脉冲/光晕动画
+
+### 第三阶段
+
+- GPS 点与心率/危险状态联动
+- 客户品牌化主题包
+- 特殊活动皮肤
+
+## 结论
+
+GPS 点应被视为独立样式系统，而不是固定蓝点。
+
+第一阶段先把：
+
+- 显示
+- 大小
+- 颜色
+- 朝向三角
+
+做稳定，再逐步承接商业品牌化定制。
+
--- a/doc/rendering/轨迹可视化方案.md
+++ b/doc/rendering/轨迹可视化方案.md
@@ -0,0 +1,86 @@
+# 轨迹可视化方案
+
+本文档定义用户轨迹的显示模式、默认策略与配置结构。
+
+目标：
+
+- 支持 `none / full / tail` 三种轨迹模式
+- `tail` 模式有更强的实时感和游戏感
+- 兼顾低端机性能
+
+## 模式定义
+
+### `none`
+
+- 不显示轨迹
+- 只显示当前 GPS 点
+
+### `full`
+
+- 显示从开始到当前的完整轨迹
+
+### `tail`
+
+- 只显示最近一小段拖尾轨迹
+- 头部更亮、更粗
+- 尾部逐步变淡、变细
+- 用户停止移动后，轨迹会逐步缩短到消失
+
+## 推荐默认值
+
+### 顺序赛
+
+- `mode = full`
+- `style = classic`
+
+### 积分赛
+
+- `mode = tail`
+- `style = neon`
+
+## 推荐配置
+
+```json
+"game": {
+  "presentation": {
+    "track": {
+      "mode": "tail",
+      "style": "neon",
+      "tailMeters": 60,
+      "tailMaxSeconds": 30,
+      "fadeOutWhenStill": true,
+      "stillSpeedKmh": 0.6,
+      "fadeOutDurationMs": 3000,
+      "colorHex": "#176d5d",
+      "headColorHex": "#54f3d8",
+      "widthPx": 5,
+      "headWidthPx": 10,
+      "glowStrength": 0.42
+    }
+  }
+}
+```
+
+## 当前实现约定
+
+当前第一版实现支持：
+
+- `mode`
+- `style`
+- `tailMeters`
+- `tailMaxSeconds`
+- `fadeOutWhenStill`
+- `stillSpeedKmh`
+- `fadeOutDurationMs`
+- `colorHex`
+- `headColorHex`
+- `widthPx`
+- `headWidthPx`
+- `glowStrength`
+
+## 后续扩展
+
+- 轨迹颜色按心率区间变化
+- 轨迹颜色按速度变化
+- `standard / lite` 下自动降级 glow
+