Three.js Interactive Guide — Learn 3D Web Graphics

Geometry defines the shape — vertices, edges and faces. Everything is a BufferGeometry: typed arrays of vertex data sent directly to the GPU. Three.js ships 21 built-in constructors. Switch between them above and adjust parameters in real-time.

How Geometry Works

Every vertex has a position (xyz), a normal (the direction the surface faces, for lighting), and UV coordinates (for texture mapping). The index attribute tells the GPU which vertices form each triangle.

Increasing segments creates smoother shapes but higher vertex counts. A SphereGeometry(1, 8, 6) is blocky; SphereGeometry(1, 64, 32) is smooth. Use the sliders above to feel the difference.

Beyond parametric shapes, Three.js offers path-based geometries: LatheGeometry revolves a profile around an axis, TubeGeometry wraps a tube along a 3D curve, ExtrudeGeometry pushes a 2D shape into 3D with bevels, and ShapeGeometry renders flat 2D outlines. Try them in the explorer above.

Materials control appearance — colour, shininess, transparency, and light response. From the zero-cost MeshBasicMaterial to the photorealistic MeshPhysicalMaterial with clearcoat, transmission, and iridescence.

Material Hierarchy

MeshBasicMaterial ignores light entirely — flat colour, cheapest to render. MeshLambertMaterial uses per-vertex diffuse lighting, good for matte surfaces. MeshPhongMaterial adds specular highlights (per-fragment).

MeshStandardMaterial is PBR (physically based rendering) with roughness and metalness. MeshPhysicalMaterial extends it with clearcoat, transmission, iridescence, and sheen.

The camera defines how 3D is projected to 2D. PerspectiveCamera mimics human vision — farther objects shrink. OrthographicCamera keeps all sizes equal. Click the presets above to see how real games use different camera setups — from first-person shooters to isometric strategy games.

Perspective vs Orthographic

PerspectiveCamera takes four parameters: fov (vertical field of view, degrees), aspect (canvas ratio), near and far clipping planes. A FOV of 30 looks telephoto; 75 is standard FPS; 120+ gives ultra-wide fisheye.

OrthographicCamera uses left, right, top, bottom, near, far — defining a box frustum with no perspective. Objects stay the same screen size regardless of distance. Used for isometric games, CAD views, and shadow map cameras.

Lighting makes a 3D scene feel real. Three.js has 7 light types — from AmbientLight that fills everything evenly to SpotLight casting dramatic cones with shadows. Toggle each light type and drag the position to see how it changes the scene.

Choosing the Right Light

DirectionalLight emits parallel rays like the sun — ideal for outdoor scenes. PointLight radiates in all directions from a single position, like a bulb. SpotLight creates a cone beam with soft penumbra edges, perfect for dramatic accents.

HemisphereLight uses two colours (sky above, ground below) for natural outdoor ambience. A three-point setup — key, fill, rim — is the film-industry standard for making any subject look professional.

Everything in a scene is an Object3D. A Mesh combines geometry + material. InstancedMesh draws thousands of copies in one GPU call. Points renders particles. Drag the count slider to see how instancing scales to 50,000 objects at interactive frame rates.

Instancing for Performance

InstancedMesh lets you draw thousands of objects with a single draw call. Each instance can have its own transform matrix and colour, but they all share the same geometry and material. This is the key technique for particle systems, forests, crowds, and anything with many similar objects.

Controls translate user input into camera or object movement. OrbitControls is the default for model viewers. MapControls for top-down. Switch modes and adjust damping, speed, and distance limits to feel the difference.

OrbitControls Configuration

Damping adds inertia — the camera glides to a stop instead of snapping. Auto-rotate slowly orbits when idle. Set minDistance/maxDistance to prevent zooming too close or far. maxPolarAngle prevents looking under the ground.

Post-processing applies screen-space effects after the scene renders. EffectComposer chains passes together — bloom, film grain, pixelation, vignette. Toggle effects and adjust parameters live.

