企业官网建设流程全解析

Bible Strong Avatar Lab 是一个浏览器端程序化 2D 头像设计工作台，它背后的纯函数播放引擎用「无状态 + 注入时间」的方式实现确定性动画：同一份动画定义、同一个随机源，在任何环境里都会跑出逐帧相同的画面。本文带你用最少代码看懂它的实现：播放状态机如何推进、眨眼如何被精确排程、暂停恢复为何不跳帧。

一、什么是「确定性动画」？传统动画为什么做不到逐帧复现

普通网页动画常常这样写：页面一加载就调用Math.random()决定何时眨眼、Date.now()决定进度。听起来方便，但有两个坑 🕳️：

• 不可复现：换个时间、换台电脑，动画节奏就不一样；
• 不可测试：你没法在单元测试里断言「第 3600 毫秒时角色应该闭眼」，因为时间永远在流动。

Bible Strong Avatar Lab 的思路是反过来：引擎本身不认识「现在几点」。所有时间、随机数都由外部「注入」，引擎只负责把「输入 → 输出」算对。这就是纯函数（Pure Function）：同样的输入永远得到同样的输出。

二、播放引擎三件套：状态、时间轴、渲染

打开 packages/avatar-core/src/runtime.ts，你会看到三个各司其职的角色 👇

注意advanceAvatarPlayback的签名（L134-L139）：definition、state、now、environment四个参数全是显式传入的——没有任何全局时钟、没有副作用，返回值就是一个新的状态对象。

1. 每个动画步骤 = 「过渡 → 保持」两段时钟

播放状态里有两个关键字段（L47-L66）：phase（transition或hold）和phaseStartedAt。推进逻辑在 L162-L184：

1. 当前阶段还没到时长？原样返回，不浪费时间；
2. 到了就把phaseStartedAt往后加duration，transition转成hold；
3. hold结束就调用nextCursor()走到下一步。

nextCursor()（L113-L132）处理三种播放模式：loop循环、once播完即停、pingPong来回播放。它只依赖「当前步 + 方向」，依然是一个纯函数。

2. 为什么用「while 循环 + 安全计数器」？

L161-L184 里有个safety = steps.length * 4 + 4的循环。这解决了时间跳变问题：如果你的标签页卡住 10 秒再恢复，一次性传入的now可能跨越好几个步骤——循环会把所有「过期」的阶段一次补齐，画面直接落到正确位置，而不是慢慢追帧。

三、眨眼机制：随机但可复现的排程

最妙的设计是眨眼 👀。它的节奏是随机的（不然像机器人），但又是确定性的（不然没法测试）。秘诀只有一个：随机数不是引擎自己生成的，而是从外部注入的。

1. 注入式随机源

AvatarRuntimeEnvironment（L73-L76）里有一个random: () => number。生产环境传Math.random，测试环境可以传() => 0.5或() => 0。

眨眼排程在 L152-L160：

• 首次眨眼的截止时间 = 播放开始时间 +initialDelayMs；
• 每次眨完后，下一次间隔 =minIntervalMs + random() × (maxIntervalMs - minIntervalMs)。

也就是说，随机性被「压扁」进了一个可复现的公式里：给定同一个random函数，眨眼时间表在宇宙中任何地方都完全一致。

2. 闭眼曲线：一个绝对值三角波

眨眼的「眼皮开合」由blinkOpacityAt()计算（L263-L272）：

return Math.abs(progress * 2 - 1)

• progress从 0 到 1 时，眼皮从睁开（1）→ 闭合（0，出现在progress = 0.5）→ 睁开（1）；
• 整个过程只由blinkStartedAt和now决定，没有定时器、没有补间动画库。

单元测试 packages/avatar-core/src/tests/core-test.ts 里有一段绝佳的演示（L300-L311）：注入random: () => 0，播放从 1000ms 开始，则断言blinkStartedAt === 3600、blinkDueAt === 7280——眨眼时刻被精确钉死。

