Chapter 844: Scene Graph (Manual)

Core Idea

Three.js's core structure is a scene graph — a hierarchy where each node's transform is relative to its parent's "local space" — illustrated with a sun/earth/moon system where nesting Object3D pivots does the orbital math for you.

Key Concepts

• Local space: a child object's position/rotation/scale is relative to its parent, not to the world — the same way you can walk around on Earth without accounting for Earth's own rotation or orbit.
• Scale propagates to children: parenting a mesh to a scaled-up parent (e.g. a sun scaled 5x) multiplies the child's own scale and position offset by that same factor — a common source of "why is my child object huge and far away" surprises.
• Invisible Object3D pivots: an Object3D has no geometry/material but is a real scene-graph node — used purely to represent a local space (e.g. solarSystem, earthOrbit, moonOrbit) so meshes can be parented to a pivot instead of inheriting an unwanted parent's scale.
• Chained pivots produce complex motion "for free": nesting moonOrbit inside earthOrbit inside solarSystem reproduces the moon's complex spirograph-like path around the sun without computing it manually — the graph does the composition.
• AxesHelper / GridHelper: visualize a node's local axes / a reference grid; commonly combined with depthTest: false and a renderOrder so they draw on top of geometry that would otherwise occlude them.

Code Examples

const solarSystem = new THREE.Object3D();
scene.add(solarSystem);

const earthOrbit = new THREE.Object3D();
earthOrbit.position.x = 10;
solarSystem.add(earthOrbit);

const earthMesh = new THREE.Mesh(sphereGeometry, earthMaterial);
earthOrbit.add(earthMesh);

const moonOrbit = new THREE.Object3D();
moonOrbit.position.x = 2;
earthOrbit.add(moonOrbit);

const moonMesh = new THREE.Mesh(sphereGeometry, moonMaterial);
moonMesh.scale.set(0.5, 0.5, 0.5);
moonOrbit.add(moonMesh);

• What it demonstrates: nesting Object3D pivots (solarSystem → earthOrbit → moonOrbit) so rotating each pivot independently produces correct orbital motion without manual trigonometry.

Key Takeaways

1. A child's transform is relative to its parent's local space — scale and position both compose down the hierarchy.
2. If a parent's scale isn't meant to affect a child (e.g. a planet parented to a scaled-up sun), insert an unscaled Object3D pivot between them instead.
3. Chaining simple rotating pivots reproduces complex real-world motion (like a moon's path around the sun) without hand-computing the combined trajectory.
4. AxesHelper/GridHelper with depthTest/renderOrder adjustments make an otherwise-invisible scene graph structure visible for debugging.

Connects To

• AxesHelper / GridHelper: the visualization helpers used throughout this lesson.