threejs-agents-scene-builder

threejs-agents-scene-builder

目的

このスキルは、Three.js のシーン全体を構築するためのオーケストレーションガイドです。ユースケースに応じて、適切なライティング、マテリアル、カメラ、コントロール、環境、ポストプロセッシングの組み合わせを選ぶための判断ツリーを提供します。3D シーンやビジュアライゼーションの作成を依頼された場合は、必ず最初にこのスキルを参照してください。

---

マスター判断ツリー：ユースケースからシーンのレシピへ

ステップ 1：ユースケースを特定する

ユースケース	移動先
製品ビューアー／コンフィギュレーター	Recipe A
建築ウォークスルー	Recipe B
ゲームレベル／インタラクティブな 3D	Recipe C
データビジュアライゼーション／チャート	Recipe D
ポートフォリオ／ヒーローセクション	Recipe E
CAD／BIM／IFC ビューアー	Recipe F
AR／XR エクスペリエンス	Recipe G

ステップ 2：R3F と命令型のどちらかを選ぶ

条件	判断
プロジェクトで React を使用している	必ず React Three Fiber（R3F）を使用する
プロジェクトで Vue、Svelte、またはバニラ JS を使用している	必ず命令型の Three.js を使用する
レンダーループを最大限に制御する必要がある	命令型の Three.js を優先する
コンポーネントを再利用して迅速にプロトタイピングする	R3F + Drei を優先する
インタラクション用フレームワークを使わない静的シーン	どちらでも対応できます。命令型のほうが軽量です

相互参照： R3F のパターンについては threejs-impl-r3f、命令型のパターンについては threejs-core-scene-graph を参照してください。

---

判断ツリー：ライティングの設定

ステップ 1：シーンの種類に応じたライティング戦略

シーンの種類	主光源	補助光	シャドウ
屋外／昼光	DirectionalLight（太陽）	HemisphereLight（空／地面）	DirectionalLight のシャドウ、PCFSoftShadowMap
屋内／部屋	PointLight または SpotLight（照明器具）	AmbientLight（弱）	SpotLight のシャドウ、2～3 個に制限
スタジオ／製品	SpotLight（キー）+ SpotLight（リム）	AmbientLight または HemisphereLight	ContactShadows（Drei）または AccumulativeShadows
スタイライズ／トゥーン	DirectionalLight	HemisphereLight	任意。くっきりした輪郭には BasicShadowMap
HDR 環境のみ	なし（IBL がすべてのライティングを提供）	なし	ContactShadows または AccumulativeShadows
夜間／暗所	SpotLight（光だまりに集中）	AmbientLight（ごく弱く、約 0.05）	SpotLight のシャドウ

ステップ 2：ライティングの強度（物理的に正確、r160 以降）

光源の種類	単位	屋内の標準値	屋外の標準値
DirectionalLight	lux	1～5	1～3（シーンのスケールに依存）
PointLight	candela	50～200	該当なし
SpotLight	candela	100～500	該当なし
AmbientLight	単位なし	0.1～0.5	0.2～0.5
HemisphereLight	単位なし	0.3～0.8	0.5～1.0

ステップ 3：光源数の予算

プラットフォーム	リアルタイム光源の最大数	シャドウを投影する光源の最大数
モバイル	3～4	1（DirectionalLight のみ）
デスクトップ	8～16	2～3（モバイルでは PointLight のシャドウは絶対に使用しない）
ハイエンド	16 以上（TiledLighting を使用）	4～5

重要なルール：

• モバイルでは PointLight のシャドウを絶対に使用しないでください。1 つにつき 6 回のシャドウマップ描画が必要です。
• ターゲットを再配置する場合は、必ず directionalLight.target をシーンに追加してください。
• RectAreaLight を作成する前に、必ず RectAreaLightUniformsLib.init() を呼び出してください。

相互参照： シャドウの調整とアーティファクトの修正については threejs-impl-lighting-shadows を参照してください。

---

判定ツリー：マテリアルの選択

視覚的な目標	マテリアル	備考
リアルな表現／PBR	MeshStandardMaterial	ほとんどのシーンで標準の選択肢です
リアルな表現＋クリアコート、透過、シーン	MeshPhysicalMaterial	Standard より負荷が高いため、必要な場合にのみ使用します
トゥーン／セルシェーディング	MeshToonMaterial	段階的な表現には gradientMap テクスチャが必要です
ライティングなし／フラットカラー	MeshBasicMaterial	ライティングのコストがゼロで、ワイヤーフレームや UI に適しています
パフォーマンスが重要（オブジェクトが多数）	MeshLambertMaterial	頂点ライティングを使用するため、Standard より低負荷です
ガラス／透明	MeshPhysicalMaterial (transmission: 1)	または R3F の Drei MeshTransmissionMaterial
反射する床	Drei MeshReflectorMaterial	R3F 専用
カスタムシェーダー	ShaderMaterial または RawShaderMaterial	GLSL を完全に制御できます
ノードベース（WebGPU）	MeshStandardNodeMaterial	TSL ノードシステム。r160+

