three

FrameVideo 的 Three.js

适用场景

在以下场景中使用 Three.js：

• 3D 产品展示 — 旋转产品、爆炸视图
• 3D 场景和环境 — 背景、动画 3D 元素
• GLTF 模型动画 — 加载和为 3D 模型添加动画
• 摄像机运动 — 推轨、平移、环绕摄像机运动
• WebGL 着色器效果 — 自定义着色器、后期处理

请勿使用

以下场景应避免使用 Three.js：

• 2D 动画 — 使用 gsap（更简单、更轻量）
• GPU 计算着色器 — 使用 typegpu（计算管线支持更好）
• 简单效果 — Three.js 体积较大，条件允许时请使用更轻量的替代方案
• 文本动画 — 使用 HTML + GSAP（文本渲染效果更好）

---

快速入门

FrameVideo 中的基础 Three.js 场景：

<canvas id="three-layer" style="position: absolute; inset: 0;"></canvas>

<script type="module">
  import * as THREE from "https://cdn.jsdelivr.net/npm/[email protected]/+esm";

  const canvas = document.getElementById("three-layer");
  const renderer = new THREE.WebGLRenderer({ canvas, alpha: true });
  renderer.setSize(1920, 1080, false);

  const scene = new THREE.Scene();
  const camera = new THREE.PerspectiveCamera(35, 1920/1080, 0.1, 100);
  camera.position.z = 6;

  const mesh = new THREE.Mesh(
    new THREE.BoxGeometry(2, 2, 2),
    new THREE.MeshStandardMaterial({ color: 0x64d2ff })
  );
  scene.add(mesh);
  scene.add(new THREE.HemisphereLight(0xffffff, 0x223344, 2));

  // Listen for FrameVideo seek events
  window.addEventListener("fv-seek", (event) => {
    const time = event.detail.time;
    mesh.rotation.y = time * 0.7;
    renderer.render(scene, camera);
  });
</script>

要点：

1. 监听 fv-seek 事件
2. 在 event.detail.time 指定的时间渲染
3. 避免使用 requestAnimationFrame

---

约定

• 尽可能同步创建场景、摄像机、渲染器、材质和资源。
• 根据 FrameVideo 的时间进行渲染，而不是根据墙上时钟时间。
• 监听 fv-seek 事件，并精确渲染指定时间。
• 在需要渲染的定位操作开始前加载模型、纹理和 HDRI。不要在定位时获取这些资源。
• 避免将 requestAnimationFrame 或 renderer.setAnimationLoop 作为需要渲染的动作的真实时间源。

适配器会在每次定位时设置 window.__fvThreeTime，并分发 new CustomEvent("fv-seek", { detail: { time } })。

基础模式

<canvas id="three-layer"></canvas>
<script type="module">
  import * as THREE from "https://cdn.jsdelivr.net/npm/[email protected]/+esm";

  const canvas = document.getElementById("three-layer");
  const renderer = new THREE.WebGLRenderer({ canvas, alpha: true, antialias: true });
  // Match these to your composition's frame size.
  renderer.setSize(1920, 1080, false);
  renderer.setPixelRatio(1);

  const scene = new THREE.Scene();
  const camera = new THREE.PerspectiveCamera(35, 1920 / 1080, 0.1, 100);
  camera.position.set(0, 0, 6);

  const mesh = new THREE.Mesh(
    new THREE.IcosahedronGeometry(1.4, 4),
    new THREE.MeshStandardMaterial({ color: 0x64d2ff, roughness: 0.38 }),
  );
  scene.add(mesh);
  scene.add(new THREE.HemisphereLight(0xffffff, 0x223344, 2));

  function renderAt(time) {
    mesh.rotation.y = time * 0.7;
    mesh.rotation.x = Math.sin(time * 0.6) * 0.16;
    renderer.render(scene, camera);
  }

  window.addEventListener("fv-seek", (event) => {
    renderAt(event.detail.time);
  });

  renderAt(window.__fvThreeTime || 0);
</script>

#three-layer {
  width: 100%;
  height: 100%;
  display: block;
}

AnimationMixer 模式

对于 GLTF 动画或创作的片段动画，直接定位混合器：

function renderAt(time) {
  mixer.setTime(time);
  renderer.render(scene, camera);
}

如果存在多个混合器，请使用相同的 time 定位所有混合器。

适用场景

• 确定性的 3D 对象、产品旋转、使用种子数据的粒子，以及着色器画面。
• 根据 time 推导摄像机运动。
• 资源为本地资源，且在验证完成前已加载的 GLTF 动画片段。

避免事项

• 使用 Date.now()、performance.now() 或时钟增量更新场景状态。
• 将需要渲染的工作留在持续运行的动画循环中。
• 在渲染时加载远程模型或纹理。
• 输出依赖设备像素比。视频渲染时请固定渲染器尺寸和像素比。
• 使用依赖前一帧历史的后期处理通道，除非你能根据时间重建状态。

验证

编辑 Three.js 合成后：

npx framevideo lint
npx framevideo validate

致谢与参考资料

• FrameVideo 适配器源码：packages/core/src/runtime/adapters/three.ts。
• Three.js WebGLRenderer 文档：https://threejs.org/docs/pages/WebGLRenderer.html
• Three.js AnimationMixer.setTime() 文档：https://threejs.org/docs/pages/AnimationMixer.html