| name | threejs-builder |
| description | Create simple, performant Three.js web apps/scenes (JS/TS, ES modules): scene/camera/renderer setup, lighting, geometries, materials, animation loop, resizing, OrbitControls, GLTF/GLB loading, and practical performance guardrails. |
| metadata | {"short-description":"Build modern Three.js scenes."} |
Three.js Builder
A focused skill for creating small, performant Three.js web applications using modern ES module patterns.
Philosophy: The Scene Graph Mental Model
Three.js is built on the scene graph—a hierarchical tree of objects where parent transformations affect children. Understanding this mental model is the fastest path to reliable 3D scenes.
Before creating a Three.js app, ask:
- What is the core visual element? (geometry, shape, model)
- What interaction does the user need? (none, orbit controls, custom input)
- What performance constraints exist? (mobile, desktop, WebGL capabilities)
- What animation brings it to life? (rotation, movement, transitions)
Core principles:
- Scene Graph First: Everything added to
scene renders. Use Group for hierarchical transforms.
- Primitives as Building Blocks: Built-in geometries (Box, Sphere, Torus) cover 80% of simple use cases.
- Animation as Transformation: Change position/rotation/scale over time using
requestAnimationFrame or renderer.setAnimationLoop.
- Performance Through Simplicity: Fewer objects, fewer draw calls, reusable geometries/materials.
Quick Start: Essential Setup
Prefer npm + bundler in real repos (Vite/React/etc.): npm i three and import from three and three/addons/.... Use CDN snippets only for truly single-file demos.
Minimal HTML Template (CDN)
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Three.js App</title>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body { overflow: hidden; background: #000; }
canvas { display: block; }
</style>
</head>
<body>
<script type="module">
import * as THREE from 'https://unpkg.com/three@0.160.0/build/three.module.js';
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));
document.body.appendChild(renderer.domElement);
camera.position.z = 5;
renderer.setAnimationLoop(() => {
renderer.render(scene, camera);
});
window.addEventListener('resize', () => {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(window.innerWidth, window.innerHeight);
});
</script>
</body>
</html>
Geometries
Built-in primitives cover most simple app needs. Use BufferGeometry only for custom shapes.
Common primitives:
BoxGeometry(width, height, depth) - cubes, boxesSphereGeometry(radius, widthSegments, heightSegments) - balls, planetsCylinderGeometry(radiusTop, radiusBottom, height) - tubes, cylindersTorusGeometry(radius, tube) - donuts, ringsPlaneGeometry(width, height) - floors, walls, backgroundsConeGeometry(radius, height) - spikes, conesIcosahedronGeometry(radius, detail) - low-poly spheres (detail=0)
Usage:
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshStandardMaterial({ color: 0x44aa88 });
const mesh = new THREE.Mesh(geometry, material);
scene.add(mesh);
Materials
Choose material based on lighting needs and visual style.
Material selection guide:
MeshBasicMaterial - No lighting, flat colors. Use for: UI, wireframes, unlit effectsMeshStandardMaterial - PBR lighting. Default for realistic surfacesMeshPhysicalMaterial - Advanced PBR with clearcoat, transmission. Glass, waterMeshNormalMaterial - Debug, rainbow colors based on normalsMeshPhongMaterial - Legacy, shininess control. Faster than Standard
Common material properties:
{
color: 0x44aa88,
roughness: 0.5,
metalness: 0.0,
emissive: 0x000000,
wireframe: false,
transparent: false,
opacity: 1.0,
side: THREE.FrontSide
}
Lighting
No light = black screen (except BasicMaterial/NormalMaterial).
Light types:
AmbientLight(intensity) - Base illumination everywhere. Use 0.3-0.5DirectionalLight(color, intensity) - Sun-like, parallel rays. Cast shadowsPointLight(color, intensity, distance) - Light bulb, emits in all directionsSpotLight(color, intensity, angle, penumbra) - Flashlight, cone of light
Typical lighting setup:
const ambientLight = new THREE.AmbientLight(0xffffff, 0.4);
scene.add(ambientLight);
const mainLight = new THREE.DirectionalLight(0xffffff, 1);
mainLight.position.set(5, 10, 7);
scene.add(mainLight);
const fillLight = new THREE.DirectionalLight(0x88ccff, 0.5);
fillLight.position.set(-5, 0, -5);
scene.add(fillLight);
Shadows (advanced, use when needed):
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
mainLight.castShadow = true;
mainLight.shadow.mapSize.width = 2048;
mainLight.shadow.mapSize.height = 2048;
mesh.castShadow = true;
mesh.receiveShadow = true;
Animation
Transform objects over time using the animation loop.
Animation patterns:
- Continuous rotation:
renderer.setAnimationLoop((time) => {
mesh.rotation.x = time * 0.001;
mesh.rotation.y = time * 0.0005;
renderer.render(scene, camera);
});
- Wave/bobbing motion:
renderer.setAnimationLoop((time) => {
mesh.position.y = Math.sin(time * 0.002) * 0.5;
renderer.render(scene, camera);
});
- Mouse interaction:
const mouse = new THREE.Vector2();
window.addEventListener('mousemove', (event) => {
mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
});
renderer.setAnimationLoop(() => {
mesh.rotation.x = mouse.y * 0.5;
mesh.rotation.y = mouse.x * 0.5;
renderer.render(scene, camera);
});
Camera Controls
Import OrbitControls from examples for interactive camera movement.
Bundler (npm) import:
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
CDN import:
<script type="module">
import * as THREE from 'https://unpkg.com/three@0.160.0/build/three.module.js';
import { OrbitControls } from 'https://unpkg.com/three@0.160.0/examples/jsm/controls/OrbitControls.js';
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
controls.dampingFactor = 0.05;
renderer.setAnimationLoop(() => {
controls.update();
renderer.render(scene, camera);
});
</script>
Common Scene Patterns
Rotating Cube (Hello World)
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshStandardMaterial({ color: 0x00ff88 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);
renderer.setAnimationLoop((time) => {
cube.rotation.x = time * 0.001;
cube.rotation.y = time * 0.001;
renderer.render(scene, camera);
});
Floating Particle Field
const particleCount = 1000;
const geometry = new THREE.BufferGeometry();
const positions = new Float32Array(particleCount * 3);
for (let i = 0; i < particleCount * 3; i += 3) {
positions[i] = (Math.random() - 0.5) * 50;
positions[i + 1] = (Math.random() - 0.5) * 50;
positions[i + 2] = (Math.random() - 0.5) * 50;
}
geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
const material = new THREE.PointsMaterial({ color: 0xffffff, size: 0.1 });
const particles = new THREE.Points(geometry, material);
scene.add(particles);
Animated Background with Foreground Object
const gridHelper = new THREE.GridHelper(50, 50, 0x444444, 0x222222);
scene.add(gridHelper);
const mainGeometry = new THREE.IcosahedronGeometry(1, 0);
const mainMaterial = new THREE.MeshStandardMaterial({
color: 0xff6600,
flatShading: true
});
const mainMesh = new THREE.Mesh(mainGeometry, mainMaterial);
scene.add(mainMesh);
Colors
Three.js uses hexadecimal color format: 0xRRGGBB
Common hex colors:
- Black:
0x000000, White: 0xffffff
- Red:
0xff0000, Green: 0x00ff00, Blue: 0x0000ff
- Cyan:
0x00ffff, Magenta: 0xff00ff, Yellow: 0xffff00
- Orange:
0xff8800, Purple: 0x8800ff, Pink: 0xff0088
Anti-Patterns to Avoid
Basic Setup Mistakes
❌ Not importing OrbitControls from correct path
Why bad: Controls won't load, THREE.OrbitControls is undefined in modern Three.js
Better: Use import { OrbitControls } from 'three/addons/controls/OrbitControls.js' or the correct CDN examples/jsm path
❌ Forgetting to add object to scene
Why bad: Object won't render, silent failure
Better: Always call scene.add(object) after creating meshes/lights
❌ Using old requestAnimationFrame pattern instead of setAnimationLoop
Why bad: More verbose, doesn't handle XR/WebXR automatically
Better: renderer.setAnimationLoop((time) => { ... })
Performance Issues
❌ Creating new geometries in animation loop
Why bad: Massive memory allocation, frame rate collapse
Better: Create geometry once, reuse it. Transform only position/rotation/scale
❌ Using too many segments on primitives
Why bad: Unnecessary vertices, GPU overhead
Better: Default segments are usually fine. SphereGeometry(1, 32, 16) not SphereGeometry(1, 128, 64)
❌ Not setting pixelRatio cap
Why bad: 4K/5K displays run at full resolution, poor performance
Better: Math.min(window.devicePixelRatio, 2)
Code Organization
❌ Everything in one giant function
Why bad: Hard to modify, hard to debug
Better: Separate setup into functions: createScene(), createLights(), createMeshes()
❌ Hardcoding all values
Why bad: Difficult to tweak and experiment
Better: Define constants at top: const CONFIG = { color: 0x00ff88, speed: 0.001 }
Variation Guidance
IMPORTANT: Each Three.js app should feel unique and context-appropriate.
Vary by scenario:
- Portfolio/showcase: Elegant, smooth animations, muted colors
- Game/interactive: Bright colors, snappy controls, particle effects
- Data visualization: Clean lines, grid helpers, clear labels
- Background effect: Subtle, slow movement, dark/gradient backgrounds
- Product viewer: Realistic lighting, PBR materials, smooth orbit
Vary visual elements:
- Geometry choice: Not everything needs to be a cube. Explore spheres, tori, icosahedra
- Material style: Mix flat shaded, glossy, metallic, wireframe
- Color palettes: Use complementary, analogous, or monochromatic schemes
- Animation style: Rotation, oscillation, wave motion, mouse tracking
Avoid converging on:
- Default green cube as first example every time
- Same camera angle (front-facing, z=5)
- Identical lighting setup (always directional light at 1,1,1)
Remember
Three.js is a tool for interactive 3D on the web.
Effective Three.js apps:
- Start with the scene graph mental model
- Use primitives as building blocks
- Keep animations simple and performant
- Vary visual style based on purpose
- Import from modern ES module paths
Modern Three.js (r150+) uses ES modules from three package or CDN. CommonJS patterns and global THREE variable are legacy.
For advanced topics (GLTF models, shaders, post-processing), see references/advanced-topics.md.
Codex is capable of creating elegant, performant 3D web experiences. These patterns guide the way—they don't limit the result.
For game development (state machines, screen effects, animation switching, parallax), see references/game-patterns.md.
