Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 39 ยท Scene, Camera and Renderer

The Scene Graph and Object3D

Learn how Three.js organizes objects in a tree with Scene, Group and Object3D, how parents transform children, and how to traverse, find and remove objects.

Everything you draw in Three.js lives in a tree called the scene graph. The root is a Scene. Its children can be meshes, lights, cameras, or empty containers called groups, and those can have children of their own. The tree matters because a child inherits the transform of its parent: move the parent and everything inside it comes along. A planet with a moon, a car with four wheels, a robot arm with a hand that has fingers: they are all trees.

Object3D is the base class

Scene, Group, Mesh, Light, Camera, Line and Points all extend Object3D, so they share the same abilities.

Member Purpose
position, rotation, scale, quaternion The local transform
add(obj, ...), remove(obj), clear() Manage children
parent, children Navigate the tree
name A string you can search for
visible Hide the object and its subtree without removing it
userData An empty object for your own data
traverse(fn) Visit this object and all descendants
getObjectByName(name) Find a descendant
getWorldPosition(v) Position in world space
layers, renderOrder, castShadow, receiveShadow Rendering controls, covered later

A plain new THREE.Object3D() is an empty node, and new THREE.Group() is the same thing with a clearer name. Use groups to build assemblies.

A tree of objects

Scene The root of the tree
Group An empty node that moves its children
Mesh A leaf that draws something

Transforms flow downward from parent to child.

1 / 2

Building an assembly

Let us build a tiny solar system. The sun is a mesh. The earthOrbit is an empty group placed at the sun. Earth sits at a distance inside that group. Spinning the group makes Earth circle the sun, without any trigonometry. A second group repeats the trick for the moon.

Parents carry their children

The moon circles the earth while the earth circles the sun, yet we only ever changed three rotation values. The moon's world position is the product of all three parents' transforms, calculated by Three.js every frame.

Adding and removing

JavaScript
scene.add(group);          // add one or several: scene.add(a, b, c)
group.add(mesh);           // if mesh had another parent it is removed from it first
group.remove(mesh);        // detach; the mesh still exists in memory
scene.clear();             // remove all children

An object can have only one parent. Adding it somewhere else moves it. Note that remove does not free GPU memory; geometries, materials and textures must be disposed separately, a topic for the performance chapter.

If you want to re-parent an object but keep its world position, use attach instead of add:

JavaScript
newParent.attach(mesh); // recomputes the local transform so the mesh does not jump

Finding and visiting objects

Give objects names, then find them later. This is how you pick parts of a loaded model.

JavaScript
wheel.name = "front-left-wheel";
const w = scene.getObjectByName("front-left-wheel");

scene.traverse((obj) => {
  if (obj.isMesh) obj.castShadow = true;   // apply to every mesh in the tree
});

Every class has an isXxx flag, such as isMesh, isLight, isCamera, isGroup. Prefer these to instanceof because they also work across bundles that load two copies of the library. traverseVisible skips hidden branches, and traverseAncestors walks upward.

Traverse and name

Scene extras: background and fog

Scene has a few properties of its own:

  • scene.background: a Color, a Texture (a flat image behind everything), or a cube/equirectangular texture for a sky.
  • scene.environment: a texture used to light physically based materials (see the lesson on environment lighting).
  • scene.fog: either Fog(color, near, far) for linear fog or FogExp2(color, density) for exponential fog. Fog fades distant objects into the fog color, which hides the far plane and adds depth. Set the background to the same color for a seamless look.
  • scene.overrideMaterial: render every object with one material, useful for debugging.
JavaScript
scene.background = new THREE.Color("#a8c8e8");
scene.fog = new THREE.Fog("#a8c8e8", 10, 40);

Materials must opt in to fog. All built-in materials do by default; for ShaderMaterial you set fog: true and include fog chunks.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A mesh is a child of a group. You rotate the group by 90 degrees. What happens to the mesh?

    Children inherit the parent's transform. The mesh's local numbers stay the same, but its world pose changes.
  2. 2. How many parents can an Object3D have?

    Adding an object to a new parent removes it from the old one.
  3. 3. Which method re-parents an object while keeping its world position?

    attach recomputes the local transform so the object stays where it is in world space.
  4. 4. Why test obj.isMesh instead of obj instanceof THREE.Mesh?

    The flags are plain properties, independent of which copy of the class created the object.

Summary

  • The scene graph is a tree of Object3D nodes; children inherit the transforms of their parents.
  • Use Group as a pivot or container, and rotate a pivot to orbit things without trigonometry.
  • add, remove, attach, traverse and getObjectByName are the everyday tools; give meaningful name values.
  • scene.background, scene.environment and scene.fog shape the whole look.

Next: PerspectiveCamera