重要なルール：

• MeshStandardMaterial で十分な場合、MeshPhysicalMaterial は絶対に使用しないでください。大幅に高負荷です
• defines または extensions を変更した後は、必ず material.needsUpdate = true を設定してください
• オブジェクトをシーンから削除するときは、必ずマテリアルを破棄してください

関連項目： マテリアルのプロパティとテクスチャについては threejs-syntax-materials を参照してください。

---

判定ツリー：カメラの選択

用途	カメラの種類	一般的な設定
ほとんどの 3D シーン	PerspectiveCamera	fov: 50-75、near: 0.1、far: 1000
製品ビューアー（遠近感の歪みなし）	PerspectiveCamera	fov: 35-45（狭いほど歪みが少なくなります）
建築（広角）	PerspectiveCamera	fov: 60-90
2D ゲーム／アイソメトリック	OrthographicCamera	ワールド単位に合わせてフラスタムを設定します
CAD／テクニカルドローイング	OrthographicCamera	必ず使用します
データの可視化（平面）	OrthographicCamera	フラスタム = データ範囲
映画的／ドラマチックな表現	PerspectiveCamera	fov: 20-35（望遠効果）

重要なルール：

• fov、near、far、または aspect を変更した後は、必ず camera.updateProjectionMatrix() を呼び出してください
• near を 0 に設定しないでください。シーン全体で Z ファイティングが発生します
• near/far の比率はできる限り小さく保ってください（理想は < 1:10000）

関連項目： カメラ API の詳細については threejs-core-renderer-camera を参照してください。

---

判定ツリー：コントロールの選択

インタラクションのパターン	コントロール	備考
オブジェクトの周囲をオービット（最も一般的）	OrbitControls	必ずダンピングを有効にしてください
マップ／トップダウンナビゲーション	MapControls	左ドラッグ = パン、右ドラッグ = 回転
一人称視点／ウォークスルー	PointerLockControls	ポインターロック API が必要です
フライスルー（6DOF）	FlyControls	キーボード＋マウス
ドラッグして回転（プレゼンテーション）	Drei PresentationControls	R3F 専用。スプリング物理を使用
スクロール連動アニメーション	Drei ScrollControls	R3F 専用
オブジェクトの操作（移動／回転／拡大縮小）	TransformControls	選択したオブジェクトにアタッチします
モバイルに適したオービット	OrbitControls	タッチジェスチャーを内蔵

重要なルール：

• enableDamping が true の場合、アニメーションループ内で必ず controls.update() を呼び出してください
• クリーンアップ時には、必ず controls.dispose() を呼び出してください
• 変形操作中に OrbitControls を無効にせず、OrbitControls と TransformControls を併用しないでください

関連項目： コントロール API の詳細については threejs-syntax-controls を参照してください。

---

判断ツリー：環境設定

視覚的な目標	アプローチ	実装
リアルな反射＋環境光	HDR環境マップ	scene.environment = pmremGenerator.fromEquirectangular(hdrTexture)
単色の背景	scene.background = new Color(...)	最もシンプルな方法
グラデーション背景	背景平面にカスタムシェーダーを適用	または透明なキャンバスの背後にCSSグラデーションを配置
スカイボックス	scene.background にCubeTextureを設定	6面の画像
プロシージャルな空	Dreiの<Sky>またはThree.jsのSkyアドオン	太陽の位置を動的に設定
背景なし（透明）	renderer = new WebGLRenderer({ alpha: true })	背後に表示される内容はCSSで制御
R3F環境	Dreiの<Environment preset="studio" />	プリセット：apartment、city、dawn、forest、lobby、night、park、studio、sunset、warehouse

重要なルール：

• PBRマテリアル用の環境マップには、必ずPMREMGeneratorを使って事前フィルタリングしてください
• 未処理のHDRテクスチャをscene.environmentに設定してはいけません。必ずPMREM処理してください
• scene.environmentを設定すると、すべてのPBRマテリアルに自動的にIBLが適用されます

関連項目： マテリアルでの環境マップの使用方法についてはthreejs-syntax-materialsを参照してください。

---

判断ツリー：ポストプロセス

ポストプロセスを追加するタイミング

条件	判断
シーンが平坦に見える、または奥行きが足りない	SSAO/GTAO＋控えめなブルームを追加
グロー／発光ハイライトが必要	UnrealBloomPassを追加
アンチエイリアスが必要（MSAAなし）	FXAAまたはSMAAを追加
映画のような見た目にしたい	BokehPass（DoF）＋FilmPass（グレイン）＋LUTPass（カラーグレーディング）を追加
選択範囲をアウトライン表示したい	OutlinePassを追加
パフォーマンスが最優先（モバイル）	ポストプロセスは絶対に追加しないでください。ベイク済みエフェクトを使用してください

ポストプロセスのパイプライン順序

パスは必ず次の順序にしてください：

