zebbern/claude-code-guide / skills/three-best-practices
three-best-practices
VerifiedThree.js performance optimization and best practices guidelines. Use when writing, reviewing, or optimizing Three.js code. Triggers on tasks involving 3D scenes, WebGL/WebGPU rendering, geometries, materials, textures, lighting, shaders, or TSL.
rules/gltf-loading-optimization.md
View on GitHub# 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/three@0.182.0/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/)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |