threejs-gltf-loading
Load glTF/GLB models in three.js with GLTFLoader and play their skinned animations with AnimationMixer, including DRACO/Meshopt-compressed meshes and KTX2 textures. Use when importing 3D models into three.js — when the user mentions glTF, GLB, GLTFLoader, AnimationMixer, animatio
Install
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills/tree/main/skills/web-engines/threejs-gltf-loading
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gamedev-skills-awesome-gamedev-agent-skills@llmmart
git clone https://github.com/gamedev-skills/awesome-gamedev-agent-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gamedev-skills/awesome-gamedev-agent-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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 importsGLTFLoader/DRACOLoader/KTX2Loaderfromthree/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 resultgltfhasgltf.scene(theObject3Droot),gltf.animations(AnimationClip[]),gltf.cameras, andgltf.asset. - Add
gltf.sceneto your scene and frame it. Inspect the hierarchy withtraverse/getObjectByNameto find the parts you'll control. - Play animations with an
AnimationMixer. One mixer per animated root;mixer.clipAction(clip).play(); advance withmixer.update(delta)every frame. - Decode compressed assets. Attach a
DRACOLoader, aKTX2Loader, 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.glbfor each changed.gltfor.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(seethreejs-materials-lighting), and check scale — glTF is in metres, so a 0.01-scaled asset is tiny. loadis async →gltfonly exists inside the callback; declaremixer/refs outside and assign them in the callback, or useawait loader.loadAsync(url).- Animation never moves → you didn't call
mixer.update(delta)each frame, or you passed milliseconds instead of seconds (usetimer.getDelta()aftertimer.update(time)), or you forgotaction.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 insidethree/examples/jsm/libs/; if your bundler or host doesn't serve those, copy the folders from the installedthreeand pointsetDecoderPath/setTranscoderPathat them. setKTX2Loader must be called before loading KTX2 texturesorsetMeshoptDecoder must be called before loading compressed files→ the asset usesKHR_texture_basisuor meshopt compression (EXT_/KHR_meshopt_compression); attach the missing decoder (see the reference).- Multiple mixers fighting → use one
AnimationMixerper 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
Object3Dto give it a clean pivot rather than fighting baked offsets.
References
- For the full decode/transcode setup (DRACO + Meshopt + KTX2 together),
loadAsync- a
LoadingManagerprogress bar, reusing models withSkeletonUtils.clone, and exporter guidance (apply transforms, one clean root), readreferences/loaders-and-animation.md.
- a
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.
Files (awesome-gamedev-agent-skills)
-
references
-
loaders-and-animation.md 5.3 KB
Loading…
-
-
SKILL.md 8.3 KB
--- name: threejs-gltf-loading description: > Load glTF/GLB models in three.js with GLTFLoader and play their skinned animations with AnimationMixer, including DRACO/Meshopt-compressed meshes and KTX2 textures. Use when importing 3D models into three.js — when the user mentions glTF, GLB, GLTFLoader, AnimationMixer, animation clips, DRACOLoader, or "load a 3D model". For scene/camera/renderer setup use threejs-scene-setup; for materials and lights use threejs-materials-lighting. --- # 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 1. **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. 2. **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`. 3. **Add `gltf.scene` to your scene** and frame it. Inspect the hierarchy with `traverse` / `getObjectByName` to find the parts you'll control. 4. **Play animations with an `AnimationMixer`.** One mixer per animated root; `mixer.clipAction(clip).play()`; advance with `mixer.update(delta)` every frame. 5. **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. 6. **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. 7. **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 ```js 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 ```js 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 ```js 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 ```js 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 ```js 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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.