diff --git a/animation-dictionary.md b/animation-dictionary.md new file mode 100644 index 0000000..814624a --- /dev/null +++ b/animation-dictionary.md @@ -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. 阶段结论 + +当前动画系统已经具备: + +- 主链 +- 分层 +- 高价值基础动画 +- 性能等级 + +下一步的重点不是继续零散加动效,而是: + +**按动画字典逐项补齐高频体验链。** + diff --git a/animation-integration-spec.md b/animation-integration-spec.md new file mode 100644 index 0000000..e12a5b4 --- /dev/null +++ b/animation-integration-spec.md @@ -0,0 +1,163 @@ +# 动画接入规格模板 + +## 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. 结论 + +这份模板的目的是把动画从“视觉稿”变成“工程规格”。 +只有规格明确,程序才能稳定接入。 + diff --git a/animation-integration-workflow.md b/animation-integration-workflow.md new file mode 100644 index 0000000..fdebce5 --- /dev/null +++ b/animation-integration-workflow.md @@ -0,0 +1,268 @@ +# 动画接入工作流 + +## 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. 结论 + +动画接入的正确方式不是: + +**拿到设计稿 -> 直接写代码** + +而是: + +**拿到设计稿 -> 转成动画规格 -> 纳入动画字典 -> 选技术实现 -> 做性能分级 -> 再接程序** + diff --git a/animation-review-checklist.md b/animation-review-checklist.md new file mode 100644 index 0000000..a513cbd --- /dev/null +++ b/animation-review-checklist.md @@ -0,0 +1,162 @@ +# 动画接入评审清单 + +## 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. 结论 + +动画接入前,只要这份清单里有明显回答不出来的问题,就不应该直接开做。 +先补规格,再接程序。 + diff --git a/miniprogram/pages/map/map.wxml b/miniprogram/pages/map/map.wxml index 8280b9e..2cd9d49 100644 --- a/miniprogram/pages/map/map.wxml +++ b/miniprogram/pages/map/map.wxml @@ -566,6 +566,13 @@ Mock Speed {{mockSpeedText}} + + {{gpsTracking ? '停止定位' : '开启定位'}} + + + 真实定位 + 模拟定位 + 心率 Heart Rate @@ -675,13 +682,6 @@ North Ref {{northReferenceText}} - - {{gpsTracking ? '停止定位' : '开启定位'}} - - - 真实定位 - 模拟定位 - {{northReferenceButtonText}}