整理文档并接入 H5 体验测试链路
This commit is contained in:
357
doc/animation-dictionary.md
Normal file
357
doc/animation-dictionary.md
Normal file
@@ -0,0 +1,357 @@
|
||||
# 动画字典 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. 阶段结论
|
||||
|
||||
当前动画系统已经具备：
|
||||
|
||||
- 主链
|
||||
- 分层
|
||||
- 高价值基础动画
|
||||
- 性能等级
|
||||
|
||||
下一步的重点不是继续零散加动效，而是：
|
||||
|
||||
**按动画字典逐项补齐高频体验链。**
|
||||
|
||||
Reference in New Issue
Block a user