@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/playground/particle_system/README.md

@@ -1,9 +1,18 @@
-# GPU particle system — playground
+# GPU particles, through AVBOIT — playground
 
-The whole GPU particle path running in a real scene: emitters, the VM, the alive/dead lists and the
-billboard renderer, driven end to end by the GPU with no renderer, no assets and no `Renderer`
-dependency. It moved here from `renderer/particles/prototypeParticleSystem.js`, which had no page to
-open it with.
+The GPU particle path where it belongs: inside the engine's own `Renderer`, drawn by the AVBOIT
+transparency pipeline as a side channel of the transparent meshes. The page owns a `Scene` and a
+camera and nothing else — no frame graph, no pass, no pipeline, no camera buffer and no depth
+texture. Two lines turn the particles on:
+
+```js
+renderer.transparency_mode = ShadeTransparencyMode.AVBOIT;
+renderer.feature_particles_enabled = true;
+```
+
+`particle_prototype.js` — the worked-example `fire_effect` / `smoke_effect` / `register_campfire` —
+lives here too, and is spec'd here rather than from the engine's own suite so that the dependency
+runs playground → renderer and never back.
 
 ## Running it
 
@@ -14,96 +23,117 @@ npm run dev --workspace @woosh/meep-engine
 then open <http://localhost:5173/src/shade/playground/particle_system/index.html>.
 
 It has to be `http://localhost` rather than `file://`: WebGPU needs a secure context, and module
-imports from `file://` are blocked by CORS anyway. The page imports nothing but meep's own relative
-ESM, so any static server rooted at the repo also serves it.
-
-**It needs `subgroups`**, and refuses to start without it. The simulate input list is bucketed by VM
-program so no wave spans two programs, and the bucket offsets come from `graph_prefix_scan_csdldf`,
-which is built on subgroup ops.
+imports from `file://` are blocked by CORS anyway.
 
-**It needs immediate data**, and refuses to start without it. Emit, simulate and build-indirect each
-carry their per-dispatch state (`u_dt`, `u_time`, `u_frame`, and for emit the request count and the
-pool capacity) as an immediate block rather than as a transient uniform buffer, so an adapter whose
-WGSL lacks the `immediate` address space cannot build any of the three. The refusal names the byte
-counts. Chrome/Edge 113+ with immediates; Claude Code's in-app browser pane is **not** one — it
-reports no adapter at all today, and no `immediate_address_space` in `wgslLanguageFeatures`.
+**It needs `subgroups` and immediate data**, both of which the renderer requires of any device it
+accepts — the prefix scans behind the spawn counts, the coherence bucketing and the scene hierarchy
+are built on subgroup ops, and every particle compute pass carries its per-dispatch state as an
+immediate block. Chrome/Edge 113+ with immediates; Claude Code's in-app browser pane is **not** one
+— it has reported no adapter at all since 2026-09-02, and no `immediate_address_space` in
+`wgslLanguageFeatures` before that.
 
 ## What is on screen
 
-Four emitters sharing one 32k pool, chosen so each renderer path is visible at once:
+A `Scene` with opaque geometry (a floor, a pillar, a block), **one transparent pane** across the
+middle of the set, a sunlight, the default environment, and five emitters sharing one pool:
 
 | emitter | blend | projection | what it is there to show |
 |---|---|---|---|
-| fire | additive | billboard | `fire_effect()` straight out of `particle_prototype.js`, at the foot of the pillar |
+| fire | additive | billboard | `fire_effect()` straight out of `particle_prototype.js` next door, at the foot of the pillar |
 | smoke | alpha | billboard, soft-depth | a rising column that fades where it meets the pillar rather than cutting into it |
 | sparks | additive | **stretched** | short-lived, gravity-fed, stretched along velocity — the one non-billboard projection |
-| dust | alpha | billboard, soft-depth | a wide slow drift, so the ground plane and the low wall both get a soft intersection |
+| dust | alpha | billboard, soft-depth | a wide slow drift, so the floor gets a soft intersection |
+| torch | additive | billboard | a child of a node that orbits — the emitter never moves, its parent does, and the GPU hierarchy pass composes the two |
+
+The torch is the point of the scene-node design. Its record holds a row of the scene's
+`transforms` table, not a matrix; the page writes its parent's translation once a frame the way it
+would for any node, and the emitter's world position comes out of the same hierarchy pass that
+places every mesh. An emitter parented to an animated joint works the same way, with nothing copied
+through the CPU.
 
 Four distinct compiled programs, so this is also where the simulation-order bucketing has something
 to do: without it a simulate wave holds fire, smoke, spark and dust particles side by side, each
-wanting different opcodes out of the interpreter's `switch` and different registers out of its
-dynamically-indexed file. Nothing on screen changes when it is on — it is a coherence change, not a
-visual one — which is why it is pinned by specs rather than by looking.
+wanting different opcodes out of the interpreter's `switch`. Nothing on screen changes when it is on
+— it is a coherence change, not a visual one — which is why it is pinned by specs rather than by
+looking.
+
+## The property the page exists to demonstrate
 
-Ground plane and three boxes are drawn first into a reverse-Z `depth32float` buffer. The billboard
-pass loads that colour target and depth-tests against the same buffer read-only, so particles are
-**occluded** by the boxes and the soft-depth emitters sample the depth they were occluded by.
+**Particles and transparent surfaces composite against each other with no order between them.**
+Orbit around the pane. From in front, the particles behind it are dimmed by it; from behind, the
+pane is dimmed by the smoke in front of it — and neither was sorted against the other, because both
+wrote their extinction into the same voxel volume and both were resolved out of the same
+accumulators. That is what a side channel buys, and what a blended pass bolted on after the
+transparency pipeline cannot do at any price.
 
-Things worth looking at:
+Two more things are visible from the same seat:
 
-- particles disappearing behind the pillar as the camera orbits — that is the depth test,
-- smoke and dust softening where they touch a surface instead of showing a hard intersection line —
-  that is `PARTICLE_FLAG_SOFT_DEPTH` and the reverse-Z linearisation,
+- **the additive emitters do not darken what is behind them.** Fire, sparks and the torch write the
+  emission accumulator, which the resolve adds outside the coverage normalization, so they light
+  the frame without taking coverage from it.
+- **switch the mode to MBOIT and the particles vanish while the pane stays.** MBOIT is the legacy
+  path and has no particle channel. The simulation keeps running — turn AVBOIT back on and the
+  effects are where they would have been, not restarted — which is the honest way to see which
+  pipeline the particles now live in.
+
+Also worth looking at, from the path itself:
+
+- particles disappearing behind the pillar as the camera orbits — the depth test, read-only, on the
+  same buffer the soft fade samples,
+- smoke and dust softening where they touch a surface instead of showing a hard intersection line,
 - sparks leaning into their own velocity — `EMITTER_PROJECTION.STRETCHED`,
-- both blend modes in **one** draw with one pipeline: `particle_premultiply` picks per particle, so
-  there is no additive pass and no alpha pass.
+- the torch's trail following its carrier.
+
+The frame is GPU-driven end to end, spawning included. The host walks no emitters and counts no
+particles: the emitter tick pass integrates every emitter's rate on the GPU, a prefix scan of its
+counts sizes the emit dispatch, and `shader_particle_build_indirect` writes the simulate dispatch
+args and the draw args. The "Burst 4000 sparks" button is the one thing the CPU asks for, and it
+asks through the same path — a command list a pass adds to that emitter's pending spawns.
 
 The overlay shows fps and, every 30 frames, the alive count, the free-list length and the two
-indirect arg buffers. Those are read back **to look at**. Nothing on the CPU sizes a pass.
+indirect arg buffers. Those are read back **to look at**, on a command buffer of their own after the
+renderer's. Nothing on the CPU sizes a pass.
 
-## The property the page exists to demonstrate
+## Bounds spheres matter here
 
-The frame is GPU-driven end to end. `shader_particle_build_indirect` writes both the simulate
-dispatch args and the billboard draw args on the GPU; the next frame's simulate runs through
-`dispatchWorkgroupsIndirect` and this frame's draw through `drawIndirect`. The host's only sizing
-decision is how many *new* particles to spawn, which is a per-emitter rate times `dt` and has
-nothing to do with how many are already alive.
+Every emitter carries one, and under AVBOIT it is not only the culling test it used to be: the
+occupancy pass marks the depth slices an emitter may occlude in from that sphere, once per emitter
+rather than once per particle. A sphere that does not hold its effect leaves particles occluding at
+slightly the wrong depth. `PARTICLE_EMITTER_MOTION` in `particle_scene.js` is the motion each effect
+is built from, and `particle_scene.spec.js` checks the spheres against it.
 
