threejs-r3f

Three.js / React Three Fiber

R3F v9（React 19）と pmndrs エコシステムを使用した、3D ウェブ体験の構築ガイドです。

バージョンの制約

パッケージ	バージョン	React
@react-three/fiber	v9.x	19.x
@react-three/drei	v9.x+	19.x
@react-three/rapier	v2.x	19.x
three	r171+	—

React 18 のプロジェクトでは、fiber v8 と rapier v1 を使用してください。異なるバージョン系列を混在させないでください。

---

インストール

スタンドアロンの Vite + R3F アプリ

bun create vite my-scene -- --template react-ts
cd my-scene
bun add three @react-three/fiber @react-three/drei
bun add -d @types/three
bun dev

既存の React 19 プロジェクトへの導入

bun add three @react-three/fiber @react-three/drei
bun add -d @types/three

任意のパッケージ：bun add @react-three/rapier（物理演算）、bun add zustand（状態管理）、bun add leva（デバッグ GUI）。

---

シーンのセットアップ

最小限のシーンテンプレート、Canvas のプロパティ表、frameloop の値、レスポンシブ Canvas、WebGPU レンダラーのブートストラップについては、references/scene-setup.md を参照してください。

リファレンスを読まなくても把握しておくべき要点：

• Canvas のデフォルト：antialias: true、outputColorSpace = SRGBColorSpace、toneMapping = ACESFilmicToneMapping、ColorManagement.enabled = true
• デバイスのピクセル比を制限するため、常に dpr={[1, 2]} を設定してください
• シャドウマップには shadows="soft" を使用し、メッシュに castShadow／receiveShadow を追加してください
• インタラクション時のみ再レンダリングが必要な静的シーンには、frameloop="demand" を使用してください

---

Drei ヘルパー — トップ 15

すべて @react-three/drei からインポートします。全項目、プロパティ、使用例については references/drei-helpers.md を参照してください。

コントロール

• OrbitControls — 回転／ズーム／パン。makeDefault を追加すると useThree から利用できます
• ScrollControls — スクロール連動シーン。useFrame 内で useScroll と組み合わせます
• PresentationControls — スプリングアニメーション付きドラッグ。OrbitControls は不要です
• KeyboardControls — 型付きキー状態のコンテキスト。useFrame 内で get() を使って命令的に読み取ります

ステージング

• Environment — プリセット（'sunset' | 'warehouse' | 'city' | ...）またはカスタム HDR による IBL
• Stage — ライティング、カメラのフィッティング、シャドウを設定する、単一コンポーネントでのシーンステージング
• ContactShadows — 平面上にソフトシャドウを擬似的に表現します。シャドウマップより低コストです
• Float — ヒーローオブジェクト用の浮遊／上下動するアイドルアニメーション

形状／コンテンツ

• Text — フォント読み込み、行折り返し、アウトラインに対応した SDF 3D テキスト
• Html — DOM コンテンツを 3D 内に埋め込みます。occlude と transform に対応します

ローダー

• useGLTF — GLTF／GLB を読み込んでキャッシュします。Draco CDN デコーダーを自動設定します
• useTexture — テクスチャを読み込んでキャッシュします。オブジェクト形式で PBR マップを指定できます

パフォーマンス

• Instances / Instance — シンプルなコンポーネント API でインスタンス化メッシュを使用します
• Detailed — LOD：カメラからの距離に応じて異なるメッシュを表示します
• PerformanceMonitor — FPS コールバック。AdaptiveDpr と組み合わせます

マテリアル

• MeshTransmissionMaterial — 屈折と色収差を備えた、物理ベースのガラス

---

アセットのパイプライン

GLTF の読み込み

import { useGLTF } from '@react-three/drei'
import { Suspense } from 'react'

function Model(props) {
  const { nodes, materials } = useGLTF('/model.glb')
  return (
    <group {...props} dispose={null}>
      <mesh geometry={nodes.Body.geometry} material={materials.Metal} castShadow />
    </group>
  )
}

useGLTF.preload('/model.glb')

// Wrap in Suspense
<Canvas>
  <Suspense fallback={null}>
    <Model />
  </Suspense>
</Canvas>

gltfjsx CLI

# Generate TypeScript component + Draco-compress the GLB
npx gltfjsx model.glb --transform --types --shadows
# Outputs: model-transformed.glb (move to /public) + Model.tsx (move to /src/components)

--transform は、Draco ジオメトリ圧縮、1024px へのテクスチャリサイズ、WebP 変換により、ほとんどのモデルのサイズを 70～90% 削減します。

クローンパターン、KTX2 テクスチャ、遅延読み込み、並列プリロードについては、references/r3f-patterns.md を参照してください。

---

パフォーマンスルール

描画コールの予算：

• モバイル：< 100 描画コール
• デスクトップ：< 300 描画コール

7 つのアンチパターン — 以下は絶対に行わないでください：

1. useFrame 内で setState を呼び出さないでください — ref を直接変更します
2. アニメーションには必ず delta を使用してください — 固定値を加算しないでください
3. onPointerMove 内で setState を呼び出さないでください — ref を直接変更します
4. useFrame 内でリアクティブなストアの状態を読み取らないでください — store.getState() の命令型形式を使用します
5. レンダーループ内で条件付きのマウント／アンマウントを行わないでください — 代わりに visible プロパティを使用します
6. useFrame 内で new THREE.Vector3() を作成しないでください — 外部で確保し、.set() を使って再利用します
7. 同一のメッシュに対してジオメトリ／マテリアルを重複して作成しないでください — useMemo または Instances を使って共有します

破棄： 動的に作成した Three.js オブジェクトについては、useEffect のクリーンアップ内で必ず geometry.dispose() と material.dispose() を呼び出してください。

誤ったコードと正しいコードのペア、テクスチャの最適化、フラスタムカリング、統計情報ツール、モバイル向けのルールを含む、7 つすべてのアンチパターンについては references/performance.md をお読みください。

---

状態、物理演算、デバッグ GUI、WebGPU

以下のトピックについては、references/extras.md をお読みください：

• Zustand の命令型パターン（useFrame の正確な動作に必須）
• Leva デバッグ GUI のセットアップ
• Rapier 物理演算のクイックスタート
• WebGPU レンダラーのブートストラップ

Rapier v2 API の全容（すべてのコライダータイプ、衝突イベント、センサー、ジョイント、力、InstancedRigidBodies）については、references/physics.md をお読みください。

---

リファレンスファイル

• references/scene-setup.md — 最小限のシーンテンプレート、Canvas のデフォルト設定、frameloop、レスポンシブ Canvas、WebGPU レンダラー
• references/r3f-patterns.md — Canvas のプロパティ、useFrame、useThree、イベントシステム、スクロール駆動シーン、GLTF クローンパターン、KTX2、遅延読み込み
• references/drei-helpers.md — カテゴリ別の Drei ヘルパー一覧：各ヘルパーのインポート、主要なプロパティ、例
• references/performance.md — 誤ったコードと正しいコードを含む 7 つすべてのアンチパターン、インスタンシング、LOD、テクスチャ圧縮、破棄チェックリスト、モバイル向けのルール
• references/physics.md — Rapier v2 の全容：コライダー、衝突イベント、センサー、6 種類のジョイント、力／インパルス、InstancedRigidBodies
• references/extras.md — Zustand の命令型パターン、Leva デバッグ GUI、Rapier クイックスタート、WebGPU ブートストラップ