threejs-syntax-loaders

threejs-syntax-loaders

クイックリファレンス

ローダーのアーキテクチャ

すべての Three.js ローダーは Loader 基底クラスを継承し、次の 2 つの読み込みパターンを共有しています。

// Callback style
loader.load(url, onLoad, onProgress, onError);

// Promise style (preferred)
const result = await loader.loadAsync(url, onProgress);

インポートパス

ローダー	インポート
TextureLoader	import { TextureLoader } from 'three';
CubeTextureLoader	import { CubeTextureLoader } from 'three';
GLTFLoader	import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
DRACOLoader	import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
KTX2Loader	import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
FBXLoader	import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
OBJLoader	import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
MTLLoader	import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
RGBELoader	import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
MeshoptDecoder	import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';

フォーマットの推奨事項

他の 3D フォーマットよりも、常に glTF/GLB を優先してください。glTF は Three.js の推奨フォーマットです。PBR マテリアル、アニメーション、カメラ、ライト、シーン階層を 1 つのファイルでサポートします。単一ファイルで配布する場合は .glb（バイナリ glTF）を使用してください。

重大な警告

決して requestAnimationFrame 内やレンダーループ内で loader.load() を呼び出さないでください。アセットは初期化時に一度だけ読み込み、結果をキャッシュしてください。

Draco 圧縮モデルを読み込む前に、DRACOLoader のデコーダーパスを設定し忘れないでください。パスは draco_decoder.wasm を含むディレクトリを必ず指定してください。

loadAsync の呼び出しでエラー処理を省略しないでください。必ず try/catch で囲んでください。エラーハンドラーのない読み込み失敗は、エラーが表示されないままクラッシュします。

読み込んだモデルを削除するときは、必ずリソースを破棄してください。GLTF モデルにはメッシュ、マテリアル、テクスチャが含まれており、これらはすべて破棄する必要があります。

拡散色／カラーのテクスチャ（map、emissiveMap）には、必ず texture.colorSpace = THREE.SRGBColorSpace を設定してください。データテクスチャ（normalMap、roughnessMap、metalnessMap、aoMap）には、決して SRGBColorSpace を設定しないでください。

Draco 圧縮モデルをすべて読み込んだ後は、WASM デコーダーのメモリを解放するため、必ず dracoLoader.dispose() を呼び出してください。

---

Loader 基底クラス

すべてのローダーは Loader から次のメソッドを継承します。

メソッド	シグネチャ	目的
load	(url, onLoad, onProgress, onError)	コールバックベースの読み込み
loadAsync	(url, onProgress) => Promise	Promise ベースの読み込み
setPath	(path: string)	すべての読み込みに使うベース URL のプレフィックスを設定
setResourcePath	(path: string)	リソース解決パスを設定
setCrossOrigin	(value: string)	CORS モードを設定
setWithCredentials	(value: boolean)	クロスオリジンで認証情報を有効化
setRequestHeader	(header: object)	カスタム HTTP ヘッダーを設定

---

LoadingManager

複数のローダーを調整し、全体の進行状況を追跡します。

import * as THREE from 'three';

const manager = new THREE.LoadingManager(
  () => { console.log('All assets loaded'); },
  (url, loaded, total) => { console.log(`Progress: ${loaded}/${total}`); },
  (url) => { console.error(`Failed to load: ${url}`); }
);

// Pass manager to any loader
const textureLoader = new THREE.TextureLoader(manager);
const gltfLoader = new GLTFLoader(manager);

マネージャーのコールバック

コールバック	シグネチャ	実行タイミング
onStart	(url, itemsLoaded, itemsTotal)	最初のアイテムの読み込み開始時
onLoad	()	すべてのアイテムの読み込み完了時
onProgress	(url, itemsLoaded, itemsTotal)	各アイテムの読み込み完了時
onError	(url)	アイテムの読み込み失敗時

マネージャーのメソッド

メソッド	目的
itemStart(url)	読み込みアイテムを手動で登録
itemEnd(url)	アイテムを読み込み済みとして手動でマーク
itemError(url)	アイテムを失敗として手動でマーク
resolveURL(url)	モディファイアを通じて URL を解決
setURLModifier(callback)	カスタム URL 書き換え（blob URL、サービスワーカー）

---

GLTFLoader

3D モデル用の主要なローダーです。glTF 2.0 はメッシュ、PBR マテリアル、アニメーション、カメラ、ライト、シーン階層をサポートします。

Draco 圧縮を使用したセットアップ

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

const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/');

const gltfLoader = new GLTFLoader();
gltfLoader.setDRACOLoader(dracoLoader);

KTX2 テクスチャを使用したセットアップ

import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';

const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath('/basis/');
ktx2Loader.detectSupport(renderer); // MUST pass renderer instance

gltfLoader.setKTX2Loader(ktx2Loader);

Meshopt デコーダーを使用したセットアップ

import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';

await MeshoptDecoder.ready;
gltfLoader.setMeshoptDecoder(MeshoptDecoder);

モデルの読み込み

try {
  const gltf = await gltfLoader.loadAsync('model.glb');
  scene.add(gltf.scene);
} catch (error) {
  console.error('Failed to load model:', error);
}

GLTF 結果オブジェクト

{
  scene: THREE.Group,                    // Root scene node -- add this to your scene
  scenes: THREE.Group[],                 // All scenes in the file
  cameras: THREE.Camera[],              // Embedded cameras
  animations: THREE.AnimationClip[],    // Animation data for AnimationMixer
  asset: { generator: string, version: string },  // File metadata
  parser: GLTFParser,                    // Internal parser (advanced use)
  userData: {}                           // Custom glTF extensions
}