-Sizing either from a CPU readback instead would be a correctness bug rather than a latency one: a
-stale count that is too small leaves the tail of the alive list unsimulated, so those slots are
-never freed, and one that is too large re-simulates entries past the end, pushing a dead slot onto
-the free list twice — it is then popped twice and two live particles share one record.
+They are sized to hold where the effect actually goes, not the last corner its jitter could reach:
+a sphere big enough for the worst case would mark most of the depth range and cost the adaptive
+slicing the very thing it is for.
 
 ## Verifying it
 
-`particle_scene.js` holds the scene with every reference to the page removed, so
-`particle_scene.spec.js` can encode the same frames against `SoftwareGPUDevice`:
-
 ```bash
-npx vitest run src/shade/playground/particle_system/particle_scene.spec.js
+npx vitest run src/shade/playground/particle_system
 ```
 
-That mock runs no shaders, so the spec asserts nothing about what a pass computed. What it does
-assert is that the frame is legal and wired the way the design requires — pass order and
-attachments, no frame reading the list it appends to, the immediate blocks written before every
-dispatch that declares them, simulate and the draw both taking their counts from the indirect
-buffers, and the two orderings staying in separate buffers: simulate reads the program-coherent
-list, the billboard draw reads the alive list. Any WebGPU validation failure anywhere in the frame arrives as an
-uncaptured error, which every test fails on.
+`particle_scene.js` holds the scene and the configuration with every reference to the page removed,
+so the spec builds the real scene — meshlets, materials, emitters — with no device, and checks what
+is the page's to get wrong: the emitters are the scene's nodes, the torch hangs off the carrier, the
+pane is transparent while the rest is opaque, the bounds spheres hold their effects, and
+`configure_particles` turns the feature on, selects AVBOIT and hands the system its sprite.
+
+What a particle *frame* encodes is not this page's business any more. It is pinned next to the code,
+against `SoftwareGPUDevice`, in `renderer/particles/graph_particles.spec.js` (the simulation, pass
+by pass, and every dispatch sized by GPU-written args) and `graph_particles_avboit.spec.js` (the
+three side-channel passes, their attachments and their indirect draws).
 
-The picture is the browser's job; the spec cannot see it.
+The picture is the browser's job; no spec here can see it.
 
 ### Stepping frames by hand
 
 Add `?debug` to the URL. `requestAnimationFrame` is then not used at all, and `window.__step(n)`
 runs exactly `n` frames and returns the frame counter — which is what makes the loop drivable in a
-hidden or headless tab, where rAF is suspended. `window.__stats` carries the last counters snapshot.
+hidden or headless tab, where rAF is suspended. `window.__stats` carries the last counters snapshot,
+and `camera_state()` / `apply_camera(...)` copy a view between sessions.
 
 ## What this page does not cover
 
-Depth sorting. `EMITTER_FLAG.SORT` and the bucketed depth sort in `particles/sort/` (histogram →
-csdldf scan → scatter) are not wired in here: the billboard pass draws the alive list directly, so
-alpha-blended emitters are in emission order rather than back-to-front. The two soft-depth emitters are faint and diffuse enough that it
-does not read as wrong, which is exactly why it should not be taken as evidence that sorting works.
-Lighting is the unlit hook, too — `chunk_particle_lighting_unlit`, not the shading-chunk-backed one
-the renderer feature swaps in.
+Lighting is the unlit hook — `chunk_particle_lighting_unlit`, not the shading-chunk-backed one a
+lit-emitter variant would swap in. No emitter opts into simulation culling, so the frustum test in
+the tick pass is never taken here; the bounds spheres are read by the occupancy pass all the same.

package/src/shade/playground/particle_system/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
 <head>
     <meta charset="utf-8">
-    <title>meep — GPU particle system</title>
+    <title>meep — GPU particles through AVBOIT</title>
     <style>
         :root {
             color-scheme: dark;
@@ -32,22 +32,25 @@
             height: 100%;
         }
 
