mini-prog/doc/animation-dictionary.md

动画字典 v1

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. 阶段结论

当前动画系统已经具备：

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

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

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