1. RenderPass（美麗なレンダリング）— 必ず最初
2. ジオメトリパス：SSAO、GTAO、SSR
3. エフェクトパス：Bloom、DoF、Outline
4. アンチエイリアス：FXAAまたはSMAA
5. カラーグレーディング：LUT、Film
6. OutputPass（トーンマッピング＋色空間）— 必ず最後

R3Fのポストプロセス

R3Fでは、@react-three/postprocessing（pmndrs/postprocessingライブラリをラップ）を使用します：

import { EffectComposer, Bloom, SSAO } from '@react-three/postprocessing'

<EffectComposer>
  <SSAO />
  <Bloom luminanceThreshold={0.9} intensity={0.5} />
</EffectComposer>

重要なルール：

• ウィンドウのサイズが変更されたら、必ずコンポーザーのサイズを変更してください：composer.setSize(w, h)
• 最後にOutputPassを忘れてはいけません。これがないと、トーンマッピングと色空間変換がスキップされます
• R3Fでは、@react-three/postprocessingがパスの順序を自動的に処理します

関連項目： パスの設定と調整についてはthreejs-impl-postprocessingを参照してください。

---

シーン構成チェックリスト

シーンを構築する際は、必ず次のチェックリストに従ってください：

1. レンダラー — antialias: trueでWebGLRendererを作成し、ピクセル比とサイズを設定
2. シーン — Sceneを作成し、背景や環境を設定
3. カメラ — 判断ツリーに従って種類を選び、位置を設定
4. ライティング — 判断ツリーに従ってレシピを選び、予算を守る
5. 地面／環境 — 地面の平面、環境マップ、または空を追加
6. コンテンツ — ジオメトリの追加、モデルの読み込み、マテリアルの作成
7. コントロール — 判断ツリーに従って選び、制約を設定
8. シャドウ — レンダラー＋ライト＋オブジェクトで有効化（3段階での明示的な有効化）
9. ポストプロセス — 必要に応じて追加し、パイプラインの順序に従う
10. リサイズ処理 — 必ずウィンドウのリサイズに対応する（カメラ＋レンダラー＋コンポーザー）
11. アニメーションループ — requestAnimationFrameまたはR3FのuseFrame
12. 破棄処理 — クリーンアップ時にジオメトリ、マテリアル、テクスチャを必ず破棄する

---

パフォーマンス早見表

最適化	適用するタイミング
InstancedMesh	同一のオブジェクトが50個を超える場合
LOD（Level of Detail）	遠方のオブジェクトがある大規模なシーン
frustumCulled: true（デフォルト）	オブジェクトを画面外にも描画する必要がない限り、常に有効にしておきます
matrixAutoUpdate: false	決して移動しない静的オブジェクト
テクスチャ圧縮（KTX2/Basis）	本番環境では常に使用します。GPU メモリを4〜6倍削減します
ジオメトリの結合	同じマテリアルを使用する小さな静的メッシュが多数ある場合
frameloop="demand"（R3F）	静的なシーン／コンフィギュレーター
ライティングのベイク	静的な環境
オブジェクトプーリング	頻繁に作成・破棄されるオブジェクト

相互参照： 詳細な最適化戦略については、threejs-errors-performance を参照してください。

---

参考リンク

• references/methods.md — 詳細な選択基準を示す判断ツリー
• references/examples.md — 各ユースケース向けの完全なシーンレシピ
• references/anti-patterns.md — シーン構成でよくある間違い

関連スキル

スキル	参照するタイミング
threejs-core-scene-graph	シーン階層、Object3D API、破棄処理
threejs-core-renderer-camera	レンダラーのセットアップ、カメラの設定
threejs-core-math-transforms	ベクトル、行列、座標変換
threejs-syntax-geometry	BufferGeometry、組み込み形状、InstancedMesh
threejs-syntax-materials	マテリアルのプロパティ、テクスチャ、環境マップ
threejs-syntax-loaders	GLTF、FBX、OBJ の読み込みと最適化
threejs-syntax-controls	カメラコントロールのセットアップと設定
threejs-impl-lighting-shadows	ライトの種類、シャドウの設定、アーティファクト
threejs-impl-animation	キーフレームアニメーション、モーフターゲット、スケルタルアニメーション
threejs-impl-postprocessing	EffectComposer、ブルーム、SSAO、アンチエイリアス
threejs-impl-physics	Rapier/Cannon.js の統合
threejs-impl-r3f	React Three Fiber のパターンとフック
threejs-impl-webgpu	WebGPU レンダラー、TSL ノードマテリアル
threejs-impl-ifc	IFC/BIM モデルの読み込みと処理
threejs-errors-performance	FPS の最適化、メモリリーク、ドローコール
threejs-errors-rendering	視覚的なアーティファクト、Zファイティング、色の問題
threejs-agents-model-optimizer	GLTF の最適化、圧縮、LOD の生成

公式ソース

• https://threejs.org/docs/
• https://threejs.org/examples/
• https://r3f.docs.pmnd.rs/
• https://drei.docs.pmnd.rs/