threejs-loaders

Three.js ローダー

アセットの取得／デコードのライフサイクル、ローダーの設定、キャッシュ、進捗状況、クリーンアップには、このスキルを使用します。モデルの読み込み後の処理は、threejs-animation、threejs-materials、threejs-textures、または threejs-geometry に振り分けます。

このスキルを使う場面

• GLB／GLTF モデル、テクスチャ、キューブマップ、HDR／EXR アセット、その他の Three.js 形式を読み込む
• デプロイ環境と互換性のあるパスで Draco と KTX2 のトランスコードを設定する
• コールバックベースの読み込みを、キャンセル可能で状態を監視できる機能境界に変換する
• アセットの欠落、CORS エラー、デコーダーパスのエラー、フェッチの重複、リークを診断する

手順

Step 1：デプロイ環境とアセットの制約を確認する

1. インストールされている Three.js のリビジョンを確認し、そのプロジェクトでサポートされているパス（通常は three/addons/...）からアドオンをインポートします。
2. バンドラーとベースパスによる変換後のアセット URL を特定します。本番環境で失敗するローカル開発用パスをハードコードしないでください。
3. ローダーやデコーダーを追加する前に、ライセンス、サイズの予算、圧縮、CORS、およびアセットに必要なランタイムサポートを確認します。

Step 2：アセットパイプラインごとに読み込みを一度だけ設定する

import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
import { DRACOLoader } from "three/addons/loaders/DRACOLoader.js";

const manager = new THREE.LoadingManager();
manager.onError = (url) => console.error(`Failed to load ${url}`);

const draco = new DRACOLoader(manager);
draco.setDecoderPath("/draco/");

const loader = new GLTFLoader(manager);
loader.setDRACOLoader(draco);
const gltf = await loader.loadAsync("/models/product.glb");
scene.add(gltf.scene);

設定済みのローダーを管理し、再利用します。最初のリクエストより前に DRACO／KTX2 デコーダーを設定し、ブラウザーのネットワークパネルで、デプロイされたデコーダーファイルと MIME タイプを確認します。

Step 3：転送、準備、所有権を分離する

フェーズ	担当
フェッチ／デコード	ローダーと LoadingManager
正規化	名前の検証、スケール／原点のポリシー、マテリアル／アニメーションの準備
キャッシュ	明示的なアセットキーと共有所有権ポリシー
アタッチ	機能がシーンへのアタッチとインスタンスごとの状態を管理
破棄	稼働中のコンシューマーと共有されていないリソースのみを解放

型付きのアセット結果を返すか、コンテキスト情報を含むエラーをスローします。読み込みエラーを握りつぶして、何も表示されない空のシーンをレンダリングするのは避けてください。コンシューマー間で可変性に関する合意がある場合に限り、デコード済みの共有アセットをキャッシュします。インスタンスごとに変更する前に、シーングラフをクローンします。

Step 4：進捗状況とエラーを正確に扱う

LoadingManager を使って全体の進捗状況を取得します。ただし、サーバーがコンテンツ長を省略する場合があるため、バイト単位の進捗状況は取得できないことがあるものとして扱ってください。ホスト UI に復旧可能な読み込み／エラー状態を表示し、診断情報には失敗した URL とステータスのコンテキストを含めます。

Step 5：本番環境での動作を確認する

• 開発サーバーだけでなく、キャッシュをクリアした本番ビルドでテストします。
• アセットが利用できない場合、デコーダー URL の失敗、応答の遅延、未対応形式をテストします。
• GLTF のアニメーション／モデル名に関する想定を、実際にエクスポートされたアセットで確認します。
• アセットのマウント／アンマウントや差し替えを繰り返し、シーンノードや重複したフェッチが蓄積しないことを確認します。

例

HDR 環境を読み込む

対応する HDR／EXR ローダーを使用し、テクスチャを threejs-textures／threejs-lighting に渡して、レンダラーのバージョンに適した事前フィルタリングと環境の所有権管理を行います。

複数のアセットを読み込む

機能をレンダリングする前にすべてのアセットが必要な場合に限り、Promise.all などで明示的な Promise 境界を作成します。段階的に表示するシーンでは、安全に使用できる個々のアセットが読み込まれ次第アタッチし、それぞれに既知のフォールバック／エラー状態を用意します。

ベストプラクティス

1. レンダリングのたびにローダーやマネージャーを作成せず、設定済みのものを再利用します。
2. デコーダー／トランスコーダーのディレクトリをデプロイ可能なアプリケーションアセットとして扱い、テストします。
3. 主なモデル交換形式には GLB／GLTF を使用し、レガシーローダーは実際に入力がある場合にのみ追加します。
4. 不変の共有アセットをキャッシュし、インスタンスごとのシーン状態を意図的にクローンします。
5. ティアダウン時にデコーダーと機能が所有する Three.js リソースを破棄します。

参考資料

• Three.js ローダーのソースに関する解説
• GLTFLoader のドキュメント
• Three.js マニュアル：3D モデルの読み込み