# 动效系统设计方案

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

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

当前系统已经具备：

- 地图引擎
- 规则引擎
- 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 化。

例如：

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

### 后续 profile 可承载的内容

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

---

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

建议后续统一支持：

```json
"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. 当前阶段结论

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

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

一句话总结：

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