Chapter 816: Fundamentals (Manual)

Core Idea

The first lesson in the manual series: three.js is a higher-level 3D library built on WebGL that handles scenes, cameras, lights, materials and math so you don't have to write raw WebGL, illustrated with a minimal spinning-cube app.

Key Concepts

• Three.js vs. WebGL: WebGL is a low-level API that only draws points, lines and triangles; three.js provides scenes, cameras, lights, materials and 3D math on top of it.
• Renderer: the main object that takes a Scene and Camera and draws (renders) into a canvas.
• Scene graph: a tree of objects — a Scene at the root, containing Mesh, Light, Group and other Object3D-derived nodes.
• Mesh = Geometry + Material: a Mesh draws a specific Geometry (vertex data) with a specific Material (surface appearance); both can be reused across multiple meshes.
• Texture: an image (loaded, generated from canvas, or rendered from another scene) that a material can sample.
• ES module loading: as of three.js r147, loading via <script type="module"> and an import map is the supported way to bring in the library and its addons.

Code Examples

<script type="importmap">
{
  "imports": {
    "three": "./path/to/three.module.js",
    "three/addons/": "./different/path/to/examples/jsm/"
  }
}
</script>
<script type="module">
import * as THREE from "three";
import { OrbitControls } from "three/addons/controls/OrbitControls.js";
</script>

• What it demonstrates: the modern import-map based way to load three.js and its addons as ES modules.

Key Takeaways

1. Three.js is a 3D library built on WebGL, not a replacement for it — it saves you from writing scene/light/material/math code by hand.
2. A minimal app needs a Scene, a Camera, and a WebGLRenderer, plus at least one Mesh (geometry + material) to see anything.
3. Objects are organized in a scene graph rooted at the Scene; lights, meshes and groups are all nodes in that tree.
4. Load three.js via <script type="module"> and an import map — this is the current supported approach as of r147.
5. MeshBasicMaterial ignores lights entirely; switch to a lit material like MeshPhongMaterial once lighting is added to a scene.

Connects To

• WebGLRenderer, PerspectiveCamera, BoxGeometry, MeshBasicMaterial, MeshPhongMaterial: the core objects introduced in this first lesson.
• OrbitControls: the standard addon for interactive camera movement, imported via the module import map shown here.