Build: The World Modules

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

module

A JavaScript file that exports functions or values. Other files import them by path.

updatable

In this course: any object with a tick(delta) method that the loop calls once per frame.

turntable

A group holding the stand and the bike, so rotating one object turns them both.

seat tube

The frame tube that runs from the bottom bracket up to the seat. This phase's bike part.

1. 1

   Add a second updatable

   In the live example add loop.add({ tick: () => { camera.position.y = 1.2 + Math.sin(performance.now() / 1000) * 0.1; camera.lookAt(0, 0.4, 0); } }); after loop.add(turntable);. The camera bobs gently: anything with a tick(delta) can join the loop without a new loop.

2. 2

   Stop the loop

   After loop.start(); add setTimeout(() => loop.stop(), 500); and two lines that log renderer.info.render.frame after 800 ms and after 1200 ms. Both print the same number: stop() called setAnimationLoop(null), so no frame is drawn any more and the stand freezes. Use it when the canvas scrolls out of view.

Your lumen-3d project after this topic. Click a file to see it in full.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Lumen Bikes · 3D showroom</title>
    <style>
      html, body { margin: 0; height: 100%; background: #0b1118; color: #e6edf6; font-family: system-ui, sans-serif; }
      #app { position: fixed; inset: 0; }
      canvas { display: block; }
      #fallback { position: fixed; inset: 0; display: grid; place-content: center; justify-items: center; gap: 12px; padding: 16px; text-align: center; background: #0b1118; }
      #fallback[hidden] { display: none; }
      #fallback img { max-width: min(100%, 420px); max-height: 60%; border-radius: 8px; }
    </style>
  </head>
  <body>
    <div id="app"></div>
    <div id="fallback" hidden>
      <p>Your browser can't draw 3D here, so here is a picture of the Lumen bike instead.</p>
      <img src="/data/3d/showroom-poster.png" alt="The Lumen Bikes showroom: an orange e-bike on a round display stand" />
    </div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: the story's trouble came from one file where nothing had an owner. Kofi could not change the pixel ratio without reading the loop. Every later phase adds more (controls, a panel, loading); without a split main.js would become a thousand lines nobody dares touch.

2. 2

   What this phase adds. In src/world/: renderer.js (createRenderer, resizeRenderer), scene.js, camera.js (createCamera, resizeCamera), lights.js and loop.js (createLoop returning start(), stop(), add(updatable)); src/objects/showroom.js (createStand); and the bike's seat tube, from the bottom bracket (0, 0.30, 0) to the seat cluster (−0.10, 0.82, 0), radius 0.020, named "seat-tube". main.js becomes wiring.

3. 3

   How it plugs in. The stand moves into showroom.js unchanged. tubeBetween, the down-tube and the top-tube keep their points, which now sit inside createBike as local constants instead of Phase 2's exported POINTS (nothing imports it). Phase 1's supportsWebGL2(), #fallback and startShowroom() stay. The stand and bike share a turntable group whose tick(delta) turns 0.25 radians a second: one turn in about 25 s, the same speed as Phase 2's time / 4000, now at any refresh rate.

4. 4

   Resize and delta. The loop uses a connected THREE.Timer (Topic 3.2) and passes delta to everything added with loop.add. main.js observes #app with a ResizeObserver (Topic 3.3), skips a 0-pixel box, and the pixel ratio is capped at 2.

5. 5

   What the showroom can do now: every part has a home; the loop reports a real delta; the canvas keeps its proportions in any container; a hidden tab does not make the stand jump. Still missing: the rear triangle (Phase 4), real materials and light (Phase 5), wheels (Phases 6–7), controls (Phase 8). Today the frame is three orange tubes on a stand.

• Your project has the five src/world/ files, showroom.js and the updated bike.js

• The stand and bike turn together at the same speed on any screen

• The canvas keeps its proportions when you resize or hide and show it

• The scene tree shows down-tube, top-tube and seat-tube under bike