# 动画字典 v1
> 文档版本：v1.0
> 最后更新：2026-04-02 08:28:05


## 1. 目的

这份文档用于统一说明：

- 当前系统里**已经存在**的动画触发点
- 哪些事件**适合继续补动画**
- 每个动画应该归属到哪一层
- `lite` 模式下哪些动画应该保留，哪些应该降级

一句话：

**动画字典 = 事件到动画效果的映射表。**

它的价值是：

- 防止动画实现越来越散
- 方便做性能分级
- 方便新玩法复用已有动画语言
- 方便以后做动画 profile / theme

---

## 2. 分层约定

当前动画建议分成 4 层：

### 2.1 地图空间动画

作用在地图对象本身。

例如：

- 当前目标点 pulse
- 可打点外环
- 已完成点 settle
- 已跳过点灰化
- 迷雾 reveal
- 金币收集爆点

归属：

- `MapPresentation`
- `MapScene`
- `WebGL renderer`

### 2.2 HUD 动画

作用在底部 HUD、数字、状态块。

例如：

- 进度跃迁
- 点距变化
- 速度/里程/心率数字轻量过渡

归属：

- 页面层 `WXML / WXSS`
- `MapEngine` 只负责下发状态类名

### 2.3 UI / Feedback 动画

作用在全局提示、局部闪光、反馈层。

例如：

- 顶部提示条出现
- 局部 stage flash
- 成功提示
- 错误/警示提示

归属：

- `feedbackConfig`
- `UiEffectDirector`
- `FeedbackDirector`
- 页面层消费

### 2.4 微交互动画

作用在按钮、弹层、设置面板等。

当前优先级最低。

---

## 3. 已实现动画字典

下面这一部分是当前已经落到代码里的内容。

| 事件/状态 | 地图空间动画 | HUD 动画 | UI/Feedback 动画 | lite 保留 |
|---|---|---|---|---|
| `control_ready` | 当前目标点更亮、ready 强调 | 打点相关状态切换 | 无 | 是 |
| `control_completed:start` | 开始点完成 settle 外环 | 进度/点距轻反馈 | 轻量成功反馈 | 是 |
| `control_completed:control` | 普通检查点完成 settle 外环 | 进度跃迁、点距动效 | 轻量地图 flash / pulse | 是 |
| `control_completed:finish` | 终点完成 settle 外环更明显 | 进度完成反馈 | finish 级反馈更强 | 是 |
| `control_skipped` | 当前点灰化、斜杠标记 | 当前目标推进 | 轻提示（较轻） | 是 |
| `target_changed` | 当前目标高亮切换 | 目标相关 HUD 状态切换 | 无 | 是 |
| `heart_rate_updated` | 无 | 心率数字过渡 | 无 | 是 |
| `timer_tick` | 无 | 计时器数字轻量过渡 | 无 | `lite` 可降级 |
| `mileage_updated` | 无 | 里程数字过渡 | 无 | `lite` 可降级 |
| `speed_updated` | 无 | 速度数字过渡 | 无 | `lite` 可降级 |
| `panel_progress_changed` | 无 | 进度数字 / 状态切换 | 无 | 是 |
| `map_pulse` | 地图局部 pulse | 无 | 可伴随轻 stage flash | `lite` 简化 |
| `stage_flash` | 无 | 无 | 局部屏幕闪光 | `lite` 可关闭 |

---

## 4. 推荐新增动画字典

下面这些是**非常适合继续补齐**的事件。

### 4.1 高优先级

#### `session_started`

建议效果：

- 地图：起点轻脉冲或开场吸附感
- HUD：开始态切换
- UI：顶部提示条轻弹入

原因：

- 这是对局开始的第一感受
- 很适合统一“进入比赛状态”的语言

#### `target_transition`

指：

- 一个点完成后
- 下一个目标点接管当前目标状态

建议效果：

- 地图：旧点 settle，新点接管 pulse
- HUD：目标进度轻切换
- UI：可以不额外做

原因：

- 当前这条链已经有基础，但还不够“连续”
- 这是顺序赛最值得打磨的高频体验

#### `control_skipped`

建议效果：

- 地图：当前点灰化过渡更明显
- HUD：提示“已跳过 x 号点”
- UI：轻量 skip toast / 轻闪光

原因：

- 逻辑已经有
- 状态已经有
- 动画语言还不够完整

---

### 4.2 中优先级

#### `gps_lock_changed:on`

建议效果：

- 地图：回中吸附感
- HUD：无
- UI：轻提示“已锁定定位点”

#### `gps_lock_changed:off`

建议效果：

- 地图：无
- HUD：无
- UI：轻提示“已解除锁定”

#### `center_scale_ruler_changed`

建议效果：

- UI：比例尺淡入/淡出

原因：

- 比例尺是工具型功能
- 不需要强动画，但可以更自然

#### `north_reference_changed`

建议效果：

- UI：小提示
- 指北针顶部文案轻切换

---

### 4.3 下一阶段重点

#### `heart_rate_zone_changed`

建议效果：

- HUD：颜色平滑切换
- UI：边缘呼吸 / 警示
- 地图：一般不建议直接做

原因：

- 未来心率玩法、危险状态会很依赖这条

#### `danger_state_changed`

适用于未来：

- 幽灵追逐
- 危险区
- 高压状态

建议效果：

- UI：边缘呼吸
- HUD：局部强调
- 地图：危险区波纹

#### `zone_entered / zone_cleared`

适用于未来：

- 区域玩法
- 迷雾玩法
- 领地玩法

建议效果：

- 地图：区域高亮 / reveal
- HUD：区域状态变化
- UI：轻量提示

---

## 5. 不建议过度动画化的节点

下面这些不建议做太重：

- 每次 GPS 更新
- 每次地图缩放
- 每次地图拖动
- 每次 compass heading 变化
- 每次 telemetry 微小变化

原因：

- 高频
- 成本高
- 极易拖垮低端机

原则：

**高频输入只做平滑，不做明显动画。**

---

## 6. 动画等级建议

当前已有两级：

- `standard`
- `lite`

建议动画字典里每项都标清楚在 `lite` 下如何处理。

### `standard`

- 完整 pulse
- 完整 settle
- HUD 数字过渡正常
- 局部 flash 保留

### `lite`

- pulse 层数减少
- settle 更轻
- HUD 数字动画缩短或关闭
- flash 关闭或极轻

---

## 7. 下一步推荐落地顺序

建议按这个顺序继续推进：

1. `session_started`
2. `target_transition`
3. `control_skipped`
4. `gps_lock_changed`
5. `heart_rate_zone_changed`
6. `danger_state_changed`

---

## 8. 执行原则

后面继续做动画时，遵循这几条：

### 8.1 先看事件，再决定动画

不要先想“做个好看的效果”，而是先问：

- 哪个事件需要被用户感知？
- 这个事件最适合地图 / HUD / UI 哪一层？

### 8.2 只强化高价值反馈

优先强化：

- 开始
- 打点成功
- 目标切换
- 跳点
- 危险状态

### 8.3 低端机优先

任何新增动画都要先问：

- `lite` 下要不要保留？
- 不保留是否影响信息传达？

### 8.4 动画不替代状态

动画只做状态的表现，不能替代状态本身。

也就是：

- 先有状态
- 再有动画

---

## 9. 阶段结论

当前动画系统已经具备：

- 主链
- 分层
- 高价值基础动画
- 性能等级

下一步的重点不是继续零散加动效，而是：

**按动画字典逐项补齐高频体验链。**