r3f-loaders

React Three Fiber ローダー

まず、インストールされている Fiber、Drei、Three.js、React のバージョンを確認してください。例では Fiber 9／React 19 を使用しています。実際のアセットパス、ノード名、形式、圧縮方式を確認し、モデルの構造を推測しないでください。

モデルの読み込みと再利用

Canvas の下にマウントしてください。アプリケーション内に /models/robot.glb を用意してください。これらのクローンはオブジェクトのトランスフォームを個別に持ちますが、ジオメトリとマテリアルは意図的に共有しています。

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

function Models() {
  const { scene } = useGLTF('/models/robot.glb')
  return (
    <group dispose={null}>
      <Clone object={scene} position={[-1.2, 0, 0]} />
      <Clone object={scene} position={[1.2, 0, 0]} />
    </group>
  )
}

export default function Example() {
  return (
    <Suspense fallback={null}>
      <Models />
    </Suspense>
  )
}

読み込み方法の選択

• glTF／GLB には useGLTF を優先し、その他の形式には対応する Three.js ローダーと useLoader を使用してください。Fiber 9 では、設定を分離する必要がある場合、外部で所有するローダーインスタンスも使用できます。
• ローダーフックはサスペンドします。一緒に表示するアセットには境界をまとめて設定し、独立して読み込むアセットには個別の境界を設定してください。操作前に必要になりそうなアセットをプリロードし、カタログ全体はプリロードしないでください。
• プリロードはリクエストを開始するもので、即座に表示されることや GPU シェーダーのコンパイルを保証するものではありません。アセットのデコードや初回レンダリングにも、依然として時間がかかる場合があります。
• 条件付きで読み込むには、フックを呼び出す子コンポーネントを条件付きでマウントしてください。偽の URL として null を渡したり、フックを条件付きで呼び出したりしないでください。
• Three.js のアドオンでは、three/addons/loaders/GLTFLoader.js のようなパスを使用します。名前が変更されたローダーについては、インストール済みのエクスポートを確認してください。最新の Three.js では、古い例で RGBELoader が使われていた箇所に HDRLoader が使われます。
• 名前付きノード／マテリアルを公開するのに便利な場合は、型付きの gltfjsx を使い、生成結果を確認してください。ラッパーでは、削除されたグローバル JSX 型名前空間ではなく、ThreeElements['group'] を使用してください。

キャッシュ、クローン、ライフタイム

• キャッシュされたローダーの結果は共有されるものとして扱ってください。1 つの Object3D を 2 つの親の下にマウントすると、親の間で移動します。繰り返し配置する場合は、グラフをクローンしてください。
• Drei Clone は、通常のグラフ複製とスケルトンを考慮したクローン作成に対応しています。アニメーションミキサーを個別に使う場合は、安定した SkeletonUtils.clone のルートを使うと、所有関係が明確になります。
• グラフのクローンでは通常、ジオメトリ、テクスチャ、マテリアルは共有されます。インスタンスごとに編集する前に、対象のマテリアル／テクスチャをクローンしてください。すべてをディープクローンするとメモリを無駄に消費します。
• 個々のコンシューマーが共有キャッシュリソースを破棄しないようにしてください（共有サブツリーに dispose={null} を指定します）。アプリケーションのキャッシュ所有者は、すべてのコンシューマーがなくなった後に限り、リソースを解放できます。
• プリミティブは R3F によって自動的に破棄されません。useGLTF.clear(url) も useLoader.clear(...) も、GPU の完全なクリーンアップ処理ではありません。
• レンダリング中にキャッシュをクリアしないでください。また、ローカルでのセットアップを簡単に済ませるために、キャッシュされたシーンのトランスフォーム／マテリアルを変更しないでください。

デコーダーとエラー処理

• useGLTF は Draco／Meshopt に対応していますが、デコーダーの URL とローダー設定は、アセットとホスティングポリシーに合わせる必要があります。KTX2 テクスチャでは、読み込み前にレンダラーの機能を検出して KTX2Loader を設定してください。
• プリロードと実際の読み込みには、同じローダー／デコーダー設定を使用してください。リクエストを開始する前に設定してください。後から変更しても、すでにキャッシュされた結果が再解析されることはありません。
• レンダリングのたびに、または読み込みコールバックのたびに、新しいデコーダーワーカープールを作成しないでください。カスタムローダー／デコーダーインスタンスには、明確な所有者とクリーンアップ方法を用意してください。
• Suspense が処理するのは処理中の読み込みであり、リクエストの失敗ではありません。明示的な再試行／再マウント戦略を備えたエラーバウンダリーを使用してください。再試行のためのキャッシュ削除は、ユーザー操作または制御された復旧処理で行ってください。
• Canvas 内では Three.js のフォールバックまたは Drei Html を使用してください。Drei Loader は DOM オーバーレイなので、Canvas の外に配置します。
• useProgress が示すのはローディングマネージャーのアクティビティであり、必ずしも単一アセットのバイト単位で正確な完了状況ではありません。利用できない Content-Length を、信頼できる分母として扱わないでください。
• ネットワークエラー、CORS、デコーダー／トランスコーダーのホスティング、実際の圧縮アセットをテストしてください。非圧縮 GLB でのスモークテストでは、すべてのデコーダー経路を検証できません。

Sources

• Fiber useLoader, Drei useGLTF, Clone.
• GLTFLoader, KTX2Loader, SkeletonUtils.