Building a Post-Processing Pipeline

EffectComposer replaces your normal renderer.render() call. Add a RenderPass first, then stack effects. Bloom makes bright areas glow. Pixelate downsamples for a retro look. Order matters — bloom before colour grading, always end with OutputPass.

One scene, many looks. The same tree and house rendered in completely different visual styles — each one powered by a different Three.js technique. Click a style to see it applied live and learn what code creates that look.

One Scene, Many Techniques

Every style above uses the exact same geometry — a tree, a house, and a ground plane. The only things changing are materials, camera type, and post-processing. This is the core insight of Three.js: visual style is not about modeling — it's about how you render.

Clay = one material on everything. Toon = a gradient map that quantizes light into steps. Neon = emissive + bloom. Gold = metalness 1.0 + environment map. Sunset = warm directional light + fog. Blueprint = wireframe + bloom glow.

Shaders are programs that run on the GPU. A vertex shader positions each vertex; a fragment shader colors each pixel. ShaderMaterial lets you write raw GLSL for full creative control — wave deformations, procedural noise, dissolve effects, and anything you can imagine.

How Shaders Work

Every mesh rendered by the GPU passes through two stages. The vertex shader runs once per vertex, transforming positions from model space to screen space. It can also pass data to the fragment shader via varying variables. The fragment shader runs once per pixel, determining the final color.

Uniforms are values you send from JavaScript to GLSL — time, mouse position, colors, thresholds. They stay constant across all vertices/fragments in a single draw call. Varyings interpolate data between vertex and fragment shaders — for example, UV coordinates or custom displacement values.

Textures are images mapped onto geometry surfaces using UV coordinates. Beyond color, you can layer multiple map types — normal, bump, displacement, AO, emissive, and environment — to add realistic detail without increasing polygon count.

Map Types Explained

Color Map (.map) provides the base surface color. Normal Map (.normalMap) fakes surface detail by perturbing how light bounces — cheaper than real geometry. Bump Map (.bumpMap) is a simpler grayscale alternative: white = raised, black = recessed. Displacement Map (.displacementMap) actually moves vertices, creating real geometry — requires high segment counts.

AO Map (.aoMap) darkens crevices for ambient occlusion, needs a second UV set (uv2). Emissive Map (.emissiveMap) makes areas glow independently of lighting. Environment Map (.envMap) adds reflections from a surrounding cubemap.

Tiling & Wrapping

Set texture.wrapS and texture.wrapT to THREE.RepeatWrapping, then use texture.repeat.set(x, y) to tile. MIP mapping (texture.generateMipmaps) automatically creates smaller versions for distant objects, improving performance and reducing aliasing.

Animation brings your scene to life. Three.js provides THREE.Clock for frame-independent timing, AnimationMixer for keyframe playback, and morphTargetInfluences for shape blending. Easing functions control the feel of motion — compare them side by side above.

Clock & Delta Time

Never use fixed increments like x += 0.01 per frame — that runs faster on 144Hz monitors and slower on 30fps phones. Instead, use THREE.Clock to get delta time (seconds since last frame). Multiply all movement by delta and your animation runs at the same speed everywhere.

Easing Functions

Easing functions map a linear progress value t (0 to 1) to a curved output. Linear moves at constant speed. Ease-in-out accelerates then decelerates. Bounce simulates a ball dropping. Elastic overshoots and springs back. The five spheres above animate simultaneously so you can see the difference.

AnimationMixer & KeyframeTrack

AnimationMixer is the Three.js playback engine for keyframe animations. Create KeyframeTrack objects (position, rotation, scale), bundle them into an AnimationClip, then play via mixer.clipAction(clip).play(). Call mixer.update(delta) each frame. This is the same system used for glTF model animations.

Morph Targets

Morph targets blend between vertex positions. Store alternate positions in geometry.morphAttributes.position, then animate mesh.morphTargetInfluences[0] from 0 to 1. The GPU interpolates every vertex — smooth shape transitions with zero CPU cost.

