gamedev-skills/awesome-gamedev-agent-skills

threejs-gltf-loading

Loads glTF/GLB models into three.js r187 and plays their animations: GLTFLoader, DRACO, Meshopt and KTX2 decoders, AnimationMixer cross-fades and SkeletonUtils clones.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill threejs-gltf-loading

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

three.js glTF loading

Loads .gltf / .glb models, including compressed geometry (DRACO, Meshopt) and textures (KTX2), and plays their animation clips. Patterns target r187; an existing project keeps its pinned release unless the user asks to upgrade. glTF is the runtime format to default to: OBJ has no scene graph or animation, and FBX is heavy to parse in a browser.

When to use

  • Importing a model or character, inspecting its node hierarchy, playing or blending clips,

spawning many copies of an animated enemy, or fixing a model that does not appear.

  • Files are .gltf / .glb, or code imports GLTFLoader, DRACOLoader or KTX2Loader

from three/addons/loaders/....

  • Not for the renderer, camera and loop (threejs-scene-setup), the model's lighting and

materials (threejs-materials-lighting), or modelling and export settings in a DCC tool.

Workflow

  1. Inspect the file before writing loader code when gltf-transform is available:

npx @gltf-transform/cli inspect model.glb lists meshes, extensions (for example KHR_draco_mesh_compression, EXT_meshopt_compression, KHR_texture_basisu), clips and texture sizes. Each listed compression extension needs its decoder attached.

  1. Load with `GLTFLoader` (loadAsync in async code). The result has gltf.scene, the

root Object3D, and gltf.animations, an AnimationClip[].

  1. Add `gltf.scene` and frame it. glTF units are metres; log names and bounds to find

the parts code will control.

  1. One `AnimationMixer` per animated root, actions from mixer.clipAction(clip), and

mixer.update(seconds) every frame.

  1. Attach decoders for the extensions found in step 1. Since r185 DRACOLoader and

KTX2Loader find their bundled decoder files without a path.

  1. Verify with Verify.

Patterns

1. Load and frame a model

js
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

const gltf = await new GLTFLoader().loadAsync('assets/robot.glb');
const root = gltf.scene;
scene.add(root);

const box = new THREE.Box3().setFromObject(root);
console.log('size (m):', box.getSize(new THREE.Vector3()).toArray());
console.log('clips:', gltf.animations.map((c) => c.name));

2. Play a clip

js
const timer = new THREE.Timer();            // THREE.Clock is deprecated since r183
const mixer = new THREE.AnimationMixer(gltf.scene);
const run = THREE.AnimationClip.findByName(gltf.animations, 'Run') ?? gltf.animations[0];
mixer.clipAction(run).play();

renderer.setAnimationLoop(() => {
  timer.update();
  mixer.update(timer.getDelta());           // seconds, not milliseconds
  renderer.render(scene, camera);
});

3. Cross-fade between clips

js
const actions = Object.fromEntries(gltf.animations.map((c) => [c.name, mixer.clipAction(c)]));
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 an old fade
  current.crossFadeTo(next, duration, false);
  current = next;
}

4. Compressed geometry and textures

js
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader, DRACO_GLTF_CONFIG } from 'three/addons/loaders/DRACOLoader.js';
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';

const loader = new GLTFLoader()
  .setDRACOLoader(new DRACOLoader().setDecoderPath(DRACO_GLTF_CONFIG)) // glTF-only WASM build (r185+)
  .setKTX2Loader(new KTX2Loader().detectSupport(renderer))             // needs the renderer
  .setMeshoptDecoder(MeshoptDecoder);
// Share this one loader for every model so decoders and workers are created once.

On releases before r185, or when the host does not serve the bundled files, copy examples/jsm/libs/draco/ and libs/basis/ from the installed three and pass those folders to setDecoderPath / setTranscoderPath.

5. Find a named part

js
const wheels = [];
gltf.scene.traverse((node) => {
  if (node.name.startsWith('Wheel')) wheels.push(node);
});
// In the loop: for (const w of wheels) w.rotation.x += dt * 4;

6. Shrink a model without losing the parts code needs

bash
# Meshopt compression, WebP textures at most 1024 px, keep named nodes and the hierarchy.
npx @gltf-transform/cli optimize in.glb out.glb \
  --compress meshopt --texture-compress webp --texture-size 1024 \
  --flatten false --join-named false
npx @gltf-transform/cli validate out.glb

optimize flattens the hierarchy and joins meshes, named ones included, by default. That cuts draw calls, but code that looks up Wheel_FL or animates a door node then finds nothing. Keep the two flags above for any model that code reaches into. The output needs setMeshoptDecoder (Pattern 4).

Verify

  1. File check: npx @gltf-transform/cli validate model.glb for each new or changed

file; fix reported errors before debugging loader code.

  1. Build: npm run build (or npx tsc --noEmit) passes.
  2. Runtime probe: expose scene and the mixer on window

(Object.assign(window, { scene, mixer })). Pass this expression to Playwright's page.evaluate as a string, so it runs in the page and not in Node (the smoke script in threejs-scene-setup works), or ask the user to paste it into the browser console with await in front and report the output:

js
(async () => {
  const before = window.mixer?.time ?? null;
  await new Promise((r) => setTimeout(r, 500));
  const meshes = [];
  window.scene.traverse((o) => { if (o.isMesh) meshes.push(o.name || o.type); });
  return { meshes: meshes.length, mixerAdvanced: before !== null && window.mixer.time > before };
})();

Expect a non-zero mesh count and mixerAdvanced: true, then check a screenshot for scale and orientation.

Gotchas

  • Model loads but nothing shows → PBR materials with no light or environment (see

threejs-materials-lighting), or the scale is off by 100 (a centimetre export). Log the bounding box from Pattern 1.

  • `gltf` is undefined outside the callback → load is asynchronous. Use loadAsync,

or assign shared references inside the callback.

  • Animation never moves → mixer.update is not called each frame, it is given

milliseconds, or play() was never called.

  • 404 for `draco_ or basis_` files, or a decode error* → the decoder files are not

served, or come from another three.js release. Serve the copies from the installed three and point the loader at them.

  • `setKTX2Loader must be called before loading KTX2 textures` or **`setMeshoptDecoder

must be called before loading compressed files** → the file uses KHRtexturebasisu` or meshopt compression; attach the decoder (Pattern 4).

  • `.hasFeature() called before the backend is initialized` → KTX2Loader.detectSupport

ran on a WebGPURenderer before await renderer.init() finished.

  • Adding the same model twice moves it → an Object3D has one parent. Clone it, and use

SkeletonUtils.clone for skinned meshes (see the reference).

  • Clones animate together, or only one moves → a plain .clone() shares the skeleton;

use SkeletonUtils.clone and a separate mixer per clone.

  • Named parts vanish after `gltf-transform optimize` → the default flatten and join

merged them. Re-run with --flatten false --join-named false.

  • Baked offsets fight runtime control → exporters can bake scale or rotation into child

nodes. Dump names and local transforms first; re-parent a part under a fresh Object3D for a clean pivot, or ask for a re-export with applied transforms.

References

LoadingManager progress bar across many loaders, spawning many animated enemies with SkeletonUtils.clone, AnimationAction looping and blending detail, decoder hosting notes, and exporter checklists to hand to an artist.

Related skills

  • threejs-scene-setup: renderer, camera and loop.
  • threejs-materials-lighting: lighting and environment so PBR models look right.
  • create-game-assets: briefing, sourcing and checking the 3D assets themselves.
  • fps-shooter: a 3D genre that builds on these skills.

Version notes

Last verified: 2026-11-11 against three r187 (npm three@0.187.0, published 2026-10-30) and @gltf-transform/cli 4.5.1.

  • r185: DRACOLoader and KTX2Loader default to their bundled decoder folders;

DRACO_GLTF_CONFIG added; DRACOLoader.setDecoderConfig() deprecated (removal planned for r194). r183: KHR_meshopt_compression supported next to EXT_meshopt_compression. r181: KTX2Loader.detectSupportAsync() deprecated.

  • gltf-transform 4.5.1 optimize defaults: --compress meshopt, --flatten true,

--join true, --join-named true, --simplify true, --texture-compress auto. --texture-compress ktx2 needs the ktx command from KTX-Software 4.4.0 or newer on PATH.

r187 DRACOLoader.js, r187 GLTFLoader.js, glTF Transform CLI, npx @gltf-transform/cli optimize --help.

同じリポジトリから

関連する Skills

すべての Skills
gamedev-skills
コミュニティ

game-ui-ux

Engine-neutral design rules for game HUDs and menus: anchors and containers, scaling, safe areas, gamepad focus, HUDs driven by events instead of polling, and accessibility minimums. Use for menus, health bars or inventory screens that break on ultrawide or phones. Pair with godot-ui-control or roblox-ui. Not for button juice (game-feel) or rebinding (input-systems).

24時間の導入数
433
GitHub Stars
1万
更新日
11月12日
gamedev-skills
コミュニティ

game-feel

Adds engine-neutral juice to a working mechanic: trauma-based screen shake, hit-stop, eased tweens, squash and stretch, and knockback. Use when the game feels flat, weightless or not punchy, or hits and jumps should feel satisfying. Not for coyote time (platformer), input buffering (input-systems), camera follow (camera-systems) or HUD layout (game-ui-ux).

24時間の導入数
431
GitHub Stars
1万
更新日
11月12日
gamedev-skills
コミュニティ

create-game-assets

Plans, generates or sources, and validates consistent game art: style guides, sprites, pixel art, tilesets, icons and textures, with QA and licence records. Use when making or AI-generating game art, fixing fake transparency, or checking Steam AI disclosure. Not for engine import (godot-tilemap, godot-animation, unity-tilemap-2d), UI layout (game-ui-ux) or sound (audio-design).

24時間の導入数
365
GitHub Stars
1万
更新日
11月12日
gamedev-skills
コミュニティ

performance-optimization

Finds and fixes game frame-rate problems by measurement in Godot, Unity, Unreal or Roblox: CPU- vs GPU-bound, then the biggest fix (draw calls, pooling, GC spikes). Use for low FPS, stutter, a first-use hitch, or requests to optimize or profile. Not for build size (unity-build-size), physics jitter (physics-tuning) or network lag (roblox-networking, godot-multiplayer).

24時間の導入数
360
GitHub Stars
1万
更新日
11月12日