3. 眨眼参数从哪里来？

每个动画都自带一份blink配置（见BlinkSettings，src/features/animation/sequences.ts L21-L27）：

对应定义见 createSequence()。

四、暂停与恢复：不改进度，只挪时间

暂停如果实现不当，很容易「跳帧」。avatar-core 的做法非常优雅：

• pauseAvatarPlayback()（L188-L192）只记录pausedAt；
• resumeAvatarPlayback()（L194-L218）把暂停时长pauseDuration整体加到所有时间戳上：phaseStartedAt、blinkDueAt、blinkStartedAt全部平移。

效果：恢复的那一刻，画面和暂停前那一帧逐像素一致，然后继续走。测试 core-test.ts L280-L298 验证了这一点——半程暂停 3 秒再恢复，phaseStartedAt从 1000 变成 4000，渲染出的leftPath与暂停前完全相同。

五、Studio 编辑器里的另一套「同源」实现

上面讲的是可导出的avatar-core包。Studio 编辑界面（React）自己还有一套播放逻辑，思想完全一致，只是用了setTimeout做调度：

• 时间轴状态：PlaybackTimeline记录position、direction、stepDueAt、blinkDueAt等（src/features/animation/playback.ts L3-L19）；
• 调度函数全是纯函数：schedulePlaybackStep()、schedulePlaybackBlink()只把「截止时间 = now + delay」写进状态并返回新对象（playback.ts L31-L37）；
• 暂停换算剩余毫秒：pausePlaybackTimeline()在暂停瞬间把「绝对截止时间」换算成「剩余毫秒」，恢复时从剩余量继续（playback.ts L39-L53）——这正是 core 包「时间平移」思路的等价实现；
• 光标推进：advanceSequenceCursor()与 core 包的nextCursor()逻辑对应（playback.ts L55-L66 与 sequences.ts L247-L265）。

真正的编排者 src/features/studio/useStudioController.ts 里的launchSequence()（L1075-L1171）负责把这些纯函数串起来：启动时beginPlayback()，每步结束scheduleAdvance()，眨眼循环里用Math.random()抽间隔（L1138-L1145）。

单元测试 src/features/animation/tests/playback-test.ts 甚至断言了「在 1200ms 暂停、步骤本应 1500ms 到期」时，stepRemainingMs恰好等于 300（L23-L32）。

💡 一个有趣的细节：编辑器的环境微动（眨眼之外的头部漂移、眼球抖动）用的也不是真随机，而是 packages/avatar-core/src/ambientMotion.ts 里的确定性伪噪声——hash()函数（L13-L16）用正弦散列把时间映射成 [-1, 1] 的「随机」数，所以连呼吸感都能逐帧复现。

六、为什么说这套设计「对新手也很友好」

• 🧪可测试：时间戳和随机源都是参数，测试可以钉死任何一帧（前文core-test.ts里全部如此）；
• 📦可移植：@bible-strong/avatar-core不依赖 React、DOM 或浏览器存储（见 packages/avatar-core/README.md），同一份动画定义可以在 React、原生 DOM、甚至 Node 里跑出相同结果；
• 📜JSON 即唯一事实源：每个动画都显式写在定义文件里，resolveAnimation()对不存在的 key 返回带类型的错误（runtime.ts L34-L45），而不是默默兜底；
• ♿尊重系统设置：传入reduceMotion: true后，过渡与环境微动会直接跳到目标帧，但眨眼依然按配置工作——见 sampleAvatarFrame() L294-L310。

七、总结：确定性 = 无状态 + 注入时间 + 注入随机

Bible Strong Avatar Lab 的播放引擎可以用一句话概括：引擎不提问「现在几点」，而是被告知「现在几点」。

想动手验证？运行pnpm test就能看到 core-test.ts 里那些「3600ms 准时眨眼」的断言。理解了这套「纯函数播放引擎」，你也能把它迁移到自己的动画系统里——让每一帧都有据可查、有迹可循 ✨