● learn-tech

ローダー

外部ファイルからモデル・テクスチャ・HDR を読み込む。Three.js のローダーは three/addons/ に 揃っている。glTF / GLB が事実上の標準なので、まずはそれだけ覚えれば足りる。

ローダーの共通 API

どのローダーも基本的に同じ流れ: 

const loader = new XxxLoader()

// コールバック版
loader.load(
  url,
  (data) => { /* 完了時 */ },
  (xhr)  => { /* 進捗 */ },
  (err)  => { /* エラー */ },
)

// Promise 版（最近の書き方）
const data = await loader.loadAsync(url)

テクスチャ系

TextureLoader

const tex = await new THREE.TextureLoader().loadAsync("/wall.jpg")
tex.colorSpace = THREE.SRGBColorSpace

CubeTextureLoader

const cube = new THREE.CubeTextureLoader()
  .setPath("/cubemap/")
  .load(["px.jpg","nx.jpg","py.jpg","ny.jpg","pz.jpg","nz.jpg"])
scene.background = cube
scene.environment = cube

HDR (RGBE) — RGBELoader

import { RGBELoader } from "three/addons/loaders/RGBELoader.js"

const hdr = await new RGBELoader().loadAsync("/hdr/studio.hdr")
hdr.mapping = THREE.EquirectangularReflectionMapping
scene.environment = hdr

EXR — EXRLoader

import { EXRLoader } from "three/addons/loaders/EXRLoader.js"

const exr = await new EXRLoader().loadAsync("/hdr/scene.exr")
exr.mapping = THREE.EquirectangularReflectionMapping

圧縮テクスチャ — KTX2Loader

Basis Universal で圧縮された .ktx2 形式。ロード時間と GPU メモリを大幅削減。 本番でテクスチャが多い時は積極的に使う。 

import { KTX2Loader } from "three/addons/loaders/KTX2Loader.js"

const ktx2 = new KTX2Loader()
  .setTranscoderPath("https://unpkg.com/three@0.170.0/examples/jsm/libs/basis/")
  .detectSupport(renderer)

const tex = await ktx2.loadAsync("/wall.ktx2")

3Dモデル系

GLTFLoader ★定番

glTF / GLB は3D モデルの標準。アニメーション・PBR マテリアル・スキニング・モーフを まとめて1ファイルに格納できる。 

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

const gltf = await new GLTFLoader().loadAsync("/robot.glb")
scene.add(gltf.scene)

// アニメ
const mixer = new THREE.AnimationMixer(gltf.scene)
mixer.clipAction(gltf.animations[0]).play()

戻り値の構造:

名前で取り出す

gltf.scene.traverse((o) => {
  if (o.isMesh) {
    console.log(o.name, o.material)
  }
})

const head = gltf.scene.getObjectByName("Head")

DRACO 圧縮対応

サイズ削減でDRACO 圧縮された GLB は、専用 decoder が必要。 

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

const draco = new DRACOLoader().setDecoderPath(
  "https://www.gstatic.com/draco/versioned/decoders/1.5.7/",
)

const gltf = new GLTFLoader().setDRACOLoader(draco)
const result = await gltf.loadAsync("/compressed.glb")

Meshopt 圧縮対応

DRACO の代替で人気の Meshopt 圧縮にも対応: 

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

const gltf = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder)

KTX2 マテリアル付き GLB

const gltf = new GLTFLoader()
  .setKTX2Loader(ktx2Loader)
  .setMeshoptDecoder(MeshoptDecoder)
  .setDRACOLoader(dracoLoader)

本番モデルは KTX2 + Meshopt の組み合わせが現代の鉄板。

その他のフォーマット

OBJ — OBJLoader

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

const mtl = await new MTLLoader().loadAsync("/model.mtl")
mtl.preload()
const obj = await new OBJLoader().setMaterials(mtl).loadAsync("/model.obj")
scene.add(obj)

FBX — FBXLoader

import { FBXLoader } from "three/addons/loaders/FBXLoader.js"

const fbx = await new FBXLoader().loadAsync("/model.fbx")
scene.add(fbx)

STL（3Dプリンタ系）

import { STLLoader } from "three/addons/loaders/STLLoader.js"

const geom = await new STLLoader().loadAsync("/part.stl")
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial())

PLY（点群・スキャンデータ）

import { PLYLoader } from "three/addons/loaders/PLYLoader.js"
const geom = await new PLYLoader().loadAsync("/scan.ply")

USDZ（Apple 系）

USDZLoader は addons に居る。AR Quick Look 用ファイルを直接表示できる。

VRM（VRoid キャラ）

VRM は GLTF 拡張の規格。@pixiv/three-vrm パッケージを使う。

LoadingManager — まとめて進捗管理

複数のローダーを1つの LoadingManager に紐づけると、全体の進捗が取れる。 

const manager = new THREE.LoadingManager()

manager.onStart    = (url, loaded, total) => console.log("start")
manager.onProgress = (url, loaded, total) => {
  const pct = (loaded / total * 100).toFixed(1)
  loadingBar.style.width = `${pct}%`
}
manager.onLoad   = () => console.log("all done")
manager.onError  = (url) => console.error("error:", url)

const tex = new THREE.TextureLoader(manager).load("/a.jpg")
const gltf = await new GLTFLoader(manager).loadAsync("/robot.glb")

並列で読み込む

const [tex, gltf, hdr] = await Promise.all([
  new THREE.TextureLoader().loadAsync("/wall.jpg"),
  new GLTFLoader().loadAsync("/robot.glb"),
  new RGBELoader().loadAsync("/hdr/studio.hdr"),
])

クロスオリジン

画像が CORS でブロックされる場合は crossOrigin = "anonymous" をローダーに設定。 

const loader = new THREE.TextureLoader()
loader.setCrossOrigin("anonymous")

キャッシュ

同じ URL を何度も load してもネット経由では再取得されない（THREE.Cache）。 最初に有効化すること: 

THREE.Cache.enabled = true

gltfjsx（R3F 連携）

生 Three.js では関係ないが、GLB → JSX を自動生成する CLI。 R3F を使うなら覚えておくと圧倒的に楽。 

npx gltfjsx model.glb -t       # TS 出力

本番運用のチェックリスト

変換ツール

gltf.report: GLB をブラウザで開いて、Draco / Meshopt / KTX2 圧縮を一括適用できる。本番投入前に必ず通すと良い。
glTF-Transform: CLI / API でビルドパイプラインに組み込める。