@woosh/meep-engine 3.30.0 → 3.31.0

package/src/shade/playground/particle_system/main.js

@@ -1,325 +1,378 @@
-import Vector3 from "../../../core/geom/Vector3.js";
-import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
-import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
-import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
-import { create_frame_loop } from "../../renderer/create_frame_loop.js";
-import { Renderer } from "../../renderer/Renderer.js";
-import { ShadeTransparencyMode } from "../../renderer/ShadeTransparencyMode.js";
-import { load_default_environment } from "../load_default_environment.js";
-import {
-    animate_particle_scene,
-    build_particle_scene,
-    configure_particles,
-} from "./particle_scene.js";
-
-/**
- * The page for the GPU particle playground: build a scene, hand it to the engine's own
- * {@link Renderer}, and let it draw. There is no frame graph here, no pass, no pipeline and no
- * camera buffer — the particles are drawn where the renderer draws them, inside the AVBOIT
- * transparency pipeline as a side channel of the transparent meshes.
- *
- * That is the point of the page: the transparent pane and the particles composite against each
- * other with no sort and no ordering rule, because they share one voxel volume. Switch the
- * transparency mode to MBOIT and the particles vanish while the pane stays — MBOIT is the legacy
- * path and has no particle channel — which is a fair way to see where they now live.
- *
- * Serve the workspace with `npm run dev --workspace @woosh/meep-engine` and open
- * `/src/shade/playground/particle_system/index.html`. See README.md for what to look at and for
- * the `?debug` query flag that swaps the frame loop for manual stepping.
- */
-
-/** Device pixels per CSS pixel, capped: 64k billboards at 3x cost more than they show. */
-const MAX_PIXEL_RATIO = 2;
-
-/** The page is full-bleed, so the canvas is the window. In CSS pixels: the renderer scales them. */
-const view_size = () => [Math.max(1, window.innerWidth), Math.max(1, window.innerHeight)];
-
-const CAMERA = {
-    position: new Vector3(9.5, 4.5, 9.5),
-    target: new Vector3(0, 2, 0),
-    fov_degrees: 55,
-    near: 0.1,
-    far: 200,
-};
-
-/** How often the counters are copied back for the overlay. Display only — nothing sizes a pass. */
-const STATS_INTERVAL_FRAMES = 30;
-
-/** Particles one press of the burst button asks the sparks emitter for. */
-const BURST_COUNT = 4000;
-
-const element = id => document.getElementById(id);
-
-async function main() {
-    const canvas = element("view");
-
-    // The canvas is the renderer's: `initialize` and `resize` set its backing size from the CSS
-    // size they are given and the pixel ratio, and pin its style to match. Nothing here writes
-    // canvas.width.
-    const pixel_ratio = Math.min(window.devicePixelRatio || 1, MAX_PIXEL_RATIO);
-    let [view_width, view_height] = view_size();
-
-    // ---- camera and controls, before anything needs a device --------------------------------
-    // Wired first on purpose: a browser without an adapter still gets a page that can be driven,
-    // and the failure it reports is the device's, not a cascade of undefined handlers.
-
-    const camera = new PerspectiveCamera();
-
-    camera.near = CAMERA.near;
-    camera.far = CAMERA.far;
-    camera.fov = CAMERA.fov_degrees * DEG_TO_RAD;
-    camera.aspect = view_width / view_height;
-    camera.transform.setTranslation(CAMERA.position[0], CAMERA.position[1], CAMERA.position[2]);
-    camera.transform.lookAt(CAMERA.target);
-    camera.transform.updateMatrix();
-
-    // document.body rather than the canvas: the controller starts a keyboard device, and only a
-    // focusable element receives key events
-    const controller = new OrbitalCameraController(camera, document.body);
-    controller.look(CAMERA.position, CAMERA.target);
-    controller.movement_speed_scale = 4;
-
-    /** @type {Renderer|null} the renderer once its device is up; null before, and on failure */
-    let renderer = null;
-
-    /** @type {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem|null} */
-    let system = null;
-
-    const world = await build_particle_scene();
-    const { scene, emitters } = world;
-
-    Object.assign(globalThis, { camera, controller, scene, emitters, world });
-
-    /**
-     * Where the camera is and what it orbits, as plain numbers: enough to put another instance of
-     * this page in exactly the same view.
-     *
-     * @returns {{position: number[], target: number[], fov_degrees: number}}
-     */
-    globalThis.camera_state = () => {
-        const p = camera.transform;
-        const t = controller.target;
-        const round = v => Math.round(v * 1000) / 1000;
-
-        return {
-            position: [round(p.translation_x), round(p.translation_y), round(p.translation_z)],
-            target: [round(t.x), round(t.y), round(t.z)],
-            fov_degrees: round(camera.fov / DEG_TO_RAD),
-        };
-    };
-
-    /**
-     * Put the camera where a {@link camera_state} says.
-     *
-     * @param {{position: number[], target: number[], fov_degrees?: number}|string} state
-     */
-    globalThis.apply_camera = state => {
-        const parsed = typeof state === "string" ? JSON.parse(state) : state;
-
-        if (parsed.fov_degrees !== undefined) {
-            camera.fov = parsed.fov_degrees * DEG_TO_RAD;
-        }
-
-        controller.look(
-            new Vector3(parsed.position[0], parsed.position[1], parsed.position[2]),
-            new Vector3(parsed.target[0], parsed.target[1], parsed.target[2])
-        );
-    };
-
-    function apply_settings() {
-        if (renderer === null) {
-            return;
-        }
-
-        renderer.feature_particles_enabled = element("particles").checked;
-        renderer.transparency_mode = element("transparency").value === "MBOIT"
-            ? ShadeTransparencyMode.MBOIT
-            : ShadeTransparencyMode.AVBOIT;
-        renderer.feature_taa_enabled = element("taa").checked;
-    }
-
-    element("particles").addEventListener("change", apply_settings);
-    element("transparency").addEventListener("change", apply_settings);
-    element("taa").addEventListener("change", apply_settings);
-
-    element("burst").addEventListener("click", () => {
-        /*
-         The emitter has a row from the moment configure_particles registered it, and none before
-         — `spawn` refuses an emitter it does not hold. And a burst queued while the particles are
-         switched off is never drained: the ring only empties inside a simulated frame, so the
-         clicks would pile up and arrive together, seconds late, the moment they are switched back
-         on. Both are the same answer: the button does nothing.
-        */
-        if (system === null || !renderer.feature_particles_enabled || system.registry.context(emitters.sparks) === undefined) {
-            return;
-        }
-
-        // The CPU's one way to ask for particles, and it is a facade over the GPU path: the count
-        // reaches a command buffer, a pass adds it to that emitter's pending spawns, and the same
-        // budget and INIT program serve it as serve the emitter's own rate.
-        system.spawn(emitters.sparks, BURST_COUNT);
-    });
-
-    document.body.focus();
-
-    // ---- the device, last --------------------------------------------------------------------
-
-    const context = canvas.getContext("webgpu");
-
-    if (context === null) {
-        return show_message(
-            "No WebGPU context.\n\nThis browser has no WebGPU, or the page is not a secure context "
-            + "— it has to be served over http://localhost rather than opened from file://."
-        );
-    }
-
-    const candidate = new Renderer();
-
-    try {
-        await candidate.initialize({ context, pixelRatio: pixel_ratio });
-    } catch (e) {
-        console.error(e);
-        return show_message("The device could not be acquired.\n\n" + e.message);
-    }
-
-    renderer = candidate;
-    globalThis.renderer = renderer;
-
-    renderer.resize(view_width, view_height);
-
-    // eye adaptation drifts for seconds after any change, which makes the picture hard to compare
-    renderer.feature_automatic_exposure_enabled = false;
-    renderer.exposure_compensation = 1.2;
-
-    system = configure_particles(renderer, world);
-    globalThis.particles = system;
-
-    apply_settings();
-
-    // the meshes are lit; without an environment they are lit by the sun alone
-    load_default_environment(scene).catch(e => console.warn("environment:", e.message));
-
-    // ---- frame loop --------------------------------------------------------------------------
-
-    const device = renderer.graphics.device;
-
-    let stats_pending = false;
-    let frame_index = 0;
-    let time = 0;
-    let fps = 0;
-
-    function frame(dt) {
-        time += dt;
-        fps = dt > 0 ? fps * 0.9 + 0.1 / dt : fps;
-
-        const [width, height] = view_size();
-
-        if (width !== view_width || height !== view_height) {
-            view_width = width;
-            view_height = height;
-            camera.aspect = width / height;
-            renderer.resize(width, height);
-        }
-
-        animate_particle_scene(world, system, time);
-        controller.update();
-
-        renderer.render(camera, scene, dt);
-
-        frame_index++;
-
-        if (!stats_pending && frame_index % STATS_INTERVAL_FRAMES === 0) {
-            capture_stats();
-        }
-    }
-
-    /**
-     * Read the counts back to display them. The system does the copying and the decoding; the page
-     * only decides how often to ask and what to put on screen.
-     */
-    function capture_stats() {
-        stats_pending = true;
-
-        system.read_stats().then(stats => {
-            stats_pending = false;
-
-            globalThis.__stats = { ...stats, frame: frame_index, fps };
-            write_hud(globalThis.__stats);
-        }).catch(() => {
-            stats_pending = false;
-        });
-    }
-
-    /** @type {(() => void)|null} */
-    let stop_loop = null;
-
-    /**
-     * One frame, with the loop stopped on the first failure.
-     *
-     * A lost device makes `render` throw, and the frame loop re-arms itself before it calls back —
-     * so without this the page would throw once per frame, for ever, with the first and most
-     * informative failure scrolled far out of reach.
-     *
-     * @param {number} dt
-     */
-    function guarded_frame(dt) {
-        try {
-            frame(dt);
-        } catch (e) {
-            stop_loop?.();
-            console.error(e);
-            show_message("The frame failed and the loop has stopped.\n\n" + e.message);
-        }
-    }
-
-    device.lost?.then(info => {
-        stop_loop?.();
-        show_message("The GPU device was lost.\n\n" + (info?.message ?? ""));
-    });
-
-    if (new URLSearchParams(location.search).has("debug")) {
-        // Drive frames by hand when the tab is hidden (rAF suspended) — headless verification.
-        // Nothing is scheduled: a stray rAF frame interleaved with __step would make the count the
-        // caller asked for and the count that ran two different numbers.
-        globalThis.__step = (n = 1, dt = 1 / 60) => {
-            for (let i = 0; i < n; i++) {
-                guarded_frame(dt);
-            }
-            return frame_index;
-        };
-        return;
-    }
-
-    stop_loop = create_frame_loop(dt => guarded_frame(Math.min(dt, 0.05)));
-}
-
-/** Push one stats snapshot into the overlay. Absent elements are simply skipped. */
-function write_hud({ fps, alive, dead, sim_workgroups, sim_padded }) {
-    const put = (id, value) => {
-        const node = element(id);
-        if (node !== null) {
-            node.textContent = value;
-        }
-    };
-
-    put("stat-fps", fps.toFixed(0));
-    put("stat-alive", alive.toLocaleString());
-    put("stat-dead", dead.toLocaleString());
-    // Padding rounds each program's run up to a whole workgroup, so this is >= alive; the gap is
-    // what wave-coherence costs in lanes.
-    put("stat-sim-lanes", sim_padded.toLocaleString());
-    put("stat-dispatch", sim_workgroups.toLocaleString());
-}
-
-function show_message(text) {
-    const node = element("message");
-
-    if (node !== null) {
-        node.textContent = text;
-    }
-}
-
-main().catch(e => {
-    console.error(e);
-    show_message("The particle playground failed to start — see the console.\n\n" + e.message);
-});
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { ShadeTransparencyMode } from "../../renderer/ShadeTransparencyMode.js";
+import { FrameRateMeter } from "../frame_rate_meter.js";
+import { load_default_environment } from "../load_default_environment.js";
+import {
+    mark_particle_stats_stale,
+    particle_stats_after_readback_failure
+} from "../particle_stats_readback.js";
+import {
+    animate_particle_scene,
+    build_particle_scene,
+    configure_particles,
+} from "./particle_scene.js";
+
+/**
+ * The page for the GPU particle playground: build a scene, hand it to the engine's own
+ * {@link Renderer}, and let it draw. There is no frame graph here, no pass, no pipeline and no
+ * camera buffer — the particles are drawn where the renderer draws them, inside the AVBOIT
+ * transparency pipeline as a side channel of the transparent meshes.
+ *
+ * That is the point of the page: the transparent pane and the particles composite against each
+ * other with no sort and no ordering rule, because they share one voxel volume. Switch the
+ * transparency mode to MBOIT and the particles vanish while the pane stays — MBOIT is the legacy
+ * path and has no particle channel — which is a fair way to see where they now live.
+ *
+ * Serve the workspace with `npm run dev --workspace @woosh/meep-engine` and open
+ * `/src/shade/playground/particle_system/index.html`. See README.md for what to look at and for
+ * the `?debug` query flag that swaps the frame loop for manual stepping.
+ */
+
+/** Device pixels per CSS pixel, capped: 64k billboards at 3x cost more than they show. */
+const MAX_PIXEL_RATIO = 2;
+
+/** The page is full-bleed, so the canvas is the window. In CSS pixels: the renderer scales them. */
+const view_size = () => [Math.max(1, window.innerWidth), Math.max(1, window.innerHeight)];
+
+const CAMERA = {
+    position: new Vector3(9.5, 4.5, 9.5),
+    target: new Vector3(0, 2, 0),
+    fov_degrees: 55,
+    near: 0.1,
+    far: 200,
+};
+
+/** How often the counters are copied back for the overlay. Display only — nothing sizes a pass. */
+const STATS_INTERVAL_FRAMES = 30;
+
+/** Particles one press of the burst button asks the sparks emitter for. */
+const BURST_COUNT = 4000;
+
+const element = id => document.getElementById(id);
+
+/**
+ * The HUD cells {@link write_hud} fills, and the ones a failed readback marks.
+ * @type {string[]}
+ */
+const HUD_STAT_IDS = ["stat-fps", "stat-alive", "stat-dead", "stat-sim-lanes", "stat-dispatch"];
+
+/**
+ * Longest step the simulation is advanced by, whatever the frame took. A tab
+ * that was in the background for ten seconds must not advance the scene by ten
+ * seconds in one tick. The readout is fed the unclamped interval — see
+ * {@link FrameRateMeter}.
+ * @type {number}
+ */
+const MAX_SIMULATION_STEP = 0.05;
+
+async function main() {
+    const canvas = element("view");
+
+    // The canvas is the renderer's: `initialize` and `resize` set its backing size from the CSS
+    // size they are given and the pixel ratio, and pin its style to match. Nothing here writes
+    // canvas.width.
+    const pixel_ratio = Math.min(window.devicePixelRatio || 1, MAX_PIXEL_RATIO);
+    let [view_width, view_height] = view_size();
+
+    // ---- camera and controls, before anything needs a device --------------------------------
+    // Wired first on purpose: a browser without an adapter still gets a page that can be driven,
+    // and the failure it reports is the device's, not a cascade of undefined handlers.
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = CAMERA.near;
+    camera.far = CAMERA.far;
+    camera.fov = CAMERA.fov_degrees * DEG_TO_RAD;
+    camera.aspect = view_width / view_height;
+    camera.transform.setTranslation(CAMERA.position[0], CAMERA.position[1], CAMERA.position[2]);
+    camera.transform.lookAt(CAMERA.target);
+    camera.transform.updateMatrix();
+
+    // document.body rather than the canvas: the controller starts a keyboard device, and only a
+    // focusable element receives key events
+    const controller = new OrbitalCameraController(camera, document.body);
+    controller.look(CAMERA.position, CAMERA.target);
+    controller.movement_speed_scale = 4;
+
+    /** @type {Renderer|null} the renderer once its device is up; null before, and on failure */
+    let renderer = null;
+
+    /** @type {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem|null} */
+    let system = null;
+
+    const world = await build_particle_scene();
+    const { scene, emitters } = world;
+
+    Object.assign(globalThis, { camera, controller, scene, emitters, world });
+
+    /**
+     * Where the camera is and what it orbits, as plain numbers: enough to put another instance of
+     * this page in exactly the same view.
+     *
+     * @returns {{position: number[], target: number[], fov_degrees: number}}
+     */
+    globalThis.camera_state = () => {
+        const p = camera.transform;
+        const t = controller.target;
+        const round = v => Math.round(v * 1000) / 1000;
+
+        return {
+            position: [round(p.translation_x), round(p.translation_y), round(p.translation_z)],
+            target: [round(t.x), round(t.y), round(t.z)],
+            fov_degrees: round(camera.fov / DEG_TO_RAD),
+        };
+    };
+
+    /**
+     * Put the camera where a {@link camera_state} says.
+     *
+     * @param {{position: number[], target: number[], fov_degrees?: number}|string} state
+     */
+    globalThis.apply_camera = state => {
+        const parsed = typeof state === "string" ? JSON.parse(state) : state;
+
+        if (parsed.fov_degrees !== undefined) {
+            camera.fov = parsed.fov_degrees * DEG_TO_RAD;
+        }
+
+        controller.look(
+            new Vector3(parsed.position[0], parsed.position[1], parsed.position[2]),
+            new Vector3(parsed.target[0], parsed.target[1], parsed.target[2])
+        );
+    };
+
+    function apply_settings() {
+        if (renderer === null) {
+            return;
+        }
+
+        renderer.feature_particles_enabled = element("particles").checked;
+        renderer.transparency_mode = element("transparency").value === "MBOIT"
+            ? ShadeTransparencyMode.MBOIT
+            : ShadeTransparencyMode.AVBOIT;
+        renderer.feature_taa_enabled = element("taa").checked;
+    }
+
+    element("particles").addEventListener("change", apply_settings);
+    element("transparency").addEventListener("change", apply_settings);
+    element("taa").addEventListener("change", apply_settings);
+
+    element("burst").addEventListener("click", () => {
+        /*
+         The emitter has a row from the moment configure_particles registered it, and none before
+         — `spawn` refuses an emitter it does not hold. And a burst queued while the particles are
+         switched off is never drained: the ring only empties inside a simulated frame, so the
+         clicks would pile up and arrive together, seconds late, the moment they are switched back
+         on. Both are the same answer: the button does nothing.
+        */
+        if (system === null || !renderer.feature_particles_enabled || system.registry.context(emitters.sparks) === undefined) {
+            return;
+        }
+
+        // The CPU's one way to ask for particles, and it is a facade over the GPU path: the count
+        // reaches a command buffer, a pass adds it to that emitter's pending spawns, and the same
+        // budget and INIT program serve it as serve the emitter's own rate.
+        system.spawn(emitters.sparks, BURST_COUNT);
+    });
+
+    document.body.focus();
+
+    // ---- the device, last --------------------------------------------------------------------
+
+    const context = canvas.getContext("webgpu");
+
+    if (context === null) {
+        return show_message(
+            "No WebGPU context.\n\nThis browser has no WebGPU, or the page is not a secure context "
+            + "— it has to be served over http://localhost rather than opened from file://."
+        );
+    }
+
+    const candidate = new Renderer();
+
+    try {
+        await candidate.initialize({ context, pixelRatio: pixel_ratio });
+    } catch (e) {
+        console.error(e);
+        return show_message("The device could not be acquired.\n\n" + e.message);
+    }
+
+    renderer = candidate;
+    globalThis.renderer = renderer;
+
+    renderer.resize(view_width, view_height);
+
+    // eye adaptation drifts for seconds after any change, which makes the picture hard to compare
+    renderer.feature_automatic_exposure_enabled = false;
+    renderer.exposure_compensation = 1.2;
+
+    system = configure_particles(renderer, world);
+    globalThis.particles = system;
+
+    apply_settings();
+
+    // the meshes are lit; without an environment they are lit by the sun alone
+    load_default_environment(scene).catch(e => console.warn("environment:", e.message));
+
+    // ---- frame loop --------------------------------------------------------------------------
+
+    const device = renderer.graphics.device;
+
+    let stats_pending = false;
+    let frame_index = 0;
+    let time = 0;
+
+    const frame_rate = new FrameRateMeter();
+
+    /**
+     * @param {number} raw_dt seconds — the frame's REAL length, unclamped
+     */
+    function frame(raw_dt) {
+        // The readout gets the real interval and the simulation gets a clamped
+        // one. Handing the clamp to both made the longest frames enter the
+        // average as if they were 50 ms, and an exponential mean of `1/dt` on
+        // top of that never read below 54 fps for a page running at 28.6.
+        frame_rate.add(raw_dt);
+
+        const dt = Math.min(raw_dt, MAX_SIMULATION_STEP);
+
+        time += dt;
+
+        const [width, height] = view_size();
+
+        if (width !== view_width || height !== view_height) {
+            view_width = width;
+            view_height = height;
+            camera.aspect = width / height;
+            renderer.resize(width, height);
+        }
+
+        animate_particle_scene(world, system, time);
+        controller.update();
+
+        renderer.render(camera, scene, dt);
+
+        frame_index++;
+
+        if (!stats_pending && frame_index % STATS_INTERVAL_FRAMES === 0) {
+            capture_stats();
+        }
+    }
+
+    /**
+     * Read the counts back to display them. The system does the copying and the decoding; the page
+     * only decides how often to ask and what to put on screen.
+     */
+    function capture_stats() {
+        stats_pending = true;
+
+        system.read_stats().then(stats => {
+            stats_pending = false;
+
+            globalThis.__stats = {
+                ...stats,
+                frame: frame_index,
+                fps: frame_rate.fps,
+                frame_ms: frame_rate.mean_ms,
+                // Counted rather than averaged in: a page can run at 60 and
+                // still stall three times a second, and the average alone
+                // cannot say which of the two it is doing.
+                hitches: frame_rate.hitches,
+            };
+            write_hud(globalThis.__stats);
+        }).catch(e => {
+            stats_pending = false;
+
+            // A rejection that only cleared the flag left the last good counts
+            // on screen — and in `__stats`, which is what a headless session
+            // reads — for ever, with a `frame:` claiming they were current.
+            console.error(e);
+
+            globalThis.__stats = particle_stats_after_readback_failure(
+                globalThis.__stats, frame_index, e
+            );
+
+            mark_particle_stats_stale(element, HUD_STAT_IDS);
+        });
+    }
+
+    /** @type {(() => void)|null} */
+    let stop_loop = null;
+
+    /**
+     * One frame, with the loop stopped on the first failure.
+     *
+     * A lost device makes `render` throw, and the frame loop re-arms itself before it calls back —
+     * so without this the page would throw once per frame, for ever, with the first and most
+     * informative failure scrolled far out of reach.
+     *
+     * @param {number} dt
+     */
+    function guarded_frame(dt) {
+        try {
+            frame(dt);
+        } catch (e) {
+            stop_loop?.();
+            console.error(e);
+            show_message("The frame failed and the loop has stopped.\n\n" + e.message);
+        }
+    }
+
+    device.lost?.then(info => {
+        stop_loop?.();
+        show_message("The GPU device was lost.\n\n" + (info?.message ?? ""));
+    });
+
+    if (new URLSearchParams(location.search).has("debug")) {
+        // Drive frames by hand when the tab is hidden (rAF suspended) — headless verification.
+        // Nothing is scheduled: a stray rAF frame interleaved with __step would make the count the
+        // caller asked for and the count that ran two different numbers.
+        globalThis.__step = (n = 1, dt = 1 / 60) => {
+            for (let i = 0; i < n; i++) {
+                guarded_frame(dt);
+            }
+            return frame_index;
+        };
+        return;
+    }
+
+    // Unclamped: `frame` clamps what it steps the simulation by and meters
+    // what actually happened.
+    stop_loop = create_frame_loop(dt => guarded_frame(dt));
+}
+
+/** Push one stats snapshot into the overlay. Absent elements are simply skipped. */
+function write_hud({ fps, alive, dead, sim_workgroups, sim_padded }) {
+    const put = (id, value) => {
+        const node = element(id);
+        if (node !== null) {
+            node.textContent = value;
+        }
+    };
+
+    put("stat-fps", fps.toFixed(0));
+    put("stat-alive", alive.toLocaleString());
+    put("stat-dead", dead.toLocaleString());
+    // Padding rounds each program's run up to a whole workgroup, so this is >= alive; the gap is
+    // what wave-coherence costs in lanes.
+    put("stat-sim-lanes", sim_padded.toLocaleString());
+    put("stat-dispatch", sim_workgroups.toLocaleString());
+}
+
+function show_message(text) {
+    const node = element("message");
+
+    if (node !== null) {
+        node.textContent = text;
+    }
+}
+
+main().catch(e => {
+    console.error(e);
+    show_message("The particle playground failed to start — see the console.\n\n" + e.message);
+});