整理中文文档结构与索引
This commit is contained in:
164
doc/archive/animation/动画接入规格模板.md
Normal file
164
doc/archive/animation/动画接入规格模板.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# 动画接入规格模板
|
||||
|
||||
## 1. 用途
|
||||
|
||||
这份模板用于：
|
||||
|
||||
- 设计公司交付动画时填写
|
||||
- 开发接入前确认规格
|
||||
- 作为动画实现与验收依据
|
||||
|
||||
建议：一个动画一条记录。
|
||||
|
||||
---
|
||||
|
||||
## 2. 基础信息模板
|
||||
|
||||
```md
|
||||
动画 ID：
|
||||
动画名称：
|
||||
所属页面/模块：
|
||||
所属层级：地图空间 / HUD / UI反馈 / 过场
|
||||
优先级：高 / 中 / 低
|
||||
|
||||
触发事件：
|
||||
触发条件：
|
||||
是否高频：
|
||||
|
||||
作用对象：
|
||||
起始状态：
|
||||
结束状态：
|
||||
|
||||
动画形式：程序动画 / Lottie / 序列帧 / 视频 / 其他
|
||||
资源文件：
|
||||
|
||||
时长：
|
||||
延迟：
|
||||
缓动：
|
||||
是否循环：
|
||||
是否可中断：
|
||||
重复触发策略：覆盖 / 忽略 / 重启 / 排队
|
||||
|
||||
standard 表现：
|
||||
lite 表现：
|
||||
是否允许关闭：
|
||||
|
||||
设计说明：
|
||||
开发备注：
|
||||
验收标准：
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 字段说明
|
||||
|
||||
### 动画 ID
|
||||
|
||||
要求：
|
||||
|
||||
- 全局唯一
|
||||
- 使用英文或稳定标识
|
||||
|
||||
例如：
|
||||
|
||||
- `control_complete_flash`
|
||||
- `target_ready_pulse`
|
||||
- `session_intro_banner`
|
||||
|
||||
### 所属层级
|
||||
|
||||
建议四选一：
|
||||
|
||||
- 地图空间
|
||||
- HUD
|
||||
- UI反馈
|
||||
- 过场
|
||||
|
||||
### 触发事件
|
||||
|
||||
必须明确写出触发它的事件。
|
||||
|
||||
例如：
|
||||
|
||||
- `control_completed:control`
|
||||
- `control_skipped`
|
||||
- `session_started`
|
||||
- `heart_rate_zone_changed:red`
|
||||
|
||||
### 重复触发策略
|
||||
|
||||
必须提前约定：
|
||||
|
||||
- `覆盖`
|
||||
- `忽略`
|
||||
- `重启`
|
||||
- `排队`
|
||||
|
||||
否则高频触发时容易行为不一致。
|
||||
|
||||
### standard / lite
|
||||
|
||||
每个动画都必须给出两档建议。
|
||||
|
||||
例如：
|
||||
|
||||
- `standard`：完整 pulse + 外环
|
||||
- `lite`：保留单层 pulse，去掉外环
|
||||
|
||||
---
|
||||
|
||||
## 4. 推荐填写示例
|
||||
|
||||
```md
|
||||
动画 ID：control_complete_flash
|
||||
动画名称：打点成功轻闪光
|
||||
所属页面/模块：地图页
|
||||
所属层级：UI反馈
|
||||
优先级：高
|
||||
|
||||
触发事件：control_completed:control
|
||||
触发条件：普通检查点打点成功
|
||||
是否高频：是
|
||||
|
||||
作用对象：地图主舞台
|
||||
起始状态：正常地图状态
|
||||
结束状态：恢复正常地图状态
|
||||
|
||||
动画形式：程序动画
|
||||
资源文件：无
|
||||
|
||||
时长：320ms
|
||||
延迟：0ms
|
||||
缓动：ease-out
|
||||
是否循环：否
|
||||
是否可中断：是
|
||||
重复触发策略：重启
|
||||
|
||||
standard 表现：淡白色局部 flash，透明度较明显
|
||||
lite 表现：透明度降低 50%，时长缩短到 220ms
|
||||
是否允许关闭：是
|
||||
|
||||
设计说明：突出“完成打点”的即时成功感
|
||||
开发备注：通过 UiEffectDirector 下发 stageFx
|
||||
验收标准：普通打点时稳定触发，连续打点不拖尾
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 对设计公司的要求
|
||||
|
||||
建议以后明确告诉设计公司：
|
||||
|
||||
- 不只要演示稿
|
||||
- 必须提供参数规格
|
||||
- 必须提供资源清单
|
||||
- 必须说明低配降级方案
|
||||
|
||||
---
|
||||
|
||||
## 6. 结论
|
||||
|
||||
这份模板的目的是把动画从“视觉稿”变成“工程规格”。
|
||||
只有规格明确，程序才能稳定接入。
|
||||
|
||||
|
||||
163
doc/archive/animation/动画接入评审清单.md
Normal file
163
doc/archive/animation/动画接入评审清单.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# 动画接入评审清单
|
||||
|
||||
## 1. 用途
|
||||
|
||||
这份清单用于在接设计稿或准备开发前，快速判断：
|
||||
|
||||
- 这个动画能不能接
|
||||
- 应该接到哪一层
|
||||
- 有没有性能风险
|
||||
- 有没有交付缺口
|
||||
|
||||
---
|
||||
|
||||
## 2. 设计稿评审
|
||||
|
||||
### 2.1 动画目标是否明确
|
||||
|
||||
- 这个动画是为了表达什么？
|
||||
- 它是状态反馈，还是纯装饰？
|
||||
- 用户不看它，会不会影响理解？
|
||||
|
||||
### 2.2 触发条件是否明确
|
||||
|
||||
- 由哪个事件触发？
|
||||
- 是否会高频触发？
|
||||
- 是否允许重复触发？
|
||||
|
||||
### 2.3 交付是否完整
|
||||
|
||||
- 是否有参数规格？
|
||||
- 是否有资源文件？
|
||||
- 是否有尺寸 / 比例说明？
|
||||
- 是否有 `lite` 降级说明？
|
||||
|
||||
---
|
||||
|
||||
## 3. 技术评审
|
||||
|
||||
### 3.1 该动画属于哪一层
|
||||
|
||||
- 地图空间
|
||||
- HUD
|
||||
- UI反馈
|
||||
- 过场
|
||||
|
||||
### 3.2 最合适的实现方式是什么
|
||||
|
||||
- 程序动画
|
||||
- Lottie
|
||||
- 序列帧
|
||||
- 视频
|
||||
|
||||
### 3.3 是否真的需要资源文件
|
||||
|
||||
很多动画其实可以纯程序实现，不需要额外资源。
|
||||
|
||||
如果只是：
|
||||
|
||||
- pulse
|
||||
- 渐隐
|
||||
- 平移
|
||||
- 数字过渡
|
||||
|
||||
优先用程序动画。
|
||||
|
||||
---
|
||||
|
||||
## 4. 性能评审
|
||||
|
||||
### 4.1 是否高频
|
||||
|
||||
如果是高频事件，不适合做重动画：
|
||||
|
||||
- GPS 更新
|
||||
- compass heading 更新
|
||||
- 拖动 / 缩放
|
||||
- telemetry 微小变化
|
||||
|
||||
### 4.2 lite 模式怎么处理
|
||||
|
||||
必须明确：
|
||||
|
||||
- 保留
|
||||
- 简化
|
||||
- 关闭
|
||||
|
||||
### 4.3 是否会增加页面层负担
|
||||
|
||||
要判断：
|
||||
|
||||
- 会不会引入高频 `setData`
|
||||
- 会不会创建大数组
|
||||
- 会不会增加持续循环动画
|
||||
- 会不会增加桥接成本
|
||||
|
||||
---
|
||||
|
||||
## 5. 交互评审
|
||||
|
||||
### 5.1 是否可中断
|
||||
|
||||
- 用户切页面怎么办？
|
||||
- 状态瞬间变化怎么办？
|
||||
- 连续触发怎么办？
|
||||
|
||||
### 5.2 是否会和现有动画冲突
|
||||
|
||||
- 同一事件是否已有动画？
|
||||
- 是否会重复表达同一个信息？
|
||||
- 是否和现有地图 pulse / HUD 动效叠加过重？
|
||||
|
||||
---
|
||||
|
||||
## 6. 当前项目特别注意项
|
||||
|
||||
### 6.1 地图过程中的动画必须克制
|
||||
|
||||
因为当前项目：
|
||||
|
||||
- 地图是主舞台
|
||||
- 低端机性能敏感
|
||||
- 页面桥接成本高
|
||||
|
||||
所以：
|
||||
|
||||
- 地图上的高频动画必须轻量
|
||||
- 尽量减少页面层大范围动画
|
||||
|
||||
### 6.2 优先动画化高价值节点
|
||||
|
||||
优先做：
|
||||
|
||||
- 打点成功
|
||||
- 目标切换
|
||||
- 跳点
|
||||
- 危险 / 高压反馈
|
||||
|
||||
延后做：
|
||||
|
||||
- 纯装饰性微动效
|
||||
- 复杂长演出
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收清单
|
||||
|
||||
动画接入完成后，至少确认：
|
||||
|
||||
- 触发时机正确
|
||||
- 结束时机正确
|
||||
- 多次连续触发稳定
|
||||
- `standard / lite` 都可用
|
||||
- 低端机可接受
|
||||
- 不破坏现有状态链
|
||||
|
||||
---
|
||||
|
||||
## 8. 结论
|
||||
|
||||
动画接入前，只要这份清单里有明显回答不出来的问题，就不应该直接开做。
|
||||
先补规格，再接程序。
|
||||
|
||||
|
||||
451
doc/archive/animation/动画设计方案.md
Normal file
451
doc/archive/animation/动画设计方案.md
Normal file
@@ -0,0 +1,451 @@
|
||||
# 动效系统设计方案
|
||||
|
||||
本文档用于整理当前项目后续的动画 / 动效建设方案，目标不是单纯“让界面更花”，而是把动画正式纳入现有架构，成为：
|
||||
|
||||
- 状态感知工具
|
||||
- 空间注意力引导工具
|
||||
- 操作反馈工具
|
||||
- 节奏增强工具
|
||||
|
||||
当前系统已经具备：
|
||||
|
||||
- 地图引擎
|
||||
- 规则引擎
|
||||
- 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. 当前阶段结论
|
||||
|
||||
当前项目已经具备做动画体系的基础。
|
||||
最正确的方向不是继续零散补动效，而是：
|
||||
|
||||
- 先按层组织动画
|
||||
- 再按事件驱动
|
||||
- 最后再做配置化和降级
|
||||
|
||||
一句话总结：
|
||||
|
||||
**后续动画建设应以“打点成功”和“目标状态”两条高频体验为起点，把动画正式纳入现有架构，而不是继续做零散样式补丁。**
|
||||
|
||||
Reference in New Issue
Block a user