Skip to main content
rule CX Codex

gltf-loading-optimization — Claude Code rule: what it does

gltf-loading-optimization is a Claude Code rule with Three.js snippets and commands for glTF loading, decoder setup, progress reporting, lazy loading and model compression.

MIT ★ 4,719 updated 2026-10-24

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/gltf-loading-optimization.md
Open on GitHub

What gltf-loading-optimization does

The rule hands the agent ready-made Three.js snippets for glTF: a GLTFLoader wired to DRACOLoader, KTX2Loader and MeshoptDecoder, callbacks for progress and errors, a LoadingManager shared across assets, and a lazy-loading pattern that pulls the hero model first and decorations afterwards.

Compression lives in gltf-transform commands: draco or meshopt for geometry, webp and ktx for textures, and one combined pass with gltf-transform optimize input.glb output.glb --compress draco --texture-compress webp --texture-size 1024. The CLI is a separate install: npm install -g @gltf-transform/cli.

Decoder files have to live somewhere. The rule sets setDecoderPath('/draco/') and setTranscoderPath('/basis/'), with Google CDN and jsDelivr paths as a fallback. Point those paths at nothing and the model will not load. Pick Meshopt when the model carries animation or morph targets, since Draco handles neither.

What it helps with

  • Wire Draco, KTX2 and Meshopt decoders into a GLTFLoader
  • Shrink a model's geometry before shipping it
  • Convert textures to KTX2 or WebP
  • Show a loading progress indicator
  • Split critical assets from background ones

Example prompts for the agent

  • Set up a glTF loader with Draco and KTX2, following the gltf-loading-optimization rule
  • Run model.glb through gltf-transform optimize and report what changed
  • Add a loading screen driven by LoadingManager with a percentage

How to install gltf-loading-optimization

Manually: put the files in place

.claude/rules/gltf-loading-optimization.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about gltf-loading-optimization

How to install gltf-loading-optimization in Claude Code?

Copy the rule file into your project at .claude/rules/gltf-loading-optimization.md. That is the whole step.

What does gltf-loading-optimization do?

It describes glTF loading in Three.js: hooking up Draco, KTX2 and Meshopt decoders, progress handling, lazy loading, and model compression through gltf-transform.

Draco or Meshopt for an animated model?

Meshopt. Draco compresses geometry harder, yet it supports neither animation nor morph targets and decodes slower.

Source text

gltf-loading-optimization.md · MIT
# GLTF Loading & Optimization

Complete setup for loading and optimizing 3D models.

## Full Loader Setup

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

// DRACO decoder
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('/draco/');

// KTX2 transcoder
const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath('/basis/');
ktx2Loader.detectSupport(renderer);

// GLTF loader with all decoders
const gltfLoader = new GLTFLoader();
gltfLoader.setDRACOLoader(dracoLoader);
gltfLoader.setMeshoptDecoder(MeshoptDecoder);
gltfLoader.setKTX2Loader(ktx2Loader);

// Load model
gltfLoader.load('model.glb', (gltf) => {
  scene.add(gltf.scene);

  // Setup animations
  const mixer = new THREE.AnimationMixer(gltf.scene);
  gltf.animations.forEach((clip) => {
    mixer.clipAction(clip).play();
  });
}, onProgress, onError);
```

## Progress Tracking

```javascript
function onProgress(xhr) {
  if (xhr.lengthComputable) {
    const percent = (xhr.loaded / xhr.total) * 100;
    console.log(`Loading: ${percent.toFixed(0)}%`);
  }
}

function onError(error) {
  console.error('Error loading model:', error);
}
```

## glTF-Transform CLI

### Installation

```bash
npm install -g @gltf-transform/cli
```

### Draco Compression

```bash
gltf-transform draco input.glb output.glb --method edgebreaker
```

### Meshopt Compression

```bash
gltf-transform meshopt input.glb output.glb --level medium
```

### Texture Compression

```bash
# WebP (25-35% reduction)
gltf-transform webp input.glb output.glb --quality 75

# KTX2/Basis (75-85% reduction)
gltf-transform ktx input.glb output.glb --slots baseColor
```

### Full Optimization Pipeline

```bash
gltf-transform optimize input.glb output.glb \
  --compress draco \
  --texture-compress webp \
  --texture-size 1024
```

## Compression Results

| Method | Typical Reduction |
|--------|-------------------|
| Draco | 70-90% geometry |
| Meshopt | 60-80% geometry + morph + animation |
| KTX2/Basis | 75-85% textures |
| WebP | 25-35% textures |

## Draco vs Meshopt

| Feature | Draco | Meshopt |
|---------|-------|---------|
| Compression | Higher | Lower |
| Decode Speed | Slower | Faster |
| Animation | No | Yes |
| Morph Targets | No | Yes |
| Recommendation | Static models | Animated models |

## Best Practices

1. **Format**: Prefer GLB over GLTF (binary, single file)

2. **Textures**: Keep 512x512 or 1024x1024 for mobile

3. **Power of Two**: Always use power-of-2 dimensions

4. **Compression**: DRACO for geometry, KTX2 for textures

5. **Host Decoders**: Host decoders locally or use reliable CDN

6. **Progress**: Always show loading progress

## CDN Decoder Paths

```javascript
// Google CDN
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/v1/decoders/');

// jsDelivr
dracoLoader.setDecoderPath('https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/libs/draco/');
```

## Post-Load Processing

```javascript
gltfLoader.load('model.glb', (gltf) => {
  const model = gltf.scene;

  // Enable shadows
  model.traverse((child) => {
    if (child.isMesh) {
      child.castShadow = true;
      child.receiveShadow = true;
    }
  });

  // Fix materials (if needed)
  model.traverse((child) => {
    if (child.material) {
      child.material.envMapIntensity = 1;
    }
  });

  // Center model
  const box = new THREE.Box3().setFromObject(model);
  const center = box.getCenter(new THREE.Vector3());
  model.position.sub(center);

  scene.add(model);
});
```

## Loading Manager

```javascript
const manager = new THREE.LoadingManager();

manager.onStart = (url, loaded, total) => {
  console.log(`Loading: ${url}`);
};

manager.onProgress = (url, loaded, total) => {
  console.log(`Progress: ${loaded}/${total}`);
};

manager.onLoad = () => {
  console.log('All assets loaded');
  hideLoadingScreen();
};

manager.onError = (url) => {
  console.error(`Error loading: ${url}`);
};

const gltfLoader = new GLTFLoader(manager);
const textureLoader = new THREE.TextureLoader(manager);
```

## Lazy Loading

```javascript
// Load critical assets first
await loadCriticalAssets();
showScene();

// Load non-critical in background
loadBackgroundAssets();

async function loadCriticalAssets() {
  const hero = await gltfLoader.loadAsync('hero.glb');
  scene.add(hero.scene);
}

function loadBackgroundAssets() {
  gltfLoader.load('decorations.glb', (gltf) => {
    scene.add(gltf.scene);
  });
}
```

## References

- [glTF-Transform](https://gltf-transform.dev/)
- [Three.js GLTFLoader](https://threejs.org/docs/#examples/en/loaders/GLTFLoader)
- [Draco Compression](https://google.github.io/draco/)

© zebbern · MIT · zebbern/claude-code-guide

Similar IDE rules

All IDE rules for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set86

The whole set →
debug-devtools The debug-devtools rule guides an agent through adding diagnostics for Three.js performance, scene parameters, and WebGL context loss. Use it when tracking down a rendering bottleneck or inspecting a scene. CX Codex +1 ★ 4,719repo stars tsl-post-processing A reference rule for TSL post-processing in Three.js: chain effects onto postProcessing.outputNode instead of stacking EffectComposer passes. CX Codex +1 ★ 4,719repo stars tsl-compute-shaders tsl-compute-shaders guides the agent in writing WebGPU compute shaders with Three.js TSL for GPGPU tasks like particle systems and physics. CX Codex +1 ★ 4,719repo stars animation-system animation-system — a practical guide to Three.js animation, from playing and blending clips to morph targets and bones. Useful when building scenes with animated models. CX Codex +1 ★ 4,719repo stars physics-integration physics-integration guides Three.js integration with Rapier and Cannon-es: Vite setup, collider primitives, and mesh synchronization patterns. CX Codex +1 ★ 4,719repo stars raycasting-optimization The raycasting-optimization rule covers ways to reduce Three.js raycasting work, from filtering objects by layer to using BVH or GPU picking. Useful when a scene has complex meshes or frequent pointer checks. CX Codex +1 ★ 4,719repo stars mobile-optimization mobile-optimization is a rule for accelerating Three.js scenes on smartphones and tablets. It reduces GPU load and memory use, helping maintain a stable frame rate. CX Codex +1 ★ 4,719repo stars webxr-setup The webxr-setup rule for Claude Code guides building VR and AR scenes in Three.js WebXR. It helps coding agents set up render loops, controllers, and hit-testing. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open