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