Clip Blending & Crossfading

Real-world 3D characters have multiple animation clips — idle, walk, run. AnimationAction.crossFadeTo() smoothly blends between clips by interpolating action weights. Control playback with timeScale, weight, fadeIn(), fadeOut(), and clampWhenFinished. Listen for 'loop' and 'finished' events on the mixer to trigger game logic.

Raycasting lets you pick, highlight, and interact with 3D objects using the mouse. A THREE.Raycaster shoots an invisible ray from the camera through the mouse position into the scene, returning every object it hits — sorted by distance.

Mouse to Normalized Device Coordinates

The browser gives you pixel coordinates (e.g. 400, 300). Three.js needs normalized device coordinates (NDC) ranging from -1 to +1 on both axes. Convert with: mouse.x = (event.clientX / width) * 2 - 1 and mouse.y = -(event.clientY / height) * 2 + 1. Note the Y-axis is flipped because screen Y goes down but NDC Y goes up.

Intersection Testing

Call raycaster.setFromCamera(mouse, camera) to aim the ray, then raycaster.intersectObjects(objects) to get sorted hits. Each intersection contains .object (the mesh), .point (world-space hit position), .distance, .face, .faceIndex, and .uv coordinates.

Hover, Select & Drag

For hover, raycast on pointermove and set material.emissive on the hit object. For click selection, raycast on pointerdown. For drag, raycast against an invisible ground plane at y=0 to convert mouse movement to XZ world positions — update the selected object's position each frame while the pointer is held down.

Three.js doesn't just render shapes you code by hand — it loads full 3D models authored in Blender, Maya, or any DCC tool. The modern standard is glTF / GLB ("JPEG for 3D"), and GLTFLoader is the workhorse that unpacks geometry, PBR materials, textures, and embedded animations in a single call.

GLTFLoader Basics

GLTFLoader is an async, add-on loader from three/addons/loaders/GLTFLoader.js. Give it a URL and it returns a gltf object containing scene (the root Object3D), animations (AnimationClip array), and cameras / asset metadata. Drop gltf.scene straight into your Three.js scene — materials, textures, and hierarchy come along for the ride.

Auto-Fit & Center

Every author exports at a different scale — some models arrive 100 units tall, others 0.01. Compute a THREE.Box3().setFromObject(model), read its size, and scale the model so its largest axis matches a target. Recenter by subtracting bbox.center. This gives every model a consistent presence regardless of its source units.

Embedded Animations

Many glTF files ship with rigged animations (walk cycles, flaps, bounces). Create a THREE.AnimationMixer(model), call mixer.clipAction(gltf.animations[0]).play(), and update the mixer with mixer.update(delta) each frame. The Flamingo and Horse samples above demonstrate this directly.

Disposal — the Silent Memory Leak

Swapping models without disposing the old one is the most common Three.js memory leak. Traverse the old scene, dispose every geometry, and dispose every texture slot on every material (map, normalMap, roughnessMap, etc.). renderer.info.memory will show you if it's working — numbers should return to baseline after a swap.

Particles turn a static scene into a living one — rain, fire, smoke, sparks, confetti. Three.js renders them with THREE.Points + BufferGeometry: thousands of GPU-drawn sprites updated from a single Float32Array.

BufferGeometry + Typed Arrays

Every particle is three floats in a Float32Array (x, y, z). Wrap that array in a BufferAttribute and register it as the position attribute. Add a parallel color attribute for per-particle color, plus CPU-side arrays for velocity, age, and lifetime. PointsMaterial takes care of rendering; you only touch the position array each frame.

Simple Physics

Each frame, multiply velocity by delta, add it to position, then add gravity * delta back into velocity. That's enough for rain, fire, confetti, and sparks. When a particle's age exceeds its lifetime (or it falls below the floor), respawn it by calling the preset's spawn function — this recycles buffers instead of allocating new particles.

Additive vs Normal Blending

Fire and sparks use THREE.AdditiveBlending — overlapping pixels brighten toward white, giving a glowing look. Rain, snow, and confetti use THREE.NormalBlending because they're opaque objects, not emissive ones. The toggle above shows the difference side by side.

Round vs Square Points

PointsMaterial renders square sprites by default. Attach a circular texture via .map and .alphaMap to get soft round particles — a CanvasTexture painted with a radial gradient costs nothing and avoids shipping an image.

Shadows sell the illusion that objects occupy space. Three.js bakes them via a shadow map — a depth render from the light's point of view — and every common bug you'll hit (acne, peter panning, blocky edges, clipping) comes from a knob you can tune. This section exposes all of them.

Shadow Map Types

BasicShadowMap samples the depth buffer once per pixel — hard pixelated edges, cheapest. PCFShadowMap (the default) averages multiple nearby samples, giving antialiased edges. PCFSoftShadowMap adds a Poisson-disk jitter per frame for realistic softness. VSMShadowMap (variance) uses a two-channel shadow map that can be blurred directly — the softest option but requires opaque receivers.

Bias — The Acne Dial

light.shadow.bias nudges the depth comparison by a tiny amount. Too small (near 0) → the ground samples itself and produces shadow acne, black speckles. Too large (positive) → the shadow detaches from its caster, peter panning. The "right" value depends on your scene scale and map resolution. normalBias offsets the sample along the surface normal and usually helps more than bias for curved objects.

Shadow Camera Frustum

A DirectionalLight uses an orthographic camera to render its shadow map. Its left / right / top / bottom / near / far define a rectangular box — anything outside casts no shadow, and the smaller the box the sharper the shadows (more resolution per world-unit). Crank Ortho Size down to see shadows clip abruptly at the frustum edge; toggle the camera helper to see the box visualized.

Map Resolution

light.shadow.mapSize.set(n, n) sets the shadow map's pixel resolution. 512 is low, 1024 is fine for most scenes, 2048+ becomes worth it when Ortho Size is also large or the camera zooms close. Every doubling quadruples memory, so don't reach for 4096 without reason.

A PBR scene isn't fully lit until it has an environment map. Even without explicit lights, an HDR panorama supplies ambient color, subtle shadows, and the reflections that make metal look like metal. This section explores the scene.environment, scene.background, and PMREMGenerator workflow.

What scene.environment Does

Assigning a cubemap or equirectangular texture to scene.environment makes it the ambient light source for every MeshStandardMaterial and MeshPhysicalMaterial in the scene — automatically, no per-material wiring. The chrome sphere above is lit entirely by the selected environment: swap the preset and its reflections change instantly.

PMREMGenerator — the PBR Prefilter

Raw HDR textures can't be sampled directly for physically correct reflections. PMREMGenerator processes them into a series of mipmap levels, each blurred to match a different roughness. This pre-baked pyramid is what scene.environment actually needs. Call it once per HDR — it's expensive — then discard the source.

Equirectangular (HDR) vs Cubemap

HDR panoramas use equirectangular projection — the whole sphere unwrapped into one image (360° wide, 180° tall). Load with RGBELoader then pass through pmrem.fromEquirectangular(hdr). Cubemaps are six square images (pos/neg × / Y / Z) — loaded with CubeTextureLoader, filtered with pmrem.fromCubemap(cube). Both produce the same kind of filtered pyramid.

Background vs Environment (They Can Differ)

scene.environment affects lighting; scene.background affects the visible sky. They're independent. Set both for the classic skybox look — or keep background as a solid color while environment still reflects in metals (common trick for stylized scenes). backgroundBlurriness (0–1) blurs only the visible background, keeping the environment reflections sharp — Apple's product pages live on this.

Rotation & Intensity

r184 exposes scene.environmentRotation and scene.backgroundRotation as Euler objects. Animate them independently to spin a skybox without the light rotating, or vice versa. scene.environmentIntensity scales the ambient contribution — useful when an HDR is too bright for your scene.