整理中文文档结构与索引

This commit is contained in:
2026-03-30 18:49:22 +08:00
parent 3b9117427e
commit 24bc60bc7f
49 changed files with 462 additions and 136 deletions

View File

@@ -0,0 +1,358 @@
# 动画字典 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. 阶段结论
当前动画系统已经具备:
- 主链
- 分层
- 高价值基础动画
- 性能等级
下一步的重点不是继续零散加动效,而是:
**按动画字典逐项补齐高频体验链。**

View File

@@ -0,0 +1,364 @@
# 动画接入工作流
## 1. 目的
这份文档用于说明:
- 设计公司提供的动画稿,应该如何转成程序可执行的内容
- 我方应该如何组织这类工作
- 动画接入前、中、后的协作方式
一句话:
**不要把动画稿直接塞进程序,要先把它转成“工程规格”。**
---
## 2. 核心原则
### 2.1 交付的是规格,不只是效果
设计公司不能只给:
- 视频
- GIF
- 一张效果图
至少还需要给:
- 动画名称
- 触发时机
- 作用对象
- 起始状态
- 结束状态
- 时长
- 延迟
- 缓动
- 是否循环
- 是否可中断
- 资源形式
- 降级方案
### 2.2 先分类,再决定技术实现
不是所有动画都适合用同一种实现方式。
必须先判断它属于:
- 地图空间动画
- HUD 动画
- UI / Feedback 动画
- 过场 / Cutscene 动画
### 2.3 先看信息价值,再看视觉效果
优先实现:
- 帮助用户理解状态的动画
- 引导视线的动画
- 强化反馈的动画
延后实现:
- 纯装饰性动画
- 对玩法理解没有帮助的长演出
### 2.4 低端机优先
任何动画都要先问:
- `lite` 模式下怎么降级?
- 不做时是否影响信息表达?
---
## 3. 推荐流程
建议每个动画都按下面这条流程走:
### 第一步:设计交付
设计提供:
- 动画视觉稿
- 动画规格参数
- 资源文件
- 适配说明
### 第二步:整理进动画字典
先把动画纳入事件字典,而不是直接实现。
例如:
- 什么事件触发它
- 作用在哪一层
- `standard / lite` 如何处理
### 第三步:技术归类
判断该动画由哪一层承接:
- `MapPresentation / Renderer`
- 页面 `WXML / WXSS`
- `UiEffectDirector`
- 单独的 `Cutscene`
### 第四步:选择实现方式
例如:
- 纯程序动画
- 序列帧 / sprite
- Lottie
- 视频
### 第五步:做性能分级
明确:
- `standard` 怎么做
- `lite` 怎么做
- 是否允许完全关闭
### 第六步:联调与验收
至少验证:
- 触发正确
- 状态切换正确
- 多次连续触发是否正常
- 可中断行为是否正确
- 低端机是否流畅
---
## 4. 动画实现方式建议
### 4.1 纯程序动画
适合:
- 地图 pulse
- 数字过渡
- HUD 状态变化
- 按钮反馈
优点:
- 最轻
- 最稳定
- 最适合小程序
### 4.2 Lottie / 骨骼类动画
适合:
- 局部高质量 UI 动效
- 成功反馈
- 勋章 / 特殊提示
风险:
- 小程序里复杂 Lottie 可能卡
### 4.3 序列帧 / Sprite
适合:
- 爆点
- 金币收集
- 局部地图特效
风险:
- 占内存
- 占包体
### 4.4 视频 / 过场动画
适合:
- 章节开场
- 比赛结果页
- 特殊演出
不适合:
- 地图过程中的高频反馈
---
## 5. 当前项目里的推荐落点
### 地图空间动画
放在:
- `MapPresentation`
- `MapScene`
- `WebGL Renderer`
### HUD 动画
放在:
- 页面层 `WXML / WXSS`
### Feedback 动画
放在:
- `feedbackConfig`
- `UiEffectDirector`
- `FeedbackDirector`
### 过场动画
建议未来独立一层:
- `Transition`
- `Cutscene`
---
## 6. 当前建议的协作方式
以后和设计公司协作时,建议这样分工:
### 设计公司负责
- 视觉稿
- 动画节奏
- 参数规格
- 资源文件
- 降级建议
### 我方负责
- 事件归类
- 技术选型
- 动画字典维护
- 分层接入
- 性能分级
---
## 7. 推荐的工作顺序
建议以后优先接这类动画:
1. 打点成功
2. 目标切换
3. 跳点
4. 高压 / 危险反馈
5. 章节开场 / 过场动画
---
## 8. 结论
动画接入的正确方式不是:
**拿到设计稿 -> 直接写代码**
而是:
**拿到设计稿 -> 转成动画规格 -> 纳入动画字典 -> 选技术实现 -> 做性能分级 -> 再接程序**
---
## 9. 规格模板
后续和设计公司、外包或内部设计协作时,建议每个动画至少补齐下面这些字段:
- 动画 ID
- 动画名称
- 所属页面/模块
- 所属层级:地图空间 / HUD / UI反馈 / 过场
- 触发事件
- 触发条件
- 是否高频
- 作用对象
- 起始状态 / 结束状态
- 动画形式:程序动画 / Lottie / 序列帧 / 视频
- 资源文件
- 时长 / 延迟 / 缓动
- 是否循环
- 是否可中断
- 重复触发策略:覆盖 / 忽略 / 重启 / 排队
- `standard` 表现
- `lite` 表现
- 是否允许关闭
- 验收标准
推荐最小记录格式:
```md
动画 ID
动画名称:
所属页面/模块:
所属层级:
触发事件:
触发条件:
动画形式:
时长:
缓动:
是否循环:
是否可中断:
重复触发策略:
standard 表现:
lite 表现:
验收标准:
```
---
## 10. 接入评审清单
在接设计稿或准备开发前,至少先过一遍这份清单:
### 设计侧
- 动画目标是否明确
- 触发条件是否明确
- 是否有完整规格和资源
- 是否提供 `lite` 降级方案
### 技术侧
- 动画属于哪一层
- 最合适的实现方式是什么
- 是否真的需要资源文件,还是纯程序动画就够
### 性能侧
- 是否高频触发
- `lite` 下是保留、简化还是关闭
- 是否会带来高频 `setData`、持续循环动画或额外桥接成本
### 交互侧
- 是否可中断
- 多次连续触发会怎样
- 是否会和现有地图 pulse、HUD 动效、stage 效果冲突
### 验收侧
- 触发时机是否正确
- 结束时机是否正确
- 连续触发是否稳定
- `standard / lite` 是否都可用
- 低端机是否可接受
---
## 11. 归档说明
原来的:
- `animation-integration-spec.md`
- `animation-review-checklist.md`
已经归档到 [archive/animation](/D:/dev/cmr-mini/doc/archive/animation),当前以本文件为统一入口。

