# GPS 点动画系统方案
> 文档版本：v1.0
> 最后更新：2026-04-02


## 目标

把 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 种状态的程序化动画跑通，再决定后续是否继续开放更细粒度配置。