threejs

---
name: "threejs"
description: "Three.js（WebGL/3D表現）のScene-Camera-Renderer三位一体と手動メモリ管理を軸に、ウェブ3Dの設計・実装・パフォーマンス最適化を整理する。Three.js、WebGL、React Three Fiber（R3F）、3Dシーン構築、メッシュ/マテリアル/テクスチャ、メモリリーク、dispose()、インスタンシング、シェーダー、GLTFローダーに関する相談で必ず使うこと。ユーザーが「ブラウザで3D」「WebGLで表示」「3Dモデルをウェブに載せたい」「パーティクルエフェクト」と言った場合にも適用する。"
license: "MIT"
---

# Three.js WebGL/3D Skill

## 参照（公式）
- [Three.js公式](https://threejs.org/)
- [Three.js Fundamentals](https://threejsfundamentals.org/)
- [Discover three.js](https://discoverthreejs.com/)
- [React Three Fiber](https://r3f.docs.pmnd.rs/)

## このSkillの基本方針
- 構造: Scene-Camera-Rendererの三位一体がすべての出発点。
- メモリ管理: GPUリソースは自動GCされない。dispose()は義務。
- 最適化: 描画コール削減（バッチング/インスタンシング/LOD）と圧縮テクスチャ（KTX2）が鍵。
- R3F: React環境ではReact Three Fiberを第一候補とする（Three.jsの完全なラッパー、オーバーヘッドなし）。

## 思想（判断ルール）
1. Scene-Camera-Renderer — すべてはこの3要素から始まる。省略しない。
2. GPUメモリは手動管理 — geometry/material/texture/renderTargetは明示的にdispose()する。
3. 描画コールを減らす — 個別メッシュの大量生成はバッチング/インスタンシングで回避する。
4. テクスチャは圧縮する — PNG/JPEGはGPUで完全展開される（200KB PNG → 20MB+ VRAM）。KTX2/Basis Universalで約1/10に。
5. 静的オブジェクトは手動更新 — `matrixAutoUpdate = false` + 変更時に `updateMatrix()` を呼ぶ。
6. R3Fは薄いラッパー — Three.jsで動くものはR3Fでもそのまま動く。新バージョンの機能も即座に利用可能。

## 組む前に構造仕様を起こす
いきなり組まず**先に構造を言語化**してから着手する。シーングラフ構成・オブジェクトの配置とスケール比・カメラ画角と距離を箇条書きにし、**ありがちな破綻を予測**して列挙する（例: スケール基準がばらつく／対象がカメラ視錐台の外／面が重なって z-fighting）。

## 出力フォーマット（必ずこの順）
1. 推奨方針（1〜3行）
2. 理由（パフォーマンス / メモリ / 保守性）
3. 設計案（シーン構造 / メモリ戦略 / レンダリング最適化 / R3F活用）
4. チェックリスト（実装前に確認）
5. 落とし穴（避けるべき）
6. 次アクション（小さく試す順）

## チェックリスト
- [ ] dispose()漏れがないか（geometry/material/texture/renderTarget）
- [ ] `renderer.info.memory` でリソース数を監視しているか（数値が増え続けるならリーク）
- [ ] 静的オブジェクトに `matrixAutoUpdate = false` を設定しているか
- [ ] テクスチャは圧縮フォーマット（KTX2/Basis）を使っているか
- [ ] 大量の同一メッシュはインスタンシングを使っているか
- [ ] アニメーションループの停止処理（cleanup）があるか
- [ ] ウィンドウリサイズ時にカメラのaspect ratioとrenderer.setSizeを更新しているか
- [ ] 組む前に構造仕様（シーン構成/スケール比/カメラ）と破綻リストを書いたか

## よくある落とし穴
- dispose()忘れによるメモリリーク（最大の落とし穴）
- 毎フレームで `new THREE.Vector3()` などのオブジェクト生成（ループ外で再利用する）
- CSS transitionとThree.jsアニメーションの競合
- `requestAnimationFrame` を複数箇所で呼び出す
- PNG/JPEGテクスチャの濫用によるVRAM浪費
- すべてを1ファイルに詰め込む（Scene管理はモジュール分割する）
- イベントリスナー（resize等）のcleanup忘れ
- 構造仕様を起こさず、いきなり細部から組み始める（全体の破綻に気づけない）