Three.js ベストプラクティス

Three.js アプリケーションの包括的なパフォーマンス最適化ガイド。18 のカテゴリーにおける 120 以上のルールが、影響度の優先順位に基づいて記載されています。

ソース・クレジット

このスキルは複数の信頼できるソースからベストプラクティスをコンパイルしています：

• mrdoob によってメンテナンスされている Three.js llms ブランチの公式ガイドライン
• Utsubo による 100 Three.js Tips - WebGPU、アセット最適化、パフォーマンス ティップスをカバーする優れた包括的ガイド

適用するべき場面

以下の場合はこのガイドラインを参照してください：

• 新しい Three.js プロジェクトをセットアップするとき
• Three.js コードを作成またはレビューするとき
• パフォーマンスを最適化またはメモリリークを修正するとき
• カスタムシェーダー（GLSL または TSL）を操作するとき
• WebGPU 機能を実装するとき
• WebXR で VR/AR エクスペリエンスを構築するとき
• 物理エンジンを統合するとき
• モバイルデバイス向けに最適化するとき

ルールカテゴリー（優先度順）

優先度	カテゴリー	影響度	プリフィックス
0	モダン セットアップ & インポート	FUNDAMENTAL	setup-
1	メモリ管理 & 破棄	CRITICAL	memory-
2	レンダーループ最適化	CRITICAL	render-
3	ドローコール最適化	CRITICAL	drawcall-
4	ジオメトリ & バッファ管理	HIGH	geometry-
5	マテリアル & テクスチャ最適化	HIGH	material-
6	アセット圧縮	HIGH	asset-
7	ライティング & シャドウ	MEDIUM-HIGH	lighting-
8	シーングラフ組織	MEDIUM	scene-
9	シェーダー ベストプラクティス (GLSL)	MEDIUM	shader-
10	TSL (Three.js Shading Language)	MEDIUM	tsl-
11	WebGPU レンダラー	MEDIUM	webgpu-
12	ロード & アセット	MEDIUM	loading-
13	Core Web Vitals	MEDIUM-HIGH	vitals-
14	カメラ & コントロール	LOW-MEDIUM	camera-
15	アニメーション システム	MEDIUM	animation-
16	物理演算 統合	MEDIUM	physics-
17	WebXR / VR / AR	MEDIUM	webxr-
18	オーディオ	LOW-MEDIUM	audio-
19	ポストプロセッシング	MEDIUM	postpro-
20	モバイル最適化	HIGH	mobile-
21	プロダクション	HIGH	error-, migration-
22	デバッグ & DevTools	LOW	debug-

クイックリファレンス

0. モダン セットアップ (FUNDAMENTAL)

• setup-use-import-maps - 古い CDN スクリプトではなく Import Maps を使用
• setup-choose-renderer - WebGLRenderer (デフォルト) vs WebGPURenderer (TSL/compute)
• setup-animation-loop - 手動 RAF ではなく renderer.setAnimationLoop() を使用
• setup-basic-scene-template - 完全なモダン シーン テンプレート

1. メモリ管理 (CRITICAL)

• memory-dispose-geometry - 常にジオメトリを破棄
• memory-dispose-material - 常にマテリアルとテクスチャを破棄
• memory-dispose-textures - 動的に作成されたテクスチャを破棄
• memory-dispose-render-targets - 常に WebGLRenderTarget を破棄
• memory-dispose-recursive - 階層構造に対して再帰的な破棄を使用
• memory-dispose-on-unmount - React のクリーンアップ/アンマウント時に破棄
• memory-renderer-dispose - ビューを破棄するときにレンダラーを破棄
• memory-reuse-objects - ジオメトリとマテリアルを再利用

2. レンダーループ (CRITICAL)

• render-single-raf - 単一の requestAnimationFrame ループ
• render-conditional - 静的シーン用のオンデマンド レンダリング
• render-delta-time - アニメーション用にデルタタイムを使用
• render-avoid-allocations - レンダーループ内でメモリを割り当てない
• render-cache-computations - 高コストな計算をキャッシュ
• render-frustum-culling - フラスタム カリングを有効化
• render-update-matrix-manual - 静的オブジェクトの自動マトリックス更新を無効化
• render-pixel-ratio - ピクセルレートを 2 に制限
• render-antialias-wisely - アンチエイリアシングは慎重に使用

3. ドローコール最適化 (CRITICAL)

• draw-call-optimization - フレームあたり 100 未満のドローコール を目標
• geometry-instanced-mesh - 同一オブジェクト用に InstancedMesh を使用
• geometry-batched-mesh - 異なるジオメトリ（同一マテリアル）用に BatchedMesh を使用
• geometry-merge-static - BufferGeometryUtils で静的ジオメトリをマージ

4. ジオメトリ (HIGH)

• geometry-buffer-geometry - 常に BufferGeometry を使用
• geometry-merge-static - 静的ジオメトリをマージ
• geometry-instanced-mesh - 同一オブジェクト用に InstancedMesh を使用
• geometry-lod - 複雑なモデル用に Level of Detail を使用
• geometry-index-buffer - インデックス付きジオメトリを使用
• geometry-vertex-count - 頂点数を最小化
• geometry-attributes-typed - 適切な型付き配列を使用
• geometry-interleaved - インターリーブ バッファを検討

5. マテリアル & テクスチャ (HIGH)

• material-reuse - メッシュ間でマテリアルを再利用
• material-simplest-sufficient - 機能する最もシンプルなマテリアルを使用
• material-texture-size-power-of-two - 2 の累乗のテクスチャサイズを使用
• material-texture-compression - 圧縮テクスチャ (KTX2/Basis) を使用
• material-texture-mipmaps - ミップマップを適切に有効化
• material-texture-anisotropy - 床用に異方性フィルタリングを使用
• material-texture-atlas - テクスチャ アトラスを使用
• material-avoid-transparency - 透明マテリアルを最小化
• material-onbeforecompile - シェーダー修正用に onBeforeCompile を使用（または TSL）

6. アセット圧縮 (HIGH)

• asset-compression - Draco、Meshopt、KTX2 圧縮ガイド
• asset-draco - ジオメトリサイズを 90-95% 削減
• asset-ktx2 - GPU 圧縮テクスチャ (UASTC vs ETC1S)
• asset-meshopt - Draco の代替案でデコンプレッション高速化
• asset-lod - 30-40% のフレームレート向上のための Level of Detail

7. ライティング & シャドウ (MEDIUM-HIGH)

• lighting-limit-lights - アクティブなライトを 3 個以下に制限
• lighting-shadows-advanced - PointLight コスト、CSM、フェイク シャドウ
• lighting-bake-static - 静的シーン用にライティングをベイク
• lighting-shadow-camera-tight - シャドウ カメラをタイトに調整
• lighting-shadow-map-size - 適切なシャドウ解像度を選択 (512-4096)
• lighting-shadow-selective - シャドウを選択的に有効化
• lighting-shadow-cascade - 大規模シーン用に CSM を使用
• lighting-shadow-auto-update - 静的シーン用に autoUpdate を無効化
• lighting-probe - Light Probes を使用
• lighting-environment - アンビエント ライト用に環境マップを使用
• lighting-fake-shadows - バジェット コンタクト シャドウ用にグラデーション プレーン

8. シーングラフ (MEDIUM)

• scene-group-objects - 組織化用に Groups を使用
• scene-layers - 選択的レンダリング用に Layers を使用
• scene-visible-toggle - 追加/削除ではなく visible フラグを使用
• scene-flatten-static - 静的階層構造をフラットン化
• scene-name-objects - デバッグ用にオブジェクトに名前を付与
• object-pooling - 作成/破棄ではなくオブジェクトを再利用

9. シェーダー GLSL (MEDIUM)

• shader-precision - モバイル用に mediump を使用（約 2 倍高速化）
• shader-mobile - モバイル固有の最適化（varyings、分岐）
• shader-avoid-branching - 条件付きを mix/step に置き換え
• shader-precompute-cpu - CPU で事前計算
• shader-avoid-discard - discard を避け、alphaTest を使用
• shader-texture-lod - 既知のミップレベル用に textureLod を使用
• shader-uniform-arrays - ユニフォーム配列を優先
• shader-varying-interpolation - varyings をモバイル用に 3 個に制限
• shader-pack-data - RGBA チャネルにデータをパック
• shader-chunk-injection - Three.js シェーダー チャンクを使用

10. TSL - Three.js Shading Language (MEDIUM)

• tsl-why-use - onBeforeCompile ではなく TSL を使用
• tsl-setup-webgpu - TSL 用の WebGPU セットアップ
• tsl-complete-reference - 完全な TSL 型システムと関数
• tsl-material-slots - Material ノード プロパティリファレンス
• tsl-node-materials - NodeMaterial クラスを使用
• tsl-basic-operations - 型、操作、スウィズリング
• tsl-functions - Fn() を使用した TSL 関数作成
• tsl-conditionals - TSL での If、select、ループ
• tsl-textures - テクスチャとトリプラナー マッピング
• tsl-noise - 組み込みノイズ関数 (mx_noise_float、mx_fractal_noise)
• tsl-post-processing - bloom、blur、dof、ao
• tsl-compute-shaders - GPGPU とコンピュート操作
• tsl-glsl-to-tsl - GLSL から TSL への変換

11. WebGPU レンダラー (MEDIUM)

• webgpu-renderer - セットアップ、ブラウザ サポート、マイグレーション ガイド
• webgpu-render-async - コンピュート集約的なシーン用に renderAsync を使用
• webgpu-feature-detection - アダプター機能をチェック
• webgpu-instanced-array - GPU 永続バッファ
• webgpu-storage-textures - 読み取り/書き込みコンピュート テクスチャ
• webgpu-workgroup-memory - 共有メモリ（10-100 倍高速化）
• webgpu-indirect-draws - GPU 駆動レンダリング

12. ロード & アセット (MEDIUM)

• loading-draco-compression - 大規模メッシュ用に Draco を使用
• loading-gltf-preferred - glTF フォーマットを使用
• gltf-loading-optimization - DRACO/Meshopt/KTX2 を備えた完全ローダー セットアップ
• loading-progress-feedback - ロード進捗を表示
• loading-async-await - ロード用に async/await を使用
• loading-lazy - 非重要なアセットを遅延ロード
• loading-cache-assets - キャッシングを有効化
• loading-dispose-unused - 未使用アセットをアンロード

13. Core Web Vitals (MEDIUM-HIGH)

• core-web-vitals - 3D 用の LCP、FID、CLS 最適化
• vitals-lazy-load - IntersectionObserver を使用してフォールド下の 3D を遅延ロード
• vitals-code-split - Three.js モジュールを動的インポート
• vitals-preload - リンクタグでクリティカル アセットをプリロード
• vitals-progressive-loading - 低解像度から高解像度への漸進的ロード
• vitals-placeholders - ロード中にプレースホルダー ジオメトリを表示
• vitals-web-workers - 高コスト処理をワーカーに オフロード
• vitals-streaming - チャンクごとに大規模シーンをストリーミング

14. カメラ & コントロール (LOW-MEDIUM)

• camera-near-far - タイトな near/far プレーンを設定
• camera-fov - 適切な FOV を選択
• camera-controls-damping - スムーズなコントロール用にダンピングを使用
• camera-resize-handler - リサイズを適切に処理
• camera-orbit-limits - オービット コントロール制限を設定

15. アニメーション (MEDIUM)

• animation-system - AnimationMixer、ブレンディング、モーフ ターゲット、骨格アニメーション

16. 物理演算 (MEDIUM)

• physics-integration - Rapier、Cannon-es 統合パターン
• physics-compute-shaders - コンピュート シェーダーで GPU 物理演算

17. WebXR (MEDIUM)

• webxr-setup - VR/AR ボタン、コントローラー、ヒット テスト

18. オーディオ (LOW-MEDIUM)

• audio-spatial - PositionalAudio、HRTF、空間オーディオ

19. ポストプロセッシング (MEDIUM)

• postprocessing-optimization - pmndrs/postprocessing ガイド
• postpro-renderer-config - ポスト処理用に AA、ステンシル、デプスを無効化
• postpro-merge-effects - 単一パスで複数のエフェクトを結合
• postpro-selective-bloom - パフォーマンス用に選択的ブルーム
• postpro-resolution-scaling - FPS 向上用に半解像度にスケール
• postpro-webgpu-native - WebGPU 用 TSL ベース ポスト処理

20. 最適化 (HIGH)

• mobile-optimization - モバイル固有の最適化とチェックリスト
• raycasting-optimization - BVH、レイヤー、GPU ピッキング

21. プロダクション (HIGH)

• error-handling-recovery - WebGL コンテキスト喪失と復旧
• migration-checklist - バージョン別の重大な変更

22. デバッグ & DevTools (LOW)

• debug-devtools - 完全なデバッグ ツールキット
• debug-stats-gl - WebGL/WebGPU 監視用 stats-gl
• debug-lil-gui - ライブ パラメータ調整用 lil-gui
• debug-spector - WebGL フレーム キャプチャ用 Spector.js
• debug-renderer-info - ドローコールとメモリを監視
• debug-three-mesh-bvh - BVH を使用した高速レイキャスト
• debug-context-lost - WebGL コンテキスト喪失を処理
• debug-animation-loop-profiling - レンダーループ セクションをプロファイル
• debug-conditional - プロダクションでデバッグコードを削除

使用方法

個別のルール ファイルで詳細な説明とコード例を参照してください：

rules/setup-use-import-maps.md
rules/memory-dispose-geometry.md
rules/tsl-complete-reference.md
rules/mobile-optimization.md

各ルール ファイルには以下が含まれています：

• なぜそれが重要かの簡潔な説明
• 説明付きの BAD コード例
• 説明付きの GOOD コード例
• 追加のコンテキストと参考資料

キーパターン

モダン Import Maps

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.182.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.182.0/examples/jsm/",
    "three/tsl": "https://cdn.jsdelivr.net/npm/three@0.182.0/build/three.tsl.js"
  }
}
</script>

適切な破棄

function disposeObject(obj) {
  if (obj.geometry) obj.geometry.dispose();
  if (obj.material) {
    if (Array.isArray(obj.material)) {
      obj.material.forEach(m => m.dispose());
    } else {
      obj.material.dispose();
    }
  }
}

TSL 基本的な使用方法

import { texture, uv, color, time, sin } from 'three/tsl';

const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = texture(map).mul(color(0xff0000));
material.colorNode = color(0x00ff00).mul(sin(time).mul(0.5).add(0.5));

モバイル検出

const isMobile = /Android|iPhone|iPad|iPod/i.test(navigator.userAgent);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, isMobile ? 1.5 : 2));