Threejs Agents Scene Builder

threejs-agents-scene-builder

Purpose

This skill is an orchestration guide for building complete Three.js scenes. It provides decision trees that map use cases to the correct combination of lighting, materials, camera, controls, environment, and post-processing. ALWAYS consult this skill first when asked to create a 3D scene or visualization.

Master Decision Tree: Use Case to Scene Recipe

Step 1: Identify the Use Case

Step 2: Choose R3F vs Imperative

Cross-reference: threejs-impl-r3f for R3F patterns, threejs-core-scene-graph for imperative patterns.

Decision Tree: Lighting Setup

Step 1: Scene Type to Lighting Strategy

Step 2: Lighting Intensity (Physically Correct, r160+)

Step 3: Light Count Budget

Critical rules:

• NEVER use PointLight shadows on mobile — each costs 6 shadow map renders
• ALWAYS add directionalLight.target to the scene when repositioning the target
• ALWAYS call RectAreaLightUniformsLib.init() before creating RectAreaLight

Cross-reference: threejs-impl-lighting-shadows for shadow tuning and artifact fixes.

Decision Tree: Material Selection

Critical rules:

• NEVER use MeshPhysicalMaterial when MeshStandardMaterial suffices — it is significantly more expensive
• ALWAYS set material.needsUpdate = true after changing defines or extensions
• ALWAYS dispose materials when removing objects from the scene

Cross-reference: threejs-syntax-materials for material properties and textures.

Decision Tree: Camera Selection

Critical rules:

• ALWAYS call camera.updateProjectionMatrix() after changing fov, near, far, or aspect
• NEVER set near to 0 — this causes z-fighting across the entire scene
• ALWAYS keep the near/far ratio as small as possible (ideally < 1:10000)

Cross-reference: threejs-core-renderer-camera for camera API details.

Decision Tree: Controls Selection

Critical rules:

• ALWAYS call controls.update() in the animation loop when enableDamping is true
• ALWAYS call controls.dispose() on cleanup
• NEVER combine OrbitControls and TransformControls without disabling OrbitControls during transform interaction

Cross-reference: threejs-syntax-controls for controls API details.

Decision Tree: Environment Setup

Critical rules:

• ALWAYS use PMREMGenerator to prefilter environment maps for PBR materials
• NEVER use unprocessed HDR textures as scene.environment — they MUST be PMREM-processed
• Setting scene.environment provides IBL to ALL PBR materials automatically

Cross-reference: threejs-syntax-materials for environment map usage on materials.

Decision Tree: Post-Processing

When to Add Post-Processing

Post-Processing Pipeline Order

ALWAYS follow this pass order:

1. RenderPass (beauty render) — ALWAYS first
2. Geometry passes: SSAO, GTAO, SSR
3. Effect passes: Bloom, DoF, Outline
4. Anti-aliasing: FXAA or SMAA
5. Color grading: LUT, Film
6. OutputPass (tone mapping + color space) — ALWAYS last

R3F Post-Processing

In R3F, use @react-three/postprocessing (wraps pmndrs/postprocessing library):

import { EffectComposer, Bloom, SSAO } from '@react-three/postprocessing'

<EffectComposer>
  <SSAO />
  <Bloom luminanceThreshold={0.9} intensity={0.5} />
</EffectComposer>

Critical rules:

• ALWAYS resize the composer when the window resizes: composer.setSize(w, h)
• NEVER forget OutputPass at the end — without it, tone mapping and color space conversion are skipped
• In R3F, @react-three/postprocessing handles pass ordering automatically

Cross-reference: threejs-impl-postprocessing for pass configuration and tuning.

Scene Composition Checklist

ALWAYS follow this checklist when building a scene:

1. Renderer — Create WebGLRenderer with antialias: true, set pixel ratio, set size
2. Scene — Create Scene, set background and/or environment
3. Camera — Choose type per decision tree, set position
4. Lighting — Choose recipe per decision tree, respect budget
5. Ground/Environment — Add ground plane, environment map, or sky
6. Content — Add geometries, load models, create materials
7. Controls — Choose per decision tree, configure constraints
8. Shadows — Enable on renderer + lights + objects (3-step opt-in)
9. Post-processing — Add if needed, follow pipeline order
10. Resize handling — ALWAYS handle window resize (camera + renderer + composer)
11. Animation loop — requestAnimationFrame or R3F useFrame
12. Disposal — ALWAYS dispose geometries, materials, textures on cleanup

Performance Quick Reference

Cross-reference: threejs-errors-performance for detailed optimization strategies.

Reference Links

• references/methods.md — Decision trees with detailed selection criteria
• references/examples.md — Complete scene recipes for each use case
• references/anti-patterns.md — Common scene composition mistakes

Related Skills

Official Sources

• https://threejs.org/docs/
• https://threejs.org/examples/
• https://r3f.docs.pmnd.rs/
• https://drei.docs.pmnd.rs/