mini-prog/doc/animation-design-proposal.md

动效系统设计方案

本文档用于整理当前项目后续的动画 / 动效建设方案，目标不是单纯“让界面更花”，而是把动画正式纳入现有架构，成为：

• 状态感知工具
• 空间注意力引导工具
• 操作反馈工具
• 节奏增强工具

当前系统已经具备：

• 地图引擎
• 规则引擎
• telemetry
• presentation
• feedback

因此动画系统最合理的做法，不是零散补丁，而是按层管理、按事件驱动、按配置扩展。

---

1. 设计原则

后续动画建设建议遵循以下原则：

1.1 动画服务于玩法，不只是装饰

动画优先回答这些问题：

• 现在发生了什么
• 用户该看哪里
• 这次操作是否成功
• 当前节奏是在紧张、平稳还是危险

1.2 动画要分层

不要把所有动画都堆在页面层的 class 切换里。
后续应按：

• 地图空间动画
• HUD 动画
• 反馈动画
• 页面微交互动画

分层管理。

1.3 动画要和事件绑定

动画应该由事件或状态变化触发，而不是页面自己猜。

例如：

• control_completed
• control_skipped
• guidance_state_changed
• session_started
• session_finished
• heart_rate_zone_changed
• gps_lock_changed

1.4 动画要支持降级

低端机和正式版都需要降级策略。
后续建议统一支持：

• animationsEnabled
• animationLevel = low / medium / high

---

2. 动画分层方案

2.1 地图空间动画

这一层最重要，也最贴玩法。

适合放在：

• MapPresentation
• MapScene
• WebGL renderer

典型内容：

• 当前目标点脉冲
• 可打点状态强化
• 已完成点过渡
• 已跳过点灰态过渡
• 地图 pulse
• 危险区呼吸
• 迷雾 reveal 扩散
• 金币收集爆点
• 幽灵感知圈变化

这一层的特点

• 与地图空间对象绑定
• 最不适合用 WXML 硬拼
• 应由渲染层持续驱动

---

2.2 HUD 动画

这一层用于数值和状态提示，不直接改地图对象。

适合放在：

• 页面层
• HUD 组件层

典型内容：

• 目标距离数字滑变
• 进度数字跳变
• 心率区间颜色过渡
• 计时器关键时刻闪烁
• 按钮状态点亮 / 失活过渡
• 玩法专属状态块的显隐和强调

这一层的特点

• 更适合 CSS / WXSS animation
• 应避免过重
• 高优先级字段可以做轻动画，避免全屏大动作

---

2.3 反馈动画

这一层最适合和声音、震动一起看，属于事件消费型动画。

适合放在：

• FeedbackDirector
• UIEffectDirector

典型内容：

• 打点成功 toast
• 警告 shake
• 成功 burst
• stage flash
• 局部 pulse
• 失败 / 结束反馈

当前已有雏形

目前系统已经有一些反馈类动效基础：

• punchFeedbackFxClass
• mapPulse
• stageFx

这条线后续最值得继续系统化。

---

2.4 页面微交互动画

这一层优先级最低。

典型内容：

• 按钮轻微过渡
• 面板弹入弹出
• 信息卡展开收起
• 调试面板展开收起

原则

• 可以做，但不要先重投入
• 不要让它抢过地图和玩法本身的注意力

---

3. 当前最值得优先打磨的动画

如果要开始投入动画，我建议先做这 4 组。

3.1 打点成功动画体系

这是当前项目最值得优先打磨的一组。

建议包含：

• 控制点本体状态变化
• 地图局部 pulse
• HUD 进度跳变
• 成功提示 toast
• 声音与震动协同

为什么优先

• 高频
• 用户感知强
• 直接决定“打点有没有爽感”

---

3.2 目标点状态动画体系

建议把目标点的几种状态做清晰区分：

• 未完成
• 当前目标
• 可打点
• 已完成
• 已跳过

每个状态至少应在：

• 颜色
• 脉冲
• 强弱

上有明显区别。

为什么优先

• 这是地图玩法的核心视觉语言
• 对理解规则和空间注意力引导都很关键

---

3.3 锁定 / 自动转图状态动画

建议补强以下体验：

• 开启 GPS 锁定时的吸附反馈
• 锁定关闭时的提示
• 自动转图切换时的更自然缓动
• 特殊状态下的方向感提示

为什么优先

• 当前地图交互已经很强
• 这块稍微打磨就很有“专业感”

---

3.4 危险 / 高压状态动画

这条非常适合未来玩法扩展，尤其是：

• 幽灵追逐赛
• 心率驱动玩法
• 高压任务模式

建议后续支持：

• 边缘呼吸
• 危险圈脉冲
• 压力提示颜色递进
• 节奏增强

---

4. 事件驱动建议

动画最好不要由页面层直接“看到状态变了就自己猜”，而应由事件或 presentation 状态明确驱动。

建议优先整理以下动画事件：

• session_started
• session_finished
• session_cancelled
• control_completed:start
• control_completed:control
• control_completed:finish
• control_skipped
• guidance_state_changed
• gps_lock_changed
• heart_rate_zone_changed
• danger_state_changed

这些事件后续可以统一映射到：

• sound
• haptics
• uiEffects
• map animation

---

5. 配置化建议

后续动画不应只写死在代码里。
建议逐步走向 profile 化。

例如：

"game": {
  "feedback": {
    "uiEffectsProfile": "default-race",
    "mapAnimationProfile": "default-map"
  }
}

后续 profile 可承载的内容

• 某类事件是否启用动效
• 动效持续时间
• 动效强度
• 颜色风格
• 是否允许低端机降级

---

6. 建议增加统一动画配置

建议后续统一支持：

"game": {
  "animation": {
    "enabled": true,
    "level": "medium"
  }
}

建议值：

• enabled
• level = low / medium / high

用途

• 低端机降级
• 调试关闭
• 正式版保守

---

7. 技术落地建议

7.1 地图动画

应继续放在地图引擎和 renderer 内处理。

不要让页面层承担：

• 点位 pulse
• 区域 reveal
• 轨迹闪动
• 目标高亮

这些都更适合：

• MapPresentation
• MapScene
• WebGL renderer

---

7.2 HUD 动画

适合继续放在页面层。

建议：

• 尽量轻量
• 尽量做过渡，不做大面积复杂动画
• 高优先级字段做细微跃迁即可

---

7.3 反馈动画

应继续走：

• FeedbackDirector
• UIEffectDirector

这条线后续很适合继续统一：

• 哪个事件触发什么动画
• 持续多久
• 是否叠加 sound / haptics

---

8. 实施顺序建议

不建议一口气铺太多动画。
推荐顺序：

1. 打点成功动画体系
2. 目标点状态动画体系
3. HUD 数字与状态过渡
4. 锁定 / 自动转图状态动画
5. 危险 / 高压反馈动画
6. 最后再做页面微交互动画

---

9. 第一阶段建议任务

如果下一步准备开始做动画，建议第一阶段先只收下面这些：

任务 1

整理一份动画事件字典：

• 哪些事件会触发动画
• 动画归属哪一层
• 对应目的是什么

任务 2

把打点成功链系统化：

• 点位变化
• HUD 跳变
• pulse
• toast

任务 3

统一目标点状态动画：

• 当前目标
• 可打点
• 已完成
• 已跳过

任务 4

补一个动画总开关：

• animationsEnabled
• animationLevel

---

10. 当前阶段结论

当前项目已经具备做动画体系的基础。
最正确的方向不是继续零散补动效，而是：

• 先按层组织动画
• 再按事件驱动
• 最后再做配置化和降级

一句话总结：

后续动画建设应以“打点成功”和“目标状态”两条高频体验为起点，把动画正式纳入现有架构，而不是继续做零散样式补丁。