threejs-fundamentals

Three.js の基礎

一般的な Three.js ウェブ体験のレンダリング基盤には、このスキルを使用してください。 プレイ可能なゲームのシステム、ライフサイクル、リリース作業には web-game-development を使用してください。 範囲が限定されたレンダリングの課題には、対応する threejs-* スキルを使用してください。

このスキルを使う場面

• シーン、カメラ、レンダラー、キャンバスの所有権、アニメーションループを設定または修正する
• 透視投影と正投影を選択する、またはワールド座標とローカル座標の変換を修正する
• レンダリングをレスポンシブにし、色管理を行い、高 DPI ディスプレイでも安全に動作させる
• シーンが表示されない、コンテンツがクリッピングされる、カメラのフレーミングが不適切、GPU リソースがリークするといった問題を診断する

手順

ステップ 1：プロジェクトの前提を確認する

1. インポートや初期化を変更する前に、インストール済みの three のバージョンと、既存のレンダラー／キャンバスの所有権を確認してください。
2. レンダーループとリサイズリスナーの所有者は、それぞれ 1 つにしてください。React Three Fiber などのフレームワークラッパーがこれらのライフサイクルを管理している場合は、競合する生のループを追加しないでください。
3. バックエンド固有の API を使う前に、レンダリングバックエンドを確認してください。このスキルでは既定で WebGLRenderer を使用します。WebGPU のパターンは、インストール済みの Three.js のリビジョンに照らして確認してください。

ステップ 2：最小限の表示可能なシーンを構築する

ローダー、シェーダー、ポストプロセッシングを追加する前に、明示的にシーン、カメラ、レンダラー、ライト付きメッシュを 1 つずつ用意し、レンダーループを構築してください。

import * as THREE from "three";

const width = window.innerWidth;
const height = window.innerHeight;

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(50, width / height, 0.1, 100);
camera.position.set(0, 1, 4);

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(width, height);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.outputColorSpace = THREE.SRGBColorSpace;

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

function render() {
  renderer.render(scene, camera);
  requestAnimationFrame(render);
}
render();

機能ごとに 1 つのトランスフォームルートを持たせるには、Group を使用してください。position、quaternion、scale は意図を持って変更してください。ローカル座標は親を介して合成されますが、シーンがまだレンダリングされていないときにワールド空間をクエリするには、updateWorldMatrix が必要です。

ステップ 3：リサイズと破棄を明示的に処理する

function resize(width, height) {
  camera.aspect = width / height;
  camera.updateProjectionMatrix();
  renderer.setSize(width, height, false);
}

function disposeObject(root) {
  root.traverse((object) => {
    object.geometry?.dispose();
    const materials = Array.isArray(object.material)
      ? object.material
      : [object.material];
    for (const material of materials) material?.dispose();
  });
}

機能が所有するテクスチャとレンダーターゲットも破棄してください。すべての利用者が使い終わるまでは、共有リソースを破棄しないでください。

ステップ 4：観測可能なレンダリング動作を確認する

• 指定したキャンバスサイズで、メッシュが表示され、カメラのフレーミングが安定していることを確認してください。
• 狭い画面、広い画面、高 DPI の条件でリサイズし、描画バッファーが引き伸ばされないことを確認してください。
• ブラウザーのコンソールで WebGL の警告を確認し、renderer.info は診断にのみ使用してください。テストの判定基準にはしないでください。
• リポジトリに存在する場合は、ビルド、型チェック、および関連するビジュアルテスト／ブラウザーテストを実行してください。

選択ガイド

必要なもの	使用するもの
シーングラフ、カメラ、レンダラー、トランスフォーム、ライフサイクル	このスキル
カスタム頂点、インスタンシング、BufferGeometry	threejs-geometry
PBR プロパティ、メッシュ表面の外観	threejs-materials
ライト、シャドウ、イメージベースドライティング	threejs-lighting
マップ、UV、HDR 背景、レンダーターゲット	threejs-textures
モデル／アセットの読み込みと進捗	threejs-loaders
AnimationMixer、クリップ、ボーン、モーフ	threejs-animation
レイキャスト、コントロール、ピッキング、入力	threejs-interaction
GLSL、マテリアルのシェーダー拡張	threejs-shaders
EffectComposer のスクリーンスペースパス	threejs-postprocessing

例

パースペクティブな製品ビュー

実物に近いオブジェクトの見え方には、PerspectiveCamera を使用してください。必要な場合にのみ、意図的に小さい near 面を設定してください。near 値が不必要に小さいと、深度精度が低下し、Z ファイティングが発生します。

アイソメトリック風のボードビュー

深度によらず縮尺を一定に保つ必要がある場合は、OrthographicCamera を使用してください。リサイズ時にアスペクト比から左／右／上／下を再計算し、updateProjectionMatrix() を呼び出してください。

ベストプラクティス

1. キャンバスごとに requestAnimationFrame の所有者を 1 つにしてください。
2. ピクセル比を上限値で制限してください。上限のないデバイスピクセル比は、気付かないうちに GPU コストを増大させます。
3. 通常の PBR 処理では、ライトのないシーンを場当たり的な色指定で補うのではなく、MeshStandardMaterial と意図的なライティングを使用してください。
4. カメラのクリッピング面は、シーンで許容できる範囲内でできるだけ近づけてください。
5. 機能が割り当てた GPU リソースには、必ず破棄処理を用意してください。

参考資料

• Three.js Fundamentals のソースカバレッジ
• Three.js のドキュメント
• Three.js マニュアル：シーンの作成