View File

@@ -0,0 +1,193 @@
# 动画体系阶段性小结
## 1. 当前定位
目前动画体系已经从“页面里临时加 class”的阶段进入了**有主链、有分层、有性能分级**的阶段。
当前主链可以概括为:
- 事件触发
- `feedbackConfig`
- `UiEffectDirector`
- `FeedbackDirector`
- `MapEngine`
- 页面层 / 渲染层消费
也就是:
**事件 -> 效果配置 -> 宿主提交 -> 页面 / Renderer 落地**
这说明动画已经不再是零散实现,而开始进入架构化管理。
---
## 2. 已经完成的内容
### 2.1 HUD 动效
已经完成:
- 打点成功后的 `进度` 动效
- 打点成功后的 `点距` 动效
- HUD 数字轻量过渡:
- 计时
- 里程
- 速度
- 心率
这些动效已经接入正式链路,不是页面单独临时处理。
### 2.2 地图空间动画
已经完成:
- 当前目标点状态强调
- 可打点状态强调
- 已完成点状态过渡
- 已跳过点灰态与标记
- 开始点 / 终点完成后的 settle 外环
- 轻量地图 pulse
### 2.3 局部 UI / Stage 动效
已经完成:
- 轻量 stage flash
- 顶部提示和局部反馈的基础动画承载链
### 2.4 动画性能分级
已经完成 2 级动画分级:
- `standard`
- `lite`
当前 `lite` 的主要策略包括:
- 减少 pulse 层数
- 降低几何分段
- 降低渲染动画频率
- 关闭部分 HUD 动画
- 关闭或减弱某些 stage/UI 动效
这意味着动画体系已经开始考虑**低端机表现**,不是只追求效果。
---
## 3. 当前架构上的价值
动画体系现在已经带来了几个明确收益:
- 动效不再散落在多个页面细节里
- 高频状态变化有了统一反馈语言
- 地图状态和 HUD 状态开始形成一致体验
- 性能分级已经进入体系,可服务低端机
从架构角度看,这意味着:
**动画已经成为正式能力层,而不是临时视觉补丁。**
---
## 4. 当前还不够完整的地方
虽然主链已经成型,但当前还没有完全形成“动画字典”和完整 profile 体系。
目前仍然存在这些不足:
- 哪些事件触发哪些动画,还没有整理成统一字典
- 部分高频状态切换还不够连续
- `跳点` 已有逻辑和状态,但动画语言还不完整
- 危险/高压状态动画还没有正式开始
- 动画 profile 还没有真正配置化
所以当前阶段可以定义为:
**第一阶段后半段:主链已成型,但还需要把高频体验打磨完整。**
---
## 5. 下一阶段最值得做的事情
### 5.1 先整理动画字典
建议先把动画按事件梳理出来,例如:
- `session_started`
- `control_ready`
- `control_completed:start`
- `control_completed:control`
- `control_completed:finish`
- `control_skipped`
- `gps_lock_changed`
- `guidance_state_changed`
- `heart_rate_zone_changed`
并明确每个事件对应:
- 地图动画
- HUD 动画
- UI 动画
- `lite` 下是否保留
这一步是当前最值得优先完成的工作。
### 5.2 补完整“目标状态切换连续感”
继续打磨:
- 当前目标
- 进入可打点
- 打点成功
- 切到下一个目标
让这一整段切换更连贯、更有节奏。
### 5.3 补齐“跳点”动画
建议下一步把跳点也正式纳入动画体系:
- 跳点确认后
- 当前点灰化
- 下一个目标接管强调
- HUD 给出轻量反馈
### 5.4 再做危险 / 高压反馈
这部分适合进入下一阶段:
- 高心率反馈
- 危险区反馈
- 幽灵追逐反馈
- 边缘呼吸 / 紧张感动效
这条线很适合后续玩法扩展。
---
## 6. 建议的实施顺序
推荐继续推进的顺序:
1. 动画字典整理
2. 目标切换连续感补齐
3. 跳点动画补齐
4. 危险 / 高压状态动画
5. 更进一步的配置化 profile
---
## 7. 结论
当前动画体系已经是一个明确的阶段性成果:
- 有主链
- 有分层
- 有高频核心动画
- 有性能分级
接下来最该做的不是“继续零散加动画”,而是:
**把现有能力收成动画字典,并优先打磨目标切换与跳点这两条高频体验链。**