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/asset-compression.md
View on GitHub# Asset Compression
> Source: [100 Three.js Tips - Utsubo](https://www.utsubo.com/blog/threejs-best-practices-100-tips)
Proper asset compression is critical for web performance. Unoptimized assets are the #1 cause of slow 3D web experiences.
## Geometry Compression
### Draco Compression
Achieves 90-95% size reduction with Web Worker decompression.
```bash
gltf-transform draco model.glb compressed.glb --method edgebreaker
```
### Meshopt (Alternative to Draco)
Similar compression ratios with faster decompression. Consider Meshopt when decompression speed is critical.
### Setup Decoder Paths
```javascript
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('/draco/');
```
## Texture Compression
### Why KTX2?
PNG/JPEG decompress fully in GPU memory:
- 200KB PNG = 20MB+ VRAM
KTX2 stays compressed in GPU memory, dramatically reducing VRAM usage.
### UASTC vs ETC1S
| Format | Quality | Size | Use Case |
|--------|---------|------|----------|
| UASTC | Higher | Larger | Normal maps, hero textures |
| ETC1S | Lower | Smaller | Environment textures, backgrounds |
### KTX2 Setup
```javascript
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath('/basis/');
```
## CLI Optimization
### gltf-transform (Recommended)
```bash
gltf-transform optimize model.glb output.glb \
--texture-compress ktx2 \
--compress draco
```
### Visual Comparison Tool
Use [Shopify's gltf-compressor](https://github.com/Shopify/gltf-compressor) for interactive side-by-side compression preview (keyboard shortcut "C").
## Texture Atlasing
Combine multiple textures into atlases to reduce texture binds:
```javascript
// Update UV coordinates to reference atlas regions
mesh.geometry.attributes.uv.array = atlasUVs;
mesh.geometry.attributes.uv.needsUpdate = true;
```
## Level of Detail (LOD)
Can improve frame rates by 30-40%.
```javascript
const lod = new THREE.LOD();
lod.addLevel(highPolyMesh, 0);
lod.addLevel(mediumPolyMesh, 50);
lod.addLevel(lowPolyMesh, 100);
scene.add(lod);
```
## Summary Checklist
- [ ] Compress geometry with Draco or Meshopt
- [ ] Convert textures to KTX2
- [ ] Use UASTC for quality-critical textures
- [ ] Use ETC1S for secondary textures
- [ ] Atlas textures where possible
- [ ] Implement LOD for complex models
- [ ] Set up decoder paths correctly
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: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |