threejs

name

threejs

description

Comprehensive Three.js development guide covering scene setup, geometry, materials, lighting, textures, animation, shaders, interaction, post-processing, and asset loading. Use when the user is building or modifying any Three.js project, creating 3D scenes, working with WebGL rendering, implementing 3D animations, writing GLSL shaders, setting up camera controls, loading 3D models (GLTF/OBJ/FBX), or doing any Three.js-related development. Also use when the user mentions 'three.js', 'threejs', 'WebGL', '3D scene', 'shader', 'GLTF', or 'post-processing effects'.

Three.js Best Practices

Quick Start

import * as THREE from "three";

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true });

renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.outputColorSpace = THREE.SRGBColorSpace;
renderer.toneMapping = THREE.ACESFilmicToneMapping;
document.body.appendChild(renderer.domElement);

// Mesh
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

// Light
const light = new THREE.DirectionalLight(0xffffff, 1);
light.position.set(5, 5, 5);
scene.add(light);
scene.add(new THREE.AmbientLight(0xffffff, 0.3));

camera.position.z = 5;

// Animation loop
const clock = new THREE.Clock();
function animate() {
  const delta = clock.getDelta();
  cube.rotation.x += delta;
  cube.rotation.y += delta;
  renderer.render(scene, camera);
}
renderer.setAnimationLoop(animate);

// Resize
window.addEventListener("resize", () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

Topic References

Read the relevant reference file based on the task at hand:

• references/fundamentals.md - Scene, camera, renderer, Object3D, math utilities, coordinate system, cleanup/disposal patterns
• references/geometry.md - Built-in shapes, custom BufferGeometry, InstancedMesh, points, lines, edges, geometry utilities
• references/materials.md - All material types, PBR workflow (Standard/Physical), environment maps, material properties, multiple materials
• references/lighting-and-shadows.md - Light types (Ambient, Hemisphere, Directional, Point, Spot, RectArea), shadow setup, IBL/HDR, lighting setups
• references/textures.md - Texture loading/config, color spaces, HDR, render targets, UV mapping, texture atlas, memory management
• references/animation.md - AnimationMixer/Clip/Action, skeletal animation, morph targets, animation blending, procedural animation
• references/shaders.md - ShaderMaterial, GLSL uniforms/varyings, common shader patterns, extending built-in materials, instanced shaders
• references/interaction.md - Raycasting, camera controls (Orbit/Fly/PointerLock), TransformControls, DragControls, selection, coordinate conversion
• references/postprocessing.md - EffectComposer, bloom, DOF, SSAO, FXAA/SMAA, custom ShaderPass, selective bloom, multi-pass rendering
• references/loaders.md - GLTF/Draco loading, OBJ/FBX/STL formats, LoadingManager, async patterns, caching, error handling

Essential Patterns

Always dispose resources when done:

geometry.dispose();
material.dispose();
texture.dispose();
renderer.dispose();

Frame-rate-independent animation: Always use clock.getDelta() or clock.getElapsedTime().

Pixel ratio: Always renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)) to cap at 2x.

Color spaces: Set texture.colorSpace = THREE.SRGBColorSpace for color/albedo maps. Leave data maps (normal, roughness, metalness) as default.