marselo-4/TotAuto / .claude/skills/threejs-webgl
threejs-webgl
VerifiedComprehensive skill for Three.js 3D web development. Use this skill when building interactive 3D scenes, WebGL/WebGPU applications, product configurators, 3D visualizations, or immersive web experiences. Triggers on tasks involving Three.js, 3D rendering, scenes, cameras, meshes, materials, lights, animations, textures, or WebGL/WebGPU rendering.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.4 KB |
| assets/starter_scene/README.md | markdown | 2.9 KB |
| assets/starter_scene/index.html | other | 1.7 KB |
| assets/starter_scene/main.js | script | 4.4 KB |
| references/api_reference.md | markdown | 10.8 KB |
| references/materials_guide.md | markdown | 11.2 KB |
| references/optimization_checklist.md | markdown | 9.4 KB |
| scripts/setup_scene.pyexecutable | script | 6.7 KB |
references/optimization_checklist.md
View on GitHub# Three.js Performance Optimization Checklist
## Quick Wins (High Impact, Low Effort)
### ✅ Geometry Optimization
- [ ] **Reuse geometries** across multiple meshes
```javascript
const sharedGeometry = new THREE.BoxGeometry(1, 1, 1);
// Use for all boxes instead of creating new geometry each time
```
- [ ] **Use InstancedMesh** for repeated objects (>50 identical objects)
```javascript
const mesh = new THREE.InstancedMesh(geometry, material, 1000);
```
- [ ] **Reduce polygon count** where not visible
- Use simpler geometries for distant objects
- Implement LOD (Level of Detail)
- [ ] **Dispose unused geometries**
```javascript
geometry.dispose();
```
### ✅ Material Optimization
- [ ] **Share materials** across meshes when possible
- [ ] **Use simpler materials**:
- MeshBasicMaterial for unlit objects
- MeshLambertMaterial for mobile
- MeshStandardMaterial only when PBR needed
- [ ] **Dispose unused materials**
```javascript
material.dispose();
```
### ✅ Texture Optimization
- [ ] **Use power-of-two dimensions** (512, 1024, 2048)
- [ ] **Compress textures**:
- JPEG for photos (smaller file size)
- PNG for transparency
- Consider KTX2/Basis Universal for web
- [ ] **Set correct color space**:
```javascript
diffuseTexture.colorSpace = THREE.SRGBColorSpace;
normalMap.colorSpace = THREE.LinearSRGBColorSpace;
```
- [ ] **Limit texture resolution**:
- 2048x2048 max for most cases
- 1024x1024 for mobile
- 512x512 for background/UI elements
- [ ] **Enable mipmaps and anisotropy**:
```javascript
texture.generateMipmaps = true;
texture.anisotropy = renderer.capabilities.getMaxAnisotropy();
```
- [ ] **Dispose unused textures**:
```javascript
texture.dispose();
```
### ✅ Rendering Optimization
- [ ] **Set pixel ratio appropriately**:
```javascript
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
// Don't use full devicePixelRatio on high-DPI displays
```
- [ ] **Disable antialiasing on mobile**
- [ ] **Use render-on-demand** when scene is static:
```javascript
function render() {
renderer.render(scene, camera);
}
// Call only when needed, not in requestAnimationFrame loop
```
### ✅ Shadow Optimization
- [ ] **Limit number of shadow-casting lights** (2-3 max)
- [ ] **Reduce shadow map size**:
```javascript
light.shadow.mapSize.width = 1024; // Lower for mobile
light.shadow.mapSize.height = 1024;
```
- [ ] **Optimize shadow camera frustum**:
```javascript
light.shadow.camera.near = 1;
light.shadow.camera.far = 20; // Only as far as needed
light.shadow.camera.left = -10;
light.shadow.camera.right = 10;
// ... etc - Tight bounds around scene
```
- [ ] **Disable shadow updates** when static:
```javascript
renderer.shadowMap.autoUpdate = false;
renderer.shadowMap.needsUpdate = true; // Only when changed
```
## Medium Effort Optimizations
### 🔧 Culling & Visibility
- [ ] **Enable frustum culling** (enabled by default):
```javascript
mesh.frustumCulled = true;
```
- [ ] **Compute bounding spheres** for custom geometries:
```javascript
geometry.computeBoundingSphere();
```
- [ ] **Hide offscreen objects**:
```javascript
if (distanceToCamera > threshold) {
mesh.visible = false;
}
```
- [ ] **Use layers** for selective rendering:
```javascript
mesh.layers.set(1);
camera.layers.enable(1);
```
### 🔧 Level of Detail (LOD)
- [ ] **Implement LOD** for complex objects:
```javascript
const lod = new THREE.LOD();
lod.addLevel(highDetailMesh, 0);
lod.addLevel(mediumDetailMesh, 50);
lod.addLevel(lowDetailMesh, 100);
scene.add(lod);
```
### 🔧 Draw Call Reduction
- [ ] **Merge static geometries**:
```javascript
import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
const merged = mergeGeometries([geo1, geo2, geo3]);
```
- [ ] **Use texture atlases** to combine multiple textures
- [ ] **Batch similar materials** together
### 🔧 Animation Optimization
- [ ] **Use Clock.getDelta()** for frame-independent animations:
```javascript
const delta = clock.getDelta();
mixer.update(delta);
```
- [ ] **Pause animations** when offscreen:
```javascript
if (!mesh.visible) {
mixer.stop();
}
```
- [ ] **Limit AnimationMixer updates** to visible objects
### 🔧 Post-Processing Optimization
- [ ] **Reduce effect quality** on mobile
- [ ] **Limit bloom/blur passes**
- [ ] **Use lower resolution render targets**:
```javascript
const renderTarget = new THREE.WebGLRenderTarget(
window.innerWidth * 0.5,
window.innerHeight * 0.5
);
```
## Advanced Optimizations
### ⚙️ Memory Management
- [ ] **Dispose all resources** when removing from scene:
```javascript
function disposeObject(obj) {
if (obj.geometry) obj.geometry.dispose();
if (obj.material) {
if (Array.isArray(obj.material)) {
obj.material.forEach(m => m.dispose());
} else {
obj.material.dispose();
}
}
if (obj.dispose) obj.dispose();
}
scene.traverse(disposeObject);
```
- [ ] **Clear render targets** when done:
```javascript
renderTarget.dispose();
```
- [ ] **Monitor memory usage**:
```javascript
console.log(renderer.info.memory);
console.log(renderer.info.render);
```
### ⚙️ Matrix Optimization
- [ ] **Disable auto-update** for static objects:
```javascript
mesh.matrixAutoUpdate = false;
mesh.updateMatrix();
```
- [ ] **Update world matrix** manually when needed:
```javascript
mesh.matrixWorldNeedsUpdate = true;
```
### ⚙️ Custom Shaders
- [ ] **Use low precision** where possible:
```glsl
precision mediump float; // Instead of highp
```
- [ ] **Minimize texture samples** in fragment shader
- [ ] **Move calculations** to vertex shader when possible
- [ ] **Use built-in GLSL functions** (faster than custom)
### ⚙️ Lighting Optimization
- [ ] **Limit number of real-time lights** (3-5 max)
- [ ] **Use baked lighting** for static scenes:
- Lightmaps
- AO maps
- Environment maps
- [ ] **Combine directional lights** where possible
- [ ] **Use AmbientLight + DirectionalLight** as base setup
### ⚙️ Model Optimization
- [ ] **Use glTF with Draco compression**:
```javascript
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('/draco/');
gltfLoader.setDRACOLoader(dracoLoader);
```
- [ ] **Remove unused data** from models:
- Multiple UV sets
- Unused vertex colors
- Unused morph targets
- [ ] **Optimize mesh topology**:
- Remove hidden faces
- Reduce triangle count
- Use instancing for repeated elements
## Mobile-Specific Optimizations
### 📱 Mobile Best Practices
- [ ] **Lower pixel ratio**:
```javascript
renderer.setPixelRatio(1);
```
- [ ] **Disable antialiasing**
- [ ] **Use simpler materials** (MeshLambertMaterial)
- [ ] **Reduce texture resolution** (512-1024px max)
- [ ] **Limit particle count** (<1000)
- [ ] **Disable shadows** or use lower resolution
- [ ] **Reduce geometry complexity** by 50%
- [ ] **Disable post-processing** or use minimal effects
- [ ] **Implement aggressive LOD**
- [ ] **Pause rendering** when tab is hidden:
```javascript
document.addEventListener('visibilitychange', () => {
if (document.hidden) {
// Stop animation loop
} else {
// Resume animation loop
}
});
```
## Profiling & Debugging
### 🔍 Performance Monitoring
- [ ] **Use Stats.js**:
```javascript
import Stats from 'three/examples/jsm/libs/stats.module.js';
const stats = new Stats();
document.body.appendChild(stats.dom);
```
- [ ] **Monitor renderer info**:
```javascript
console.log('Geometries:', renderer.info.memory.geometries);
console.log('Textures:', renderer.info.memory.textures);
console.log('Draw Calls:', renderer.info.render.calls);
console.log('Triangles:', renderer.info.render.triangles);
```
- [ ] **Use browser DevTools**:
- Performance tab (frame rate)
- Memory tab (heap snapshots)
- Rendering tab (FPS meter, paint flashing)
- [ ] **WebGL Performance Tools**:
- Spector.js (WebGL inspector)
- Chrome GPU Profiler
### 🔍 Common Performance Bottlenecks
1. **Too many draw calls** → Merge geometries, use instancing
2. **Too many triangles** → Reduce geometry complexity, use LOD
3. **Large textures** → Compress, reduce resolution
4. **Too many lights** → Limit lights, use baked lighting
5. **Complex shaders** → Simplify materials
6. **Memory leaks** → Dispose resources properly
7. **Expensive post-processing** → Reduce effects, lower resolution
## Performance Targets
### 🎯 Desktop
- **60 FPS** (16.67ms per frame)
- **Draw calls**: <100
- **Triangles**: <1M visible
- **Texture memory**: <500MB
- **Pixel ratio**: 1-2
### 🎯 Mobile
- **30-60 FPS** (16.67-33ms per frame)
- **Draw calls**: <50
- **Triangles**: <100K visible
- **Texture memory**: <200MB
- **Pixel ratio**: 1
## Optimization Workflow
1. **Profile first** - Identify actual bottlenecks
2. **Optimize bottlenecks** - Focus on highest impact
3. **Measure improvement** - Verify gains
4. **Iterate** - Repeat process
**Remember:** Premature optimization is the root of all evil. Profile before optimizing!
## Quick Optimization Checklist Summary
```
✅ Reuse geometries and materials
✅ Use InstancedMesh for repeated objects
✅ Optimize texture size and format
✅ Set pixel ratio to max 2
✅ Limit shadow-casting lights
✅ Dispose unused resources
✅ Implement LOD for complex objects
✅ Reduce draw calls via merging
✅ Profile with Stats.js
✅ Test on target devices (mobile!)
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |