three-best-practices

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	デバッグと開発者ツール	LOW	debug-

クイックリファレンス

0. モダンなセットアップ（FUNDAMENTAL）

• setup-use-import-maps - 古い CDN スクリプトではなく、Import Maps を使用する
• setup-choose-renderer - WebGLRenderer（デフォルト）と 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 ループを 1 つだけ使用する
• 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. 描画コールの最適化（最重要）

• draw-call-optimization - 1 フレームあたりの描画コール数を 100 未満に抑えます
• geometry-instanced-mesh - 同一オブジェクトには InstancedMesh を使用します
• geometry-batched-mesh - ジオメトリが異なる場合は、同じマテリアルで BatchedMesh を使用します
• geometry-merge-static - BufferGeometryUtils で静的ジオメトリを結合します

4. ジオメトリ（重要）

• 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. マテリアルとテクスチャ（重要）

• 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. アセット圧縮（重要）

• asset-compression - Draco、Meshopt、KTX2 の圧縮ガイド
• asset-draco - ジオメトリのサイズを 90～95% 削減します
• asset-ktx2 - GPU 圧縮テクスチャ（UASTC と ETC1S）
• asset-meshopt - Draco の代替手段で、より高速に展開できます
• asset-lod - Level of Detail によりフレームレートを 30～40% 向上させます

7. ライティングとシャドウ（中～高）

• 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. シーングラフ（中）

• scene-group-objects - 整理には Groups を使用します
• scene-layers - 選択的なレンダリングには Layers を使用します
• scene-visible-toggle - 追加・削除ではなく visible フラグを使用します
• scene-flatten-static - 静的な階層をフラット化します
• scene-name-objects - デバッグ用にオブジェクトに名前を付けます
• object-pooling - オブジェクトを生成・破棄するのではなく再利用します

9. シェーダー GLSL（中）

• 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 - uniform 配列を優先して使用します
• shader-varying-interpolation - モバイルでは varyings を 3 個までに制限します
• shader-pack-data - データを RGBA チャネルにパックします
• shader-chunk-injection - Three.js のシェーダーチャンクを使用します

10. TSL - Three.js Shading Language（中程度）

• tsl-why-use - onBeforeCompile の代わりに TSL を使う
• tsl-setup-webgpu - TSL 用の WebGPU セットアップ
• tsl-complete-reference - TSL の型システムと関数の完全なリファレンス
• tsl-material-slots - マテリアルノードのプロパティリファレンス
• 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 - ブルーム、ぼかし、被写界深度、AO
• tsl-compute-shaders - GPGPU とコンピュート処理
• tsl-glsl-to-tsl - GLSL から TSL への変換

11. WebGPU レンダラー（中程度）

• 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. 読み込みとアセット（中程度）

• 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（中～高）

• core-web-vitals - 3D 向けの LCP、FID、CLS の最適化
• vitals-lazy-load - IntersectionObserver を使って、スクロールせずに見える範囲より下の 3D を遅延読み込みする
• vitals-code-split - Three.js モジュールを動的にインポートする
• vitals-preload - link タグを使って重要なアセットをプリロードする
• vitals-progressive-loading - 低解像度から高解像度へ段階的に読み込む
• vitals-placeholders - 読み込み中にプレースホルダーのジオメトリを表示する
• vitals-web-workers - 負荷の高い処理をワーカーに移す
• vitals-streaming - 大きなシーンをチャンク単位でストリーミングする

14. カメラとコントロール（低～中）

• camera-near-far - near／far クリッピング面を適切な範囲に設定する
• camera-fov - 適切な FOV を選ぶ
• camera-controls-damping - 滑らかな操作のためにダンピングを使う
• camera-resize-handler - リサイズを適切に処理する
• camera-orbit-limits - オービットコントロールの制限を設定する

15. アニメーション（中程度）

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

16. 物理演算（中程度）

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

17. WebXR（中程度）

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

18. オーディオ（低～中）

• audio-spatial - PositionalAudio、HRTF、空間サウンド

19. ポストプロセッシング（中程度）

• postprocessing-optimization - pmndrs/postprocessing ガイド
• postpro-renderer-config - ポストプロセッシング用に AA、ステンシル、深度を無効にする
• postpro-merge-effects - エフェクトを 1 回のパスにまとめる
• postpro-selective-bloom - パフォーマンス向上のための選択的ブルーム
• postpro-resolution-scaling - 解像度を半分にして FPS を 2 倍にする
• postpro-webgpu-native - TSL ベースの WebGPU 向けポストプロセッシング

20. 最適化（高）

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

21. 本番環境（高）

• error-handling-recovery - WebGL コンテキストの喪失と復旧
• migration-checklist - バージョンごとの破壊的変更

22. デバッグと開発ツール（低）

• 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 コード例
• 追加の背景情報と参考資料

主なパターン

最新のインポートマップ

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/",
    "three/tsl": "https://cdn.jsdelivr.net/npm/[email protected]/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));