GLTFLoader のメソッド

メソッド	シグネチャ	目的
load	(url, onLoad, onProgress, onError)	コールバックを使用して読み込みます
loadAsync	(url, onProgress) => Promise<GLTF>	Promise を使用して読み込みます
parse	(data, path, onLoad, onError)	ArrayBuffer または JSON を直接解析します
setDRACOLoader	(dracoLoader: DRACOLoader)	Draco の解凍を有効にします
setKTX2Loader	(ktx2Loader: KTX2Loader)	KTX2 テクスチャの解凍を有効にします
setMeshoptDecoder	(decoder)	meshopt の解凍を有効にします
register	(plugin)	glTF 拡張プラグインを登録します
unregister	(plugin)	glTF 拡張プラグインの登録を解除します

---

DRACOLoader

Draco 圧縮されたジオメトリをデコードします。メッシュのファイルサイズを 80～90% 削減します。

メソッド	シグネチャ	目的
setDecoderPath	(path: string)	WASM デコーダーを含むディレクトリのパス
setDecoderConfig	(config: object)	{ type: 'js' | 'wasm' } -- デフォルトは WASM で、より高速です
preload	()	初回使用前にデコーダーの WASM を事前取得します
dispose	()	WASM デコーダーのメモリを解放します

Draco 圧縮モデルをすべて読み込んだ後は、必ず dracoLoader.dispose() を呼び出してください。

---

TextureLoader

2D テクスチャ（PNG、JPG、WebP）を THREE.Texture に読み込みます。

const loader = new THREE.TextureLoader();
const texture = await loader.loadAsync('diffuse.jpg');
texture.colorSpace = THREE.SRGBColorSpace; // ALWAYS for color textures
texture.wrapS = THREE.RepeatWrapping;
texture.wrapT = THREE.RepeatWrapping;
material.map = texture;

---

CubeTextureLoader

スカイボックスや環境の反射に使用するキューブマップとして、6 枚の画像を読み込みます。

const cubeLoader = new THREE.CubeTextureLoader();
cubeLoader.setPath('/textures/cube/');
const cubeTexture = cubeLoader.load([
  'px.jpg', 'nx.jpg',  // positive-x, negative-x
  'py.jpg', 'ny.jpg',  // positive-y, negative-y
  'pz.jpg', 'nz.jpg'   // positive-z, negative-z
]);
scene.background = cubeTexture;
scene.environment = cubeTexture;

---

RGBELoader

Radiance .hdr 形式の HDR 環境マップを読み込みます。

import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';

const rgbeLoader = new RGBELoader();
rgbeLoader.load('environment.hdr', (texture) => {
  texture.mapping = THREE.EquirectangularReflectionMapping;
  scene.environment = texture; // PBR environment lighting
  scene.background = texture;  // Optional: visible HDR background
});

RGBELoader は色空間を自動で設定します。HDR テクスチャの色空間を手動で上書きしないでください。

---

FBXLoader

Autodesk FBX モデルを読み込みます。メッシュ、マテリアル、スケルタルアニメーションに対応しています。

import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';

const fbxLoader = new FBXLoader();
const model = await fbxLoader.loadAsync('character.fbx');
scene.add(model);

---

OBJLoader + MTLLoader

必要に応じて MTL マテリアルファイルとともに、Wavefront OBJ ジオメトリを読み込みます。

import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';

const mtlLoader = new MTLLoader();
const materials = await mtlLoader.loadAsync('model.mtl');
materials.preload();

const objLoader = new OBJLoader();
objLoader.setMaterials(materials);
const model = await objLoader.loadAsync('model.obj');
scene.add(model);

OBJ ファイルを読み込む前に、必ず MTL ファイルを読み込み、マテリアルを OBJLoader に渡してください。

---

読み込み済みモデルの破棄

読み込み済みモデルを削除するときは、必ずすべてを走査し、すべてのリソースを破棄してください。

function disposeModel(model) {
  model.traverse((child) => {
    if (child.isMesh) {
      child.geometry.dispose();
      if (Array.isArray(child.material)) {
        child.material.forEach((mat) => {
          disposeMaterial(mat);
        });
      } else {
        disposeMaterial(child.material);
      }
    }
  });
  model.removeFromParent();
}

function disposeMaterial(material) {
  for (const key of Object.keys(material)) {
    const value = material[key];
    if (value && typeof value === 'object' && 'dispose' in value) {
      value.dispose(); // Disposes textures
    }
  }
  material.dispose();
}

---

参考リンク

• references/methods.md -- すべてのローダーの完全な API シグネチャ
• references/examples.md -- 一般的な読み込みシナリオの動作するコード例
• references/anti-patterns.md -- アセット読み込み時に避けるべきこと

公式ソース

• https://threejs.org/docs/#api/en/loaders/Loader
• https://threejs.org/docs/#api/en/loaders/LoadingManager
• https://threejs.org/docs/#api/en/loaders/TextureLoader
• https://threejs.org/docs/#examples/en/loaders/GLTFLoader
• https://threejs.org/docs/#examples/en/loaders/DRACOLoader
• https://threejs.org/docs/#examples/en/loaders/KTX2Loader
• https://threejs.org/docs/#examples/en/loaders/FBXLoader
• https://threejs.org/docs/#examples/en/loaders/OBJLoader
• https://threejs.org/docs/#examples/en/loaders/RGBELoader