threejs

What this skill does

# Three.js

## Overview

Guides building high-performance 3D web experiences with Three.js, WebGPU-first rendering, TSL (Three Shader Language), and React Three Fiber. Covers scene architecture, asset compression, draw call budgets, and React 19 / Next.js integration patterns.

**When to use:** Creating 3D scenes, WebGPU rendering setup, TSL shader authoring, asset optimization (Draco/KTX2), React Three Fiber composition, Next.js streaming for 3D content, loading GLTF models, setting up lighting and shadows, animation playback and blending.

**When NOT to use:** 2D canvas animations (use Canvas API), simple SVG graphics, server-side rendering without client hydration, projects targeting pre-2022 hardware exclusively.

## Quick Reference

| Pattern           | API / Approach                                     | Key Points                                             |
| ----------------- | -------------------------------------------------- | ------------------------------------------------------ |
| WebGPU renderer   | `import * as THREE from 'three/webgpu'`            | Must `await renderer.init()` before first render       |
| R3F canvas        | `<Canvas gl={...}>` with Suspense                  | Wrap in `<Suspense>` for streaming support             |
| Frame updates     | `useFrame((state, delta) => ...)`                  | Mutate refs directly; never use `setState`             |
| TSL shaders       | `import { ... } from 'three/tsl'`                  | Node-based; compiles to WGSL or GLSL                   |
| Instancing        | `<instancedMesh>` with matrix updates              | Single draw call for repeated geometry                 |
| Batched mesh      | `BatchedMesh` (r156+)                              | Different geometries sharing one material              |
| Draco compression | `gltf-pipeline -i in.gltf -o out.glb -d`           | Up to 90% geometry size reduction                      |
| KTX2 textures     | Basis Universal via `toktx`                        | Stays compressed in VRAM                               |
| LOD               | `THREE.LOD` with distance thresholds               | Swap detail levels by camera distance                  |
| On-demand render  | `<Canvas frameloop="demand">`                      | Only render when scene state changes                   |
| Cleanup           | `.dispose()` on unmount                            | Geometries, materials, and textures                    |
| Compute shaders   | `Fn(() => {...})().compute(count)`                 | GPU-side physics, particles, flocking                  |
| Lighting          | `DirectionalLight`, `SpotLight`, `HemisphereLight` | Enable `shadowMap` on renderer + `castShadow` on light |
| GLTF loading      | `GLTFLoader` + `DRACOLoader`                       | Draco for geometry compression; traverse for shadows   |
| Animation         | `AnimationMixer` + `clipAction()`                  | Update with `clock.getDelta()` every frame             |
| Crossfade         | `action.fadeOut()` / `action.fadeIn()`             | Weight-based blending between walk/run/idle            |
| Environment maps  | `RGBELoader` + `PMREMGenerator`                    | Set `scene.environment` for PBR reflections            |
| Raycasting        | `Raycaster.setFromCamera(pointer, cam)`            | Mouse/touch picking; use `recursive: true` for GLTF    |
| Morph targets     | `mesh.morphTargetInfluences[index]`                | Facial animation, blend shapes from GLTF               |

## Common Mistakes

| Mistake                                                                   | Correct Pattern                                                                 |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Allocating `new THREE.Vector3()` or `new THREE.Color()` inside `useFrame` | Pre-allocate outside the loop to avoid GC pressure every frame                  |
| Using `requestAnimationFrame` manually in React projects                  | Use R3F's `useFrame` hook for frame-by-frame updates                            |
| Not awaiting `renderer.init()` for WebGPU                                 | Always `await renderer.init()` before the first render to avoid race conditions |
| Loading assets without `<Suspense>` boundaries                            | Wrap `<Canvas>` in `<Suspense>` to prevent main thread blocking                 |
| Using high-poly models for background or distant elements                 | Use LOD (Level of Detail) or Impostors to reduce draw calls                     |
| Using `setState` inside render loop for animations                        | Mutate refs directly via `useFrame` for frame-by-frame updates                  |
| Speed tied to frame rate (`rotation += 0.01`)                             | Multiply by `delta` for frame-rate-independent motion                           |
| Not using `clock.getDelta()` for `mixer.update()`                         | Always pass delta time to `mixer.update(delta)` for correct animation speed     |
| Forgetting to dispose loaded GLTF models                                  | Traverse and dispose geometries, materials, and textures on removal             |
| Shadow map enabled on renderer but not on the light                       | Set both `renderer.shadowMap.enabled` and `light.castShadow = true`             |
| Large `far/near` ratio on camera                                          | Keep ratio small to avoid z-fighting; set `near` as large as possible           |

## Delegation

- **Asset and scene graph exploration**: Use `Explore` agent
- **Multi-file scene refactoring and optimization passes**: Use `Task` agent
- **3D architecture and rendering pipeline planning**: Use `Plan` agent

## References

- [Scene, lighting, and model loading](references/scene-and-lighting.md)
- [Animation system and blending](references/animation.md)
- [Performance and asset optimization](references/performance.md)
- [WebGPU and TSL shader patterns](references/webgpu-tsl.md)
- [React Three Fiber patterns and Next.js integration](references/r3f-patterns.md)