Rinne 0.1.0

Rinne 是一个面向现代 Web 的高性能、纯叠加补间动画引擎。

特色

Rinne 尝试采用一种基于物理偏移的累加模型，通过在内部维护统一的计算缓冲区，在高性能与复杂编排之间取得平衡。

• 增量叠加: 将动画视为偏移信号进行实时累加，用数学手段处理并发动画间的逻辑冲突。
• 单次写回: 无论有多少叠加信号，每帧仅对目标执行一次物理赋值。
• 确定性: 提供稳定的 seek 功能，为交互式预览与动画调试提供可靠基础。

安装

npm install @shxnovel/rinne

子路径导出

Rinne 支持按需引入插件以优化包体积：

import { rinne } from "@shxnovel/rinne";
import { ColorPlugin } from "@shxnovel/rinne/plugins/color";
import { VectorPlugin } from "@shxnovel/rinne/plugins/vector";
// ...

快速上手

实时动画

// 1. 目标值动画：将属性平滑移动至 100。
// 动画结束后，物体将停留在 100。
rinne.to(target, { x: 100 }, { duration: 1000 });

// 2. 叠加 (Additive)：在当前位置上额外叠加 50 的位移信号。
// 结束后该信号自动归零，物体回到其基础位置 (E.g. 震动、呼吸感)。
rinne.to(target, { x: 50 }, { duration: 1000, additive: true });

// 3. 固定 (Commit)：配合 additive 使用，控制信号结束后是否永久合并进状态。
rinne.to(target, { x: 50 }, { duration: 1000, additive: true, commit: true });

// 4. 相对位移 (快捷语法)：在当前基础上增加 100，在结束时合并进状态。
rinne.to(target, { x: "+=100" }, { duration: 1000 });

演出编排 (Timeline)

Rinne 提供时间轴，用于编排复杂的序列逻辑与时间轴回溯。

const tl = rinne.timeline({ repeat: -1, yoyo: true });

tl.to(mesh.position, { z: 5 }, { duration: 2000, ease: "expo.out" })

  .set(mesh, { visible: true }, 500)

  .addLabel("scene", 3000)

  .to(light, { intensity: 0 }, { duration: 500 }, "scene+=200")

  .call(() => console.log("event"), "scene");

tl.seek(1500);

回调

rinne.to(target, { x: 100 }, {
    duration: 1000,
    onStart: () => console.log("Started"),
    onUpdate: (p) => console.log(`Progress: ${p}`), // p in [0, 1]
    onComplete: () => console.log("Completed"),
  },
);

性能表现

50,000 活跃节点实测 (Node.js/V8):

• 渲染循环: ~1.3ms / 帧
• 物理写回: ~1.2ms / 帧

许可证

MIT

局限

目前，timeline 的实验性 add 方法用于同步不同的时间轴，但

• 这会忽视子轴的 TimeScale 等，无法从父轴确定总时长。
• 忽视无视子轴的 pause

为了避免这些问题，在编排动画时，请先构建一个完整的 timeline，再将它添加到其他 timeline 中。

tl.add(otherTimeline, 1000);