three.js glTF Loading
Load .gltf/.glb models and play their animations in three.js, including
compressed geometry (DRACO/Meshopt) and textures (KTX2). Patterns target
r186; preserve an existing project's pinned release unless migration is requested.
When to use
- Use to import a 3D model, add it to the scene, inspect its node hierarchy, and
play baked/skinned animation clips with an
AnimationMixer.
- Use when files are
.gltf/.glb, or code imports GLTFLoader /
DRACOLoader / KTX2Loader from three/addons/loaders/....
When not to use: creating the renderer/camera/loop → threejs-scene-setup.
Tuning surface look, lights, or shadows on the loaded model →
threejs-materials-lighting. Authoring/exporting the model itself (Blender) is out
of scope; prefer glTF over OBJ/FBX for runtime.
Core workflow
- Why glTF. It's a transmission format: binary vertex data, PBR materials, and
animations are ready to render with minimal parsing. Prefer it over OBJ (no scene
graph, no animation) and FBX (heavy) for the web.
- Load with
GLTFLoader. loader.load(url, onLoad, onProgress, onError). The
result gltf has gltf.scene (the Object3D root), gltf.animations
(AnimationClip[]), gltf.cameras, and gltf.asset.
- Add
gltf.scene to your scene and frame it. Inspect the hierarchy with
traverse / getObjectByName to find the parts you'll control.
- Play animations with an
AnimationMixer. One mixer per animated root;
mixer.clipAction(clip).play(); advance with mixer.update(delta) every frame.
- Decode compressed assets. Attach a
DRACOLoader, a KTX2Loader, and/or
the Meshopt decoder so DRACO meshes, KTX2 textures, and meshopt-compressed
buffers load. Since r185 the DRACO and KTX2 loaders find their bundled
decoder files on their own.
- Validate changed glTF files when the project already has the tool. Run
gltf-transform validate path/to/model.glb for each changed .gltf or .glb;
fix reported errors before loading.
- Verify what loaded — log the scene graph and
gltf.animations, and confirm
the model is visible (right scale, lit) and the clip actually plays.
Patterns
1. Load a model and frame it
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
const loader = new GLTFLoader();
loader.load(
'assets/robot.glb',
(gltf) => {
const root = gltf.scene;
scene.add(root);
// Inspect: gltf.animations is an array of AnimationClip.
console.log('clips:', gltf.animations.map((c) => c.name));
},
(event) => {
// total is 0 when the server sends no Content-Length (e.g. compressed responses)
if (event.total) console.log(`${(event.loaded / event.total) * 100}% loaded`);
},
(error) => console.error('glTF load failed:', error)
);
2. Play a skinned animation with AnimationMixer
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
let mixer; // declare outside so the loop can see it
const timer = new THREE.Timer(); // THREE.Clock is deprecated since r183
new GLTFLoader().load('assets/character.glb', (gltf) => {
scene.add(gltf.scene);
mixer = new THREE.AnimationMixer(gltf.scene); // one mixer per animated root
const clip = THREE.AnimationClip.findByName(gltf.animations, 'Run')
?? gltf.animations[0];
mixer.clipAction(clip).play();
});
renderer.setAnimationLoop((time) => {
timer.update(time);
const dt = timer.getDelta();
if (mixer) mixer.update(dt); // advance the animation by real seconds
renderer.render(scene, camera);
});
3. Cross-fade between two clips
const actions = {};
mixer = new THREE.AnimationMixer(gltf.scene);
for (const clip of gltf.animations) {
actions[clip.name] = mixer.clipAction(clip);
}
let current = actions['Idle'];
current.play();
function transitionTo(name, duration = 0.3) {
const next = actions[name];
if (!next || next === current) return;
next.reset().play(); // rewind and clear any old fade
current.crossFadeTo(next, duration, false); // fade the old one out, new one in
current = next;
}
4. DRACO-compressed geometry
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader, DRACO_GLTF_CONFIG } from 'three/addons/loaders/DRACOLoader.js';
// r185+: DRACOLoader finds the decoder that ships next to it in
// three/examples/jsm/libs/draco/, so no path is required. DRACO_GLTF_CONFIG
// (also r185+) selects the smaller glTF-only WASM build in libs/draco/gltf/.
const draco = new DRACOLoader().setDecoderPath(DRACO_GLTF_CONFIG);
const loader = new GLTFLoader();
loader.setDRACOLoader(draco); // share one DRACOLoader across loads
loader.load('assets/city-draco.glb', (gltf) => scene.add(gltf.scene));
On releases before r185, or when your host does not serve those files, pass a
folder instead: draco.setDecoderPath('/decoders/draco/') with the files copied
from the same three version.
5. Find and animate a named part
const timer = new THREE.Timer();
new GLTFLoader().load('assets/car.glb', (gltf) => {
scene.add(gltf.scene);
const wheels = [];
gltf.scene.traverse((node) => {
if (node.name.startsWith('Wheel')) wheels.push(node);
});
renderer.setAnimationLoop((time) => {
timer.update(time);
const dt = timer.getDelta();
for (const w of wheels) w.rotation.x += dt * 4;
renderer.render(scene, camera);
});
});
Pitfalls
- Model loads but is invisible → it has lit (PBR) materials and the scene has no
light or environment. Add a light or
scene.environment (see
threejs-materials-lighting), and check scale — glTF is in metres, so a 0.01-scaled
asset is tiny.
load is async → gltf only exists inside the callback; declare mixer/refs
outside and assign them in the callback, or use await loader.loadAsync(url).
- Animation never moves → you didn't call
mixer.update(delta) each frame, or you
passed milliseconds instead of seconds (use timer.getDelta() after
timer.update(time)), or you forgot
action.play().
- DRACO/KTX2 model fails, or the network tab shows a 404 for
draco_*/basis_*
files → the decoder/transcoder files are not being served, or come from a
different three.js version. Since r185 the loaders default to the copies inside
three/examples/jsm/libs/; if your bundler or host doesn't serve those, copy the
folders from the installed three and point setDecoderPath/setTranscoderPath
at them.
setKTX2Loader must be called before loading KTX2 textures or
setMeshoptDecoder must be called before loading compressed files → the
asset uses KHR_texture_basisu or meshopt compression (EXT_/KHR_meshopt_compression);
attach the missing decoder (see the reference).
- Multiple mixers fighting → use one
AnimationMixer per animated root and
create all actions from it; don't make a new mixer per clip.
- Baked-in transforms surprise you → exporters sometimes bake scale/rotation onto
child nodes. Dump the hierarchy (names + position/rotation/scale) before relying on
a node's local transform; re-export from the source if the rig is unusable.
- Origins are off → re-parent a part under a fresh
Object3D to give it a clean
pivot rather than fighting baked offsets.
References
- For the full decode/transcode setup (DRACO + Meshopt + KTX2 together),
loadAsync
- a
LoadingManager progress bar, reusing models with SkeletonUtils.clone, and
exporter guidance (apply transforms, one clean root), read
references/loaders-and-animation.md.
Related skills
threejs-scene-setup — the renderer, camera, and loop this model renders into.
threejs-materials-lighting — lighting/environment so PBR models look right.
fps-shooter — a 3D genre that composes three.js skills.
1---2name: threejs-gltf-loading3description: >4 Load glTF/GLB models in three.js with GLTFLoader and play their skinned5 animations with AnimationMixer, including DRACO/Meshopt-compressed meshes and6 KTX2 textures. Use when importing 3D models into three.js — when the user7 mentions glTF, GLB, GLTFLoader, AnimationMixer, animation clips, DRACOLoader, or8 "load a 3D model". For scene/camera/renderer setup use threejs-scene-setup; for9 materials and lights use threejs-materials-lighting.10metadata:11 source: https://skillmd.com/skills/junmystery/threejs-gltf-loading12---1314# three.js glTF Loading1516Load `.gltf`/`.glb` models and play their animations in three.js, including17compressed geometry (DRACO/Meshopt) and textures (KTX2). Patterns target18**r186**; preserve an existing project's pinned release unless migration is requested.1920## When to use2122- Use to import a 3D model, add it to the scene, inspect its node hierarchy, and23 play baked/skinned animation clips with an `AnimationMixer`.24- Use when files are `.gltf`/`.glb`, or code imports `GLTFLoader` /25 `DRACOLoader` / `KTX2Loader` from `three/addons/loaders/...`.2627**When *not* to use:** creating the renderer/camera/loop → `threejs-scene-setup`.28Tuning surface look, lights, or shadows on the loaded model →29`threejs-materials-lighting`. Authoring/exporting the model itself (Blender) is out30of scope; prefer glTF over OBJ/FBX for runtime.3132## Core workflow33341. **Why glTF.** It's a transmission format: binary vertex data, PBR materials, and35 animations are ready to render with minimal parsing. Prefer it over OBJ (no scene36 graph, no animation) and FBX (heavy) for the web.372. **Load with `GLTFLoader`.** `loader.load(url, onLoad, onProgress, onError)`. The38 result `gltf` has `gltf.scene` (the `Object3D` root), `gltf.animations`39 (`AnimationClip[]`), `gltf.cameras`, and `gltf.asset`.403. **Add `gltf.scene` to your scene** and frame it. Inspect the hierarchy with41 `traverse` / `getObjectByName` to find the parts you'll control.424. **Play animations with an `AnimationMixer`.** One mixer per animated root;43 `mixer.clipAction(clip).play()`; advance with `mixer.update(delta)` every frame.445. **Decode compressed assets.** Attach a `DRACOLoader`, a `KTX2Loader`, and/or45 the Meshopt decoder so DRACO meshes, KTX2 textures, and meshopt-compressed46 buffers load. Since r185 the DRACO and KTX2 loaders find their bundled47 decoder files on their own.486. **Validate changed glTF files when the project already has the tool.** Run49 `gltf-transform validate path/to/model.glb` for each changed `.gltf` or `.glb`;50 fix reported errors before loading.517. **Verify what loaded** — log the scene graph and `gltf.animations`, and confirm52 the model is visible (right scale, lit) and the clip actually plays.5354## Patterns5556### 1. Load a model and frame it5758```js59import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';6061const loader = new GLTFLoader();62loader.load(63 'assets/robot.glb',64 (gltf) => {65 const root = gltf.scene;66 scene.add(root);67 // Inspect: gltf.animations is an array of AnimationClip.68 console.log('clips:', gltf.animations.map((c) => c.name));69 },70 (event) => {71 // total is 0 when the server sends no Content-Length (e.g. compressed responses)72 if (event.total) console.log(`${(event.loaded / event.total) * 100}% loaded`);73 },74 (error) => console.error('glTF load failed:', error)75);76```7778### 2. Play a skinned animation with AnimationMixer7980```js81import * as THREE from 'three';82import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';8384let mixer; // declare outside so the loop can see it85const timer = new THREE.Timer(); // THREE.Clock is deprecated since r1838687new GLTFLoader().load('assets/character.glb', (gltf) => {88 scene.add(gltf.scene);89 mixer = new THREE.AnimationMixer(gltf.scene); // one mixer per animated root90 const clip = THREE.AnimationClip.findByName(gltf.animations, 'Run')91 ?? gltf.animations[0];92 mixer.clipAction(clip).play();93});9495renderer.setAnimationLoop((time) => {96 timer.update(time);97 const dt = timer.getDelta();98 if (mixer) mixer.update(dt); // advance the animation by real seconds99 renderer.render(scene, camera);100});101```102103### 3. Cross-fade between two clips104105```js106const actions = {};107mixer = new THREE.AnimationMixer(gltf.scene);108for (const clip of gltf.animations) {109 actions[clip.name] = mixer.clipAction(clip);110}111let current = actions['Idle'];112current.play();113114function transitionTo(name, duration = 0.3) {115 const next = actions[name];116 if (!next || next === current) return;117 next.reset().play(); // rewind and clear any old fade118 current.crossFadeTo(next, duration, false); // fade the old one out, new one in119 current = next;120}121```122123### 4. DRACO-compressed geometry124125```js126import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';127import { DRACOLoader, DRACO_GLTF_CONFIG } from 'three/addons/loaders/DRACOLoader.js';128129// r185+: DRACOLoader finds the decoder that ships next to it in130// three/examples/jsm/libs/draco/, so no path is required. DRACO_GLTF_CONFIG131// (also r185+) selects the smaller glTF-only WASM build in libs/draco/gltf/.132const draco = new DRACOLoader().setDecoderPath(DRACO_GLTF_CONFIG);133134const loader = new GLTFLoader();135loader.setDRACOLoader(draco); // share one DRACOLoader across loads136loader.load('assets/city-draco.glb', (gltf) => scene.add(gltf.scene));137```138139On releases before r185, or when your host does not serve those files, pass a140folder instead: `draco.setDecoderPath('/decoders/draco/')` with the files copied141from the same `three` version.142143### 5. Find and animate a named part144145```js146const timer = new THREE.Timer();147148new GLTFLoader().load('assets/car.glb', (gltf) => {149 scene.add(gltf.scene);150 const wheels = [];151 gltf.scene.traverse((node) => {152 if (node.name.startsWith('Wheel')) wheels.push(node);153 });154 renderer.setAnimationLoop((time) => {155 timer.update(time);156 const dt = timer.getDelta();157 for (const w of wheels) w.rotation.x += dt * 4;158 renderer.render(scene, camera);159 });160});161```162163## Pitfalls164165- **Model loads but is invisible** → it has lit (PBR) materials and the scene has no166 light or environment. Add a light or `scene.environment` (see167 `threejs-materials-lighting`), and check scale — glTF is in metres, so a 0.01-scaled168 asset is tiny.169- **`load` is async** → `gltf` only exists inside the callback; declare `mixer`/refs170 outside and assign them in the callback, or use `await loader.loadAsync(url)`.171- **Animation never moves** → you didn't call `mixer.update(delta)` each frame, or you172 passed milliseconds instead of seconds (use `timer.getDelta()` after173 `timer.update(time)`), or you forgot174 `action.play()`.175- **DRACO/KTX2 model fails, or the network tab shows a 404 for `draco_*`/`basis_*`176 files** → the decoder/transcoder files are not being served, or come from a177 different three.js version. Since r185 the loaders default to the copies inside178 `three/examples/jsm/libs/`; if your bundler or host doesn't serve those, copy the179 folders from the installed `three` and point `setDecoderPath`/`setTranscoderPath`180 at them.181- **`setKTX2Loader must be called before loading KTX2 textures`** or182 **`setMeshoptDecoder must be called before loading compressed files`** → the183 asset uses `KHR_texture_basisu` or meshopt compression (`EXT_`/`KHR_meshopt_compression`);184 attach the missing decoder (see the reference).185- **Multiple mixers fighting** → use **one** `AnimationMixer` per animated root and186 create all actions from it; don't make a new mixer per clip.187- **Baked-in transforms surprise you** → exporters sometimes bake scale/rotation onto188 child nodes. Dump the hierarchy (names + position/rotation/scale) before relying on189 a node's local transform; re-export from the source if the rig is unusable.190- **Origins are off** → re-parent a part under a fresh `Object3D` to give it a clean191 pivot rather than fighting baked offsets.192193## References194195- For the full decode/transcode setup (DRACO + Meshopt + KTX2 together), `loadAsync`196 + a `LoadingManager` progress bar, reusing models with `SkeletonUtils.clone`, and197 exporter guidance (apply transforms, one clean root), read198 `references/loaders-and-animation.md`.199200## Related skills201202- `threejs-scene-setup` — the renderer, camera, and loop this model renders into.203- `threejs-materials-lighting` — lighting/environment so PBR models look right.204- `fps-shooter` — a 3D genre that composes three.js skills.