Three.js scene setup: scenes and fog, cameras, the renderer and tone mapping, the animation loop, object hierarchies, transforms, core math and cleanup, on WebGL or with WebGPU and TSL. Use when creating a scene from scratch, configuring a camera or renderer, handling resize, or arranging objects.
Read from this skill's files on GitHub on 2026-11-09. These are facts about the files, not a review of how well the skill works.
Files
1 file, 0 scripts, SKILL.md is 2808 words
Needs on your machine
Nothing beyond the agent: no scripts or install commands found
Web addresses in its scripts
No URLs in its scripts
Worth a look before running
No sudo, rm -rf, curl | sh or shell=True in its scripts
Agent Skills spec
name and description present, name matches the folder
Last upstream change
2026-10-19
Three.js Fundamentals
Targets three.js r186. Examples use WebGLRenderer; the WebGPU and TSL section uses WebGPURenderer.
Quick Start
import * as THREE from "three";const renderer = new THREE.WebGLRenderer({ antialias: true });renderer.setPixelRatio(window.devicePixelRatio);renderer.setSize(window.innerWidth, window.innerHeight);document.body.appendChild(renderer.domElement);const scene = new THREE.Scene();scene.background = new THREE.Color(0x111318);const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);camera.position.set(0, 1.5, 5);const cube = new THREE.Mesh( new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial({ color: 0x3a86ff }),);scene.add(cube);const light = new THREE.DirectionalLight(0xffffff, 2);light.position.set(3, 4, 5); // shines from its position toward the originscene.add(light);scene.add(new THREE.AmbientLight(0xffffff, 0.4));const timer = new THREE.Timer();timer.connect(document); // freezes the delta while the tab is hiddenfunction animate() { timer.update(); // advance the timer first thing each frame cube.rotation.y += timer.getDelta(); // seconds since the previous frame renderer.render(scene, camera);}renderer.setAnimationLoop(animate);window.addEventListener("resize", () => { camera.aspect = window.innerWidth / window.innerHeight; camera.updateProjectionMatrix(); renderer.setSize(window.innerWidth, window.innerHeight);});
Without a bundler, the browser loads three.js as ES modules through an import map; this is the map for the WebGLRenderer examples above:
const scene = new THREE.Scene();scene.background = new THREE.Color(0x111318); // solid colorscene.fog = new THREE.Fog(0x111318, 1, 100); // linear fog: near, farscene.fog
scene.background also accepts a CubeTexture, or a Texture whose mapping is THREE.EquirectangularReflectionMapping; a plain unmapped texture is drawn as a flat screen-filling quad, not a skybox.
scene.environment lights MeshStandardMaterial and MeshPhysicalMaterial on both renderers, and MeshLambertMaterial and MeshPhongMaterial on WebGLRenderer only. scene.environmentIntensity scales it — material.envMapIntensity scales only material.envMap. See threejs-loaders for HDR environments.
Cameras
PerspectiveCamera
// PerspectiveCamera(fov in degrees, aspect, near, far)const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);camera.position.set(0, 5, 10);camera.lookAt(0,
OrthographicCamera
// OrthographicCamera(left, right, top, bottom, near, far); frustum size in world unitsconst aspect = window.innerWidth / window.innerHeight;const frustumHeight = 10;const camera = new THREE.OrthographicCamera( (-frustumHeight * aspect) / 2,
ArrayCamera
// Renders the scene once per sub-camera, each into its own viewport.// Viewport units under WebGLRenderer are drawing-buffer pixels (CSS size × pixel ratio);// WebGPURenderer multiplies CSS pixels by the pixel ratio itself.const width = window.innerWidth;const height = window.innerHeight;const dpr = renderer.getPixelRatio();
CubeCamera
const cubeRenderTarget = new THREE.WebGLCubeRenderTarget(256);const cubeCamera = new THREE.CubeCamera(0.1, 1000, cubeRenderTarget);scene.add(cubeCamera);const chrome =
With WebGPURenderer, build the target with CubeRenderTarget from three/webgpu instead of WebGLCubeRenderTarget.
WebGLRenderer
const renderer = new THREE.WebGLRenderer({ canvas: document.querySelector("#canvas"), // reuse an existing canvas; omit to create one antialias: true, // MSAA alpha: true
Objects
Object3D
Base class of Mesh, Group, Light and Camera.
const obj = new THREE.Object3D();const child = new THREE.Object3D();
Group and Mesh
const group = new THREE.Group(); // an Object3D that exists to hold childrenconst ball = new THREE.Mesh(new THREE.SphereGeometry(0.5), new THREE.MeshStandardMaterial());group.add(ball);
const mesh = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial());scene.add(mesh);
Coordinate System
Right-handed, +Y up: +X right, +Y up, +Z toward the viewer. A camera at the origin with no rotation looks down −Z.
const axesHelper = new THREE.AxesHelper(5); // red X, green Y, blue Z; 5 = axis lengthscene.add(axesHelper);
Math Utilities
Vector3
const a = new THREE.Vector3(1, 0, 0);const b = new THREE.Vector3(0, 1, 0
Matrix4, Quaternion, Euler
const m = new THREE.Matrix4();m.identity();m.makeTranslation(1, 2, 3);m.makeRotationY(Math.PI
Color
const color = new THREE.Color(0xff0000); // hex numberconst sky = new THREE.Color("#87ceeb"); // also color names and "rgb(255, 0, 0)"color.setHex(0x0000ff);color.
scene.remove(mesh);// dispose geometry, materials and textures only when nothing else still uses themmesh.geometry.dispose();const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];for (const material of materials) { for
Object3D.dispose() releases per-object renderer state (WebGPURenderer bindings, WebGLRenderer instanced-mesh buffers); it does not visit children or free geometry, material or textures. To tear down a subtree, traverse it and dispose each mesh as above. A custom Object3D subclass that overrides dispose() calls super.dispose(). timer.dispose() disconnects a connected timer.
Performance
Frustum culling tests a bounding sphere, not the bounding box: geometry.boundingSphere for a plain mesh, the object's own boundingSphere for InstancedMesh, SkinnedMesh and BatchedMesh. Both are computed once, so after editing positions call geometry.computeBoundingSphere(), and after moving instances or bones far from where they started call object.computeBoundingSphere(), or visible objects get culled.
Merge static geometry that shares a material into one mesh, and use InstancedMesh for many copies of one object (threejs-geometry).
Switch meshes by distance with LOD; the renderer calls update(camera) for you each frame.
On WebGLRenderer, renderer.info.render.calls counts the draw calls of the last render() call (with several passes per frame, set renderer.info.autoReset = false and call renderer.info.reset() once per frame), and renderer.info.memory the live geometries and textures; check them after merging meshes or disposing objects.
import * as BufferGeometryUtils from "three/addons/utils/BufferGeometryUtils.js";// inputs must carry the same set of attributesconst merged = BufferGeometryUtils.mergeGeometries([ new THREE.BoxGeometry(1, 1, 1), new THREE
WebGPU and TSL
import * as THREE from "three/webgpu";const renderer = new THREE.WebGPURenderer({ antialias: true });await renderer.init();
renderer.render() throws until await renderer.init() has completed. setAnimationLoop would run the init too, but await init() right after construction, before setup code touches the renderer: the WebGL 2 fallback replaces renderer.backend during init().
WebGPURenderer falls back to WebGL 2 by itself when WebGPU is unavailable; new THREE.WebGPURenderer({ forceWebGL: true }) forces the fallback, and after await renderer.init(), renderer.backend.isWebGPUBackend reports which backend runs.
Node materials and TSL target WebGPURenderer (either backend). WebGLRenderer renders them only through the WebGLNodesHandler addon (three/addons/tsl/WebGLNodesHandler.js, passed to renderer.setNodesHandler()), a migration aid without VSM shadows, MRT, transmission or the WebGPU post-processing stack. ShaderMaterial and onBeforeCompile are WebGLRenderer-only. Custom shading starts in threejs-shaders.
Built-in materials such as MeshStandardMaterial are converted to their node versions automatically; use the classes when you set node slots.
Common Mistakes
renderer.shadowMap.type = THREE.PCFSoftShadowMap → renderer.shadowMap.type = THREE.PCFShadowMap: deprecated in r182; both renderers now warn and fall back to PCFShadowMap, which is already soft.
const clock = new THREE.Clock() → const timer = new THREE.Timer(); timer.connect(document);: Clock is deprecated in r183 and warns on construction; call timer.update() once per frame before timer.getDelta() or timer.getElapsed().
requestAnimationFrame(animate) → renderer.setAnimationLoop(animate): both renderers' docs advise it over a manual loop, WebXR frames run only through it, and on WebGPURenderer render() throws before the async init that setAnimationLoop performs.
subCamera.viewport = new THREE.Vector4(0, 0, 0.5, 0.5) → subCamera.viewport = new THREE.Vector4(x * dpr, y * dpr, width * dpr, height * dpr): ArrayCamera viewports are drawing-buffer pixels under WebGLRenderer (WebGPURenderer scales CSS pixels by the pixel ratio itself), so fractions draw nothing.
→ : a visible reflective mesh is rendered into the very cube map its material samples.
See Also
threejs-geometry — creating and editing BufferGeometry, instancing, merging, bounding volumes.
threejs-materials — choosing and configuring materials and their texture slots.
threejs-textures — loading textures, color spaces, UV channels.
threejs-lighting — light types, units, and shadow configuration.
threejs-animation — the AnimationMixer and clip system for keyframed motion.
threejs-interaction — raycasting, pointer events, and camera controls.
threejs-loaders — glTF and other file loaders, async loading patterns.
threejs-shaders — ShaderMaterial and GLSL on WebGLRenderer, TSL node materials on WebGPURenderer.
threejs-postprocessing — EffectComposer passes and the WebGPU render pipeline.
threejs-performance — measuring frame cost and cutting draw calls, memory and fill rate.
threejs-react-three-fiber — the same scene graph written as React components.
=
new
THREE
.
FogExp2
(
0x111318
,
0.02
);
// exponential fog: density (pick one)
0
,
0
);
// rotates the camera to face the target
camera.fov = 60;
camera.updateProjectionMatrix(); // required after changing fov, aspect, near or far
(frustumHeight
*
aspect)
/
2
,
frustumHeight / 2,
-frustumHeight / 2,
0.1,
1000,
);
// on resize: recompute left and right from the new aspect, then call camera.updateProjectionMatrix()
const cameras = [];
for (let i = 0; i < 4; i++) {
const subCamera = new THREE.PerspectiveCamera(75, width / height, 0.1, 100);
subCamera.viewport = new THREE.Vector4(
((i % 2) * width * dpr) / 2,
(Math.floor(i / 2) * height * dpr) / 2,
(width * dpr) / 2,
(height * dpr) / 2,
);
subCamera.position.set(-2 + (i % 2) * 4, 1.5, 6);
subCamera.lookAt(0, 0, 0);
subCamera.updateMatrixWorld(); // sub-cameras are not scene-graph children; update them when they move
cameras.push(subCamera);
}
const arrayCamera = new THREE.ArrayCamera(cameras);
arrayCamera.position.set(0, 1.5, 6); // WebGLRenderer culls every viewport with this camera's frustum (fov 50, aspect 1 by default); WebGPURenderer uses each sub-camera's frustum
renderer.render(scene, arrayCamera);
new
THREE
.
Mesh
(
new THREE.SphereGeometry(1, 32, 16),
new THREE.MeshStandardMaterial({ color: 0xffffff, metalness: 1, roughness: 0 }),
scene.background = texture → texture.mapping = THREE.EquirectangularReflectionMapping; scene.background = texture: without an equirect or cube mapping the texture draws as a flat screen-filling quad, not a skybox.
import { mergeGeometries } from "three/examples/jsm/utils/BufferGeometryUtils.js" → import * as BufferGeometryUtils from "three/addons/utils/BufferGeometryUtils.js": the three/examples/jsm/ specifier does not resolve under the standard import map, which maps three/addons/ instead.
<script src="three.min.js"></script> → <script type="module">import * as THREE from "three";</script>: build/three.js and build/three.min.js were removed in r161, so in the browser three.js loads as an ES module behind an import map.
mesh.layers.set(1) → mesh.layers.enable(1): set replaces the layer mask and takes the mesh off layer 0, where the default camera and lights live.
renderer.outputEncoding = THREE.sRGBEncoding → renderer.outputColorSpace = THREE.SRGBColorSpace: the encoding API no longer exists, and the color-space property already defaults to SRGBColorSpace, so the assignment is usually unnecessary.
renderer.physicallyCorrectLights = true → const bulb = new THREE.PointLight(0xffffff, 100): physically based light units are always on and the physicallyCorrectLights and useLegacyLights switches no longer exist, so delete the line and give point and spot lights candela intensities that suit their distance (threejs-lighting).
material.envMapIntensity = 0.5 → scene.environmentIntensity = 0.5: envMapIntensity scales only the material's own envMap, not scene.environment.
mesh.dispose() → mesh.dispose(); mesh.geometry.dispose(); for (const value of Object.values(mesh.material)) if (value?.isTexture) value.dispose(); mesh.material.dispose();: the object-level dispose frees only per-object renderer state, never the geometry, material or textures, and material.dispose() leaves the textures alone too.
import { WebGLCubeRenderTarget } from "three/webgpu" → import { CubeRenderTarget } from "three/webgpu": three/webgpu does not export WebGLCubeRenderTarget, which does not work with WebGPURenderer; keep it for WebGLRenderer.
await renderer.renderAsync(scene, camera) → await renderer.init(); renderer.render(scene, camera): the async render methods are deprecated in r181; initialize once, then render synchronously in the loop.