在 React Three Fiber 中为程序化运动…

适用于 React Three Fiber 的连续变换、GLTF 剪辑、协调过渡和 demand-loop 动画，用 useFrame、阻尼和剪辑控制解决动画归属、时序与性能问题。

适用场景

解决思路

1. 先检查项目已安装的 Fiber、Drei 和 React 版本；示例面向 Fiber 9 / React 19。若项目已有动画库且已满足任务，保留它，不要为了示例替换。
2. 选择动画归属：连续变换或 uniform 用 useFrame + refs；React state 只描述离散目标，例如 selected、open、active。
3. 有作者制作的 GLTF 剪辑时用 Drei useAnimations；阅读 references/clips.md 以处理独立动画实例和清理。
4. 协调过渡用项目已有的 spring/tween 库；添加前检查其 React peer dependencies。不要仅为了动画一个 mesh 引入状态管理器。
5. 模拟刚体变换交给 Rapier 拥有；通过物理 API 动画 kinematic 目标，不要用 mesh positions 与模拟对抗。
6. 把阻尼组件挂载在 Canvas 下；该做法也适用于 frameloop="demand"。点击 box 切换目标。
7. 使用 useRef<Mesh>(null) 保存 mesh，useState(false) 保存 active，useThree((state) => state.invalidate) 获取 invalidate，并令 target = active ? 1 : -1。
8. 在 useEffect 中以 [target, invalidate] 为依赖调用 invalidate()，目标变化时请求一帧。
9. 在 useFrame((_, delta) => { ... }) 中先检查 mesh.current；用 const x = MathUtils.damp(mesh.current.position.x, target, 6, Math.min(delta, 0.1)) 计算阻尼位置；这里的 delta 限制用于视觉过渡恢复跳变，不是物理模拟步长。
10. 计算 moving = Math.abs(x - target) > 0.001；moving 时把 mesh.current.position.x 设为 x，否则直接设为 target；moving 时调用 invalidate()。
11. 返回 mesh 并设置 ref={mesh}、name="moving-box"、onClick={() => setActive((value) => !value)}；内部放 <boxGeometry /> 和 <meshStandardMaterial color={active ? 'orange' : 'coral'} />。
12. 把 delta 当作秒：速度积分写成 position += velocity * delta；指数平滑用 MathUtils.damp 或 lerp 配合 1 - exp(-lambda * delta)。固定 lerp 比例依赖刷新率；delta * speed 可能过冲。
13. 复用 vectors/quaternions，避免每帧分配；方向插值用 quaternion interpolation，不要分别 lerp Euler angles 跨越环绕边界。
14. 只使用一个 timeline/clock owner。Fiber 9 仍提供 state.clock；不要替换 Fiber 内部实现，因为 Three.js 已废弃新的独立 Clock 实例。若需要独立 Three.js 计时，查阅已安装版本中的 Timer。
15. 按需渲染时，外部动画系统在活动期间需要 invalidation：启动同步动画前先 invalidate，且若首帧会跳变，把启动安排到下一帧。
16. 支持时在 frame callback 中直接读取快速变化的外部状态（例如 store 的 getState()）；React 只订阅与 UI 相关的变更；清理外部订阅。
17. 不要断言普通 React re-render 会停止动画；在 memoize 组件前先 profile 实际工作和订阅频率。
18. 隐藏对象不会停止其 frame callback 或 mixer；适当时显式暂停昂贵动画；装饰性运动要尊重 reduced-motion 偏好。
19. 重复振荡和 shader motion 可从 elapsed time 推导 phase；需要可复现的模拟必须用 fixed-step 设计，而不是任意 delta clamping。
20. 验证时对比不同帧率下的运动、后台/恢复行为、重复改变目标。
21. 按需渲染时确认对象唤醒、到达目标并停止请求帧。
22. 对剪辑测试两个实例播放不同 action。

适用边界 · 注意事项

• 碰撞驱动的运动不要用本技能；应交给物理引擎或物理指南处理。
• 项目已有动画库已满足任务时不要替换它；不要仅为动画一个 mesh 引入状态管理器。
• 需要可复现的固定步长模拟时不要用任意 delta clamping 或普通阻尼方案。