-        #hud {
+        .panel {
             position: fixed;
-            top: 12px;
-            left: 12px;
-            min-width: 210px;
             padding: 10px 12px;
             border: 1px solid var(--line);
             border-radius: 8px;
             background: var(--panel);
             backdrop-filter: blur(6px);
+        }
+
+        #hud {
+            top: 12px;
+            left: 12px;
+            min-width: 210px;
             font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
             font-size: 12px;
             pointer-events: none;
         }
 
-        #hud h1 {
+        #hud h1, #controls h1 {
             font: inherit;
             font-weight: 600;
             margin: 0 0 6px;
@@ -59,16 +62,43 @@
         #hud div { display: flex; gap: 10px; justify-content: space-between; }
         #hud .key { color: var(--muted); }
 
+        #controls {
+            top: 12px;
+            right: 12px;
+            min-width: 230px;
+            font-size: 12.5px;
+        }
+
+        #controls h1 { font-family: ui-monospace, SFMono-Regular, Consolas, monospace; font-size: 12px; }
+
+        #controls label {
+            display: flex;
+            gap: 8px;
+            align-items: center;
+            justify-content: space-between;
+            padding: 3px 0;
+        }
+
+        #controls select { background: #14161a; color: var(--text); border: 1px solid var(--line); border-radius: 4px; padding: 2px 4px; }
+
+        #controls button {
+            width: 100%;
+            margin-top: 8px;
+            padding: 6px 10px;
+            background: #14161a;
+            color: var(--text);
+            border: 1px solid var(--line);
+            border-radius: 6px;
+            cursor: pointer;
+            font: inherit;
+        }
+
+        #controls button:hover { border-color: #3d4450; }
+
         #legend {
-            position: fixed;
             bottom: 12px;
             left: 12px;
-            max-width: 62ch;
-            padding: 10px 12px;
-            border: 1px solid var(--line);
-            border-radius: 8px;
-            background: var(--panel);
-            backdrop-filter: blur(6px);
+            max-width: 68ch;
             font-size: 12.5px;
             color: var(--muted);
             pointer-events: none;
@@ -95,11 +125,11 @@
         #message:not(:empty) { display: flex; }
     </style>
 </head>
-<body>
+<body tabindex="0">
 
 <canvas id="view"></canvas>
 
-<div id="hud">
+<div id="hud" class="panel">
     <h1>GPU particles</h1>
     <div><span class="key">fps</span><span id="stat-fps">—</span></div>
     <div><span class="key">alive</span><span id="stat-alive">—</span></div>
@@ -109,12 +139,28 @@
     <div><span class="key">sim workgroups</span><span id="stat-dispatch">—</span></div>
 </div>
 
-<div id="legend">
-    <p><b>Four emitters, one pool.</b> Additive fire at the pillar, an alpha soft-depth smoke column
-        above it, velocity-stretched sparks by the block, and a wide soft-depth dust drift.</p>
-    <p>Emit, simulate and the billboard draw are all GPU-sized — the simulate dispatch and the draw
-        read indirect args the build-indirect pass writes. The counters above are read back purely to
-        display; nothing on the CPU sizes a pass.</p>
+<div id="controls" class="panel">
+    <h1>renderer</h1>
+    <label><span>particles</span><input type="checkbox" id="particles" checked></label>
+    <label><span>transparency</span>
+        <select id="transparency">
+            <option value="AVBOIT" selected>AVBOIT (voxels)</option>
+            <option value="MBOIT">MBOIT (legacy)</option>
+        </select>
+    </label>
+    <label><span>TAA</span><input type="checkbox" id="taa" checked></label>
+    <button id="burst">Burst 4000 sparks</button>
+</div>
+
+<div id="legend" class="panel">
+    <p><b>Drawn by the engine's own Renderer.</b> Five emitters share one pool, and their quads go
+        through the AVBOIT transparency pipeline as a side channel — the same volume, the same
+        accumulators and the same resolve as the transparent pane in the middle of the set.</p>
+    <p>Orbit around the pane: it and the particles occlude each other correctly from either side,
+        with no sort between them. Switch to MBOIT and the particles disappear while the pane stays
+        — the legacy path has no particle channel, and they are still being simulated.</p>
+    <p>Emit, simulate and the draws are all GPU-sized. The counters above are read back purely to
+        display; nothing on the CPU sizes a pass. Drag to orbit, wheel to zoom, right-drag to pan.</p>
 </div>
 
 <div id="message"></div>