Chapter 840: Primitives (Manual)

Core Idea

A tour of three.js's built-in geometry primitives (boxes, spheres, planes, text, etc.), useful for prototyping and simple visualizations before moving to artist-authored models, plus the trade-offs of how much to subdivide them.

Key Concepts

• side: THREE.DoubleSide: needed for flat/2D geometry like PlaneGeometry or ShapeGeometry that has no "inside," or the back face disappears; costs more to draw than single-sided, so apply it only where actually needed.
• TextGeometry: needs a font loaded asynchronously first (via FontLoader, commonly wrapped in a promise); by default its rotation pivot is at the left edge, fixed by computing the geometry's bounding box, centering the mesh's position with getCenter().multiplyScalar(-1), and parenting that mesh to an empty Object3D for the actual world placement.
• EdgesGeometry / WireframeGeometry: paired with LineSegments (not a normal Mesh) and a LineBasicMaterial to draw line-based visualizations of a shape's edges/wireframe.
• Points + PointsMaterial: draws a point per vertex instead of faces or lines; PointsMaterial.size controls point size, and sizeAttenuation can be disabled to keep points a constant screen size regardless of camera distance.
• Subdivision trade-off: primitives like spheres accept segment counts that trade visual smoothness for triangle count (e.g. 5×3 segments = 30 triangles vs. 50×50 = 5,000); the right choice depends on how many instances you're drawing — fine for one globe, potentially very expensive multiplied across thousands of instances.

Code Examples

const loader = new FontLoader();
function loadFont(url) {
  return new Promise((resolve, reject) => loader.load(url, resolve, undefined, reject));
}

async function makeText() {
  const font = await loadFont("resources/fonts/helvetiker_regular.typeface.json");
  const geometry = new TextGeometry("three.js", { font, size: 3.0, depth: 0.2 });
  const mesh = new THREE.Mesh(geometry, createMaterial());
  geometry.computeBoundingBox();
  geometry.boundingBox.getCenter(mesh.position).multiplyScalar(-1);

  const parent = new THREE.Object3D();
  parent.add(mesh);
  scene.add(parent);
}

• What it demonstrates: async font loading plus the bounding-box centering trick needed so text spins around its own center rather than its left edge.

Key Takeaways

1. Use side: THREE.DoubleSide for flat/non-solid geometry only — it's slower than default single-sided rendering.
2. TextGeometry needs an async-loaded font and a bounding-box-based centering fix if you want it to rotate around its own center.
3. Points/PointsMaterial is the right tool when you want one visual point per vertex rather than triangles or line segments.
4. Higher subdivision counts look smoother but cost more triangles — weigh that against how many instances of the shape you're actually drawing.

Connects To

• PlaneGeometry / ShapeGeometry / TextGeometry / FontLoader / EdgesGeometry / WireframeGeometry: the specific primitive and loader classes covered in this lesson.