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
.claude/rules/gltf-loading-optimization.mdWhat 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-optimizationrule - Run
model.glbthroughgltf-transform optimizeand report what changed - Add a loading screen driven by
LoadingManagerwith a percentage
How to install gltf-loading-optimization
Manually: put the files in place
.claude/rules/gltf-loading-optimization.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/gltf-loading-optimization.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/gltf-loading-optimization.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/gltf-loading-optimization.mdManually: put the files in place
.clinerules/gltf-loading-optimization.mdStep 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