Build: The Headlight in TSL

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

paint.tsl.js

The project file that builds the Lumen paint and the headlight lens from TSL nodes.

backendName

A small helper that returns WebGL 2, WebGPU or WebGL 2 (fallback) for the console and bug reports.

opt-in path

A new way of running that only users who ask for it get (here ?webgpu), while everyone else keeps the proven one.

equirectangular texture

A panorama image stored as a flat rectangle. Assigned to scene.environment, it lights and reflects.

emissive

Light a surface gives off itself, whatever lights are in the scene. The headlight lens uses it.

glow uniform

The number that sets the lens brightness. Set glow.value = 0 and the lamp is off.

1. 1

   Run the WebGPU path

   Open your project with ?webgpu at the end of the address. The console prints backend: WebGPU in Chrome with a GPU. Then add forceWebGL: true to the WebGPURenderer options: it prints backend: WebGL 2 (fallback) with no warning, the WebGPU path on the WebGL 2 backend. Remove the option to go back.

2. 2

   Switch the lamp off

   On the WebGPU path, after the model loads, add bike.getObjectByName("headlight").children[1].material.userData.glow.value = 0;. The lens turns dark glass: no new shader, only a number changed. (On WebGL 2 the lens is a classic material: set its emissiveIntensity instead.)

3. 3

   Change the flakes

   On the WebGPU path, call createPaintTSL({ flakeScale: 60, flakeStrength: 1 }) in main.js. The flakes become fewer and bigger.

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

import * as THREE from "three";

// Two renderers since Phase 13. WebGL 2 stays the default: Phase 12's GLSL paint (and Phase 15's effects) need it.
// Add ?webgpu to the address to run the WebGPU path (WebGPURenderer and the TSL paint), which falls back to WebGL 2 itself.
export function createRenderer(container) {
  const renderer = new THREE.WebGLRenderer({ antialias: true });
  setUp(renderer, container);
  return renderer;
}

/** Phase 13: the WebGPU path. Async: the browser must be asked for a GPU before the first frame. */
export async function createWebGPURenderer(container) {
  const { WebGPURenderer } = await import("three/webgpu"); // downloaded only on this path: about 676 kB
  const renderer = new WebGPURenderer({ antialias: true });
  setUp(renderer, container);
  await renderer.init(); // picks the backend; render() before this finishes throws
  return renderer;
}

function setUp(renderer, container) {
  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); // sharp, but never more than 4x the pixels of ratio 1
  renderer.shadowMap.enabled = true; // Phase 5: draw shadow maps
  renderer.toneMapping = THREE.NeutralToneMapping; // Phase 5: keeps Lumen orange orange when the light is bright
  container.append(renderer.domElement);
}

/** "WebGPU", "WebGL 2 (fallback)" or "WebGL 2": what the console says, and what to put in a bug report. */
export function backendName(renderer) {
  if (!renderer.isWebGPURenderer) return "WebGL 2";
  return renderer.backend.isWebGPUBackend ? "WebGPU" : "WebGL 2 (fallback)";
}

export function resizeRenderer(renderer, width, height) {
  renderer.setSize(width, height); // also sets the canvas's CSS size
}

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

1. 1

   Why the showroom needs this now. Tomás asked whether to move to WebGPU. The honest answer is "not everything at once": Phase 12's paint uses onBeforeCompile, which WebGPURenderer doesn't support (Topic 13.4), and the effect chain coming in Phase 15 is WebGL-only too. So the team ships WebGPU as an opt-in path, the way real migrations go: both paths stay working, and the WebGPU one gets the TSL paint. And the bike gets a headlight, which Ama asked for so the evening view looks finished.

2. 2

   What it adds. src/world/renderer.js keeps createRenderer() (WebGL 2) and adds createWebGPURenderer() (a WebGPURenderer, await init()) and backendName(renderer). src/world/scene.js gives the HDR image straight to scene.environment (both renderers prepare it themselves) and picks the right PMREMGenerator for the fallback room. src/materials/paint.tsl.js holds createPaintTSL() and createGlow(). src/objects/bike.js gains createHeadlight(lensMaterial) and createLens(). src/ui/panel.js prices the headlight. src/main.js reads ?webgpu, creates the matching renderer and paint, prints the backend, and adds the headlight.

3. 3

   How it plugs in. Every other module keeps import * as THREE from "three": the classes are the same ones. Only renderer.js, scene.js and paint.tsl.js import from three/webgpu and three/tsl. The picker, the controls and the loop did not change. The lens is the one material that differs per path: a node material can only be drawn by WebGPURenderer, so on WebGL 2 the lens is a classic emissive material. And the WebGPU path loads with import() only when asked for: measured with vite build, the main chunk is 135.60 kB (39.22 kB gzipped) instead of 821.75 kB, because three/webgpu (675.53 kB) and paint.tsl.js become separate files that ?webgpu visitors download.

4. 4

   What the showroom can do now that it could not before. With ?webgpu, run on WebGPU where the browser has it (falling back to WebGL 2 without any code of ours) and paint the frame from a node graph with uniforms (paint.userData.flake.density.value); without it, run exactly as before. Both show a headlight that glows, and the console names the backend.

5. 5

   What is still missing. The paint colour is fixed: a customer can't pick one yet. Phase 14 adds the rear light with a small raw-GPU overlay. Phase 15 adds bloom so the headlight glows on the WebGL 2 path (its EffectComposer doesn't run on WebGPURenderer, so that path keeps plain rendering until the effects are ported to nodes). Phase 18 handles the loss of the GPU.

6. 6

   Same function, two paints. paintFrame (Phase 12) doesn't care which paint it gets: createPaint() and createPaintTSL() take the same options and return a material named lumen-paint. That is the trick of a gradual migration: the code around the swap doesn't change.

• Run the showroom on both paths and read the backend

• Explain why only three files changed their imports

• Add a node-material part (the lens) and change it with a uniform

• Name what is still missing and which phase adds it