@woosh/meep-engine 3.18.0 → 3.19.0

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

@@ -0,0 +1,203 @@
+# Bonfire — GPU particles as ECS entities
+
+A moonlit fire pit, and the demonstrator for the ECS particle API. Everything in the set is an
+entity carrying a `Transform64` and one more component — the ground and the logs a `ShadedGeometry`,
+the moon and the firelight a `Light`, and the flame, smoke, embers and soot a **`ParticleEffect`**.
+Four systems observe those pairs and put rows into one `Scene`. The page owns no scene graph, no
+frame graph, no pass and no emitter object.
+
+Spawning a fire is therefore this, and nothing else:
+
+```js
+new Entity()
+    .add(new Transform64())
+    .add(ParticleEffect.from({ ...create_particle_effect({ layout, init, update }), spawn_rate: 560 }))
+    .build(dataset);
+```
+
+with `entityManager.addSystem(new GPUParticleEmitterSystem(graphics, scene, assetManager))` once, at
+boot. Move the entity and the fire moves; destroy it and the fire goes out. That is the point of the
+page: an effect is placed, moved, saved and destroyed by the same machinery as everything else, and
+`../particle_system/` next door is what it used to take — emitters built as scene nodes and added to
+a `Scene` by hand.
+
+## Running it
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+then open <http://localhost:5173/src/shade/playground/particle_ecs/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.
+
+**It needs `subgroups` and immediate data**, both of which the renderer requires of any device it
+accepts. 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.
+
+## What is on screen
+
+| entity | component | what it is there to show |
+|---|---|---|
+| flame | `ParticleEffect` | additive billboards, short-lived, stirred by noise and pinched inward so the column narrows |
+| smoke | `ParticleEffect` | alpha, soft-depth, expanding, firelit at the base and moonlit above it |
+| embers | `ParticleEffect` | small additive motes, buoyant then falling, flickering on their own clock |
+| soot | `ParticleEffect` | dark tumbling flakes that ride the plume and fall back through the firelight |
+| ground, logs, stones | `ShadedGeometry` | something for the fire to light, and for the smoke to fade against |
+| moon | `Light` (directional) | the cool half of the lighting, aimed at the moon in the environment map |
+| firelight | `Light` (point) | the warm half, flickered every frame by writing the component |
+
+The sky is a generated octahedral environment map (`moonlit_environment.js`) and the four sprites are
+generated PNGs (`bonfire_sprites.js`), so a fresh checkout with no `test_assets/` looks exactly like
+everybody else's. The four effects are saved documents under `effects/` — the editor opens them, and
+what it writes is what the page reads.
+
+### The two controls, and why they are the whole API
+
+- **The checkboxes** write `effect.emitting`. No system call, no node, and nothing to remember the
+  rate with — `emitting` gates `spawn_rate` without clearing it, and the system's next comparison
+  finds the change. Particles already alive burn out on their own, which is what putting a fire out
+  looks like.
+- **"Stoke the fire"** calls `particles.burst(entity, count)`. The request is queued and handed over
+  after the next frame's membership sweep, so it works before the first frame has run, and it goes
+  down the same GPU spawn path the continuous rate does.
+
+### Editing an effect while it burns
+
+<kbd>E</kbd> switches between looking at the fire and editing it. The editor takes the **whole
+window** — the graph, the instructions it compiles to, the emitter settings and a CPU preview, over
+the effect the selector names — and <kbd>E</kbd> again puts you back in the scene. Not a panel with a
+share of the screen: a node graph wants every pixel it can get, and so does the fire.
+
+Nothing is drawn while it is up. The editor covers the window, so a frame underneath it is a whole
+scene — the transparency pipeline, the particle passes, the resolve — composited behind an opaque
+panel and thrown away. Measured at 1075x1216, the ten-a-second trickle this replaces cost 3.5 ms of
+CPU to encode and about 21 ms from submission to completion, each. The machine goes to the graph
+editor, which is the thing you are actually looking at.
+
+An edit still reaches the GPU; it waits for the way back. `GPUParticleEmitterSystem` publishes the
+emitter table from `prepare` at FrameStart rather than from its tick, and that is idempotent by
+design — a frame must not depend on a simulation tick having preceded it — so the first frame after
+<kbd>Esc</kbd> carries everything you changed. What you give up is that the fire no longer advances
+behind the editor: the simulation is GPU work, so you come back to the instant you left rather than
+a few seconds on. An edit kills and restarts the effect anyway, which is where that would otherwise
+have shown.
+
+Change anything and the fire changes. What happens is worth knowing, because it is the reason a live
+edit is safe: the document recompiles and the entity's `ParticleEffect` component is **removed and
+added back**, not mutated. An edit can change the attribute layout, and a layout change repoints
+every word of a particle record — replacing the component retires the emitter's table row and takes
+its generation with it, so the particles running the old program are killed rather than reinterpreted
+under the new one. The effect restarts; for a fire that is what you wanted to see anyway. An effect
+that does not compile leaves the previous one burning and says so in the toolbar.
+
+**The round trip is the point.** Each effect *is* a saved document — `effects/flame.json` and its
+three siblings, which is what `bonfire_effects.js` loads. Press **Download**, drop the file over the
+one it came from, reload, and the page is running what you edited. There is no porting step and no
+authoring code to keep in step, because the file the editor writes is the file the page reads.
+**Import…** does the same without the reload, for trying a file out.
+
+Two things to know before editing one:
+
+- **One store per attribute per phase.** Every store runs and nothing orders them, so a second store
+  does not refine the first, it replaces it. That is how the smoke's drag silently ate its own
+  velocity integration — the picture only looked slightly wrong — until the editor's validator was
+  pointed at it. The graph editor calls it an error and `bonfire.spec.js` pins that none of the four
+  has one; nothing on the runtime path checks.
+- **The register budget is shared.** See below.
+
+## What to look at
+
+- **The smoke fades where it meets the ground and the logs** rather than showing the hard line a
+  camera-facing quad cuts into a surface. That is `soft_depth`, sampling the same depth buffer the
+  AVBOIT draw depth-tests against.
+- **The flame does not darken what is behind it.** Additive emitters write the emission accumulator,
+  which the resolve adds outside the coverage normalization — so the fire lights the frame instead of
+  taking coverage from it. The smoke, which is matter, does cover.
+- **The soot flakes cross in front of the flame and are lit by nothing**, and still read, because
+  they are dark against something bright. That is the cheapest depth cue in the set.
+- **Orbit around it.** The particles and the transparent surfaces composite against each other with
+  no order between them — both write extinction into one voxel volume and both resolve out of the
+  same accumulators. Switch the renderer to MBOIT and the particles vanish while everything else
+  stays: MBOIT is the legacy path and has no particle channel.
+
+### Profiling
+
+<kbd>T</kbd> starts a GPU capture, <kbd>T</kbd> again stops it and saves an `.sgpt`. The status line
+bottom-right says what it is doing and what the file was called; the console repeats the name, because
+a browser that declines the save says nothing about which capture it declined.
+
+Worth having on this page in particular: four distinct compiled programs means the simulate pass runs
+four coherence buckets, and what that costs relative to the emit, the bounds measurement and the three
+AVBOIT side-channel passes is not something anybody can guess. The capture's note carries which
+effects were emitting and how many particles were alive when it was taken.
+
+The wiring is `../profile_hotkey.js`, four lines at the bottom of `main.js`. The engine never
+constructs a `GPUProfileSession` — `Renderer.profile_session` is a nullable field and the null checks
+around it are the whole integration, which is what keeps the profiler out of a bundle that does not
+ask for it.
+
+## What it deliberately does not do
+
+- **No emitter opts into `EMITTER_FLAG.LIGHTING`.** The shipped hook is
+  `chunk_particle_lighting_unlit`, a pass-through, so the flag would cost a bit in a record and
+  change no pixel. The smoke and the soot are *painted* lit instead: their gradients carry the fire's
+  warmth low down and the moon's blue higher up, over the particle's own age. When a lit hook lands,
+  those gradients are the thing to reconsider.
+- **No emitter opts into culling.** One fire, always on screen; the frustum test in the tick pass
+  would never be taken. The measured bounds are still published every frame and still read by the
+  occupancy pass.
+- **No flipbooks.** Every sprite here is a single frame. `../particle_system/` has the flipbook path.
+
+## Verifying it
+
+```bash
+npx vitest run src/shade/playground/particle_ecs
+```
+
+`bonfire_effects.js`, `bonfire_world.js` and `moonlit_environment.js` have every reference to the
+page removed, so the spec opens the real documents, compiles them, and builds the real world with no
+device:
+
+- every saved document opens, compiles, and carries no diagnostic the editor would show — which is
+  the duplicate-store check above, pinned against the data rather than against the detector,
+- every effect's compiled program fits `PARTICLE_VM_FAST_REGISTER_SLOTS`. That is a **shared**
+  budget, and the reason it is a test rather than a comment: one program needing more than the
+  register file holds swaps emit and simulate for storage-backed variants *for the whole system*, so
+  an effect that grows past it does not slow itself down, it slows down every effect in the scene,
+- the render channels resolve to attributes that exist, and the blend modes are what each effect is,
+- every entity built carries a `Transform64` and exactly one more component,
+- the sky averages a hundredth of daylight and its brightest texel is where `MOON_DIRECTION` points,
+  so the shadows on the ground fall away from the moon that is actually in the map.
+
+What a particle *frame* encodes is not this page's business: that is pinned next to the code, against
+`SoftwareGPUDevice`, in `renderer/particles/graph_particles.spec.js` (the simulation, pass by pass)
+and `graph_particles_avboit.spec.js` (the three side-channel passes). The ECS half —
+membership, placement, the field comparison, the atlas — is pinned in
+`engine/graphics3/GPUParticleEmitterSystem.spec.js`.
+
+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, and
+`camera_state()` / `apply_camera(...)` copy a view between sessions. `globalThis` also carries
+`graphics`, `scene`, `dataset`, `entities`, `particles` and `world`, which is enough to drive the
+whole ECS from a console or a CDP session.
+
+## Cost
+
+About 1,600 live particles at the default rates, four distinct compiled programs, and a frame that is
+GPU-driven end to end: the host walks no emitters and counts no particles. The emitter tick pass
+integrates every 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 one thing
+the CPU asks for is the burst button, and it asks through the same path.
+
+The four programs are around 620 VM instructions each in UPDATE, most of which is the three
+`simplex3` samples the turbulence is made of. That is deliberately not the library's `curl3`, which
+is twelve of them for a divergence-free field: over a metre of flame nobody can tell, and the four
+effects share the register budget above — the editor's toolbar reports both numbers after every
+recompile, which is the cheapest way to notice an edit that has gone past them.

package/src/shade/playground/particle_ecs/bonfire_editor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @typedef {object} EffectEditorHandle
+ * @property {function(): boolean} is_open
+ * @property {function(): void} toggle
+ * @property {function(string): void} select which effect the editor shows
+ * @property {function(): void} dispose
+ */
+/**
+ * @param {object} params
+ * @param {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} params.dataset
+ * @param {import("./bonfire_world.js").BonfireWorld} params.world
+ * @param {Object<string, string|null>} params.sprites image URL per effect name
+ * @param {HTMLElement} params.host the panel the editor is mounted into; shown and hidden by this
+ * @param {HTMLSelectElement} params.selector which effect is being edited
+ * @param {HTMLElement} params.status one line about the last compile
+ * @param {HTMLElement} params.mount where the editor view's element goes, inside `host`
+ * @returns {EffectEditorHandle}
+ */
+export function install_effect_editor({ dataset, world, sprites, host, selector, status, mount }: {
+    dataset: import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset;
+    world: import("./bonfire_world.js").BonfireWorld;
+    sprites: {
+        [x: string]: string | null;
+    };
+    host: HTMLElement;
+    selector: HTMLSelectElement;
+    status: HTMLElement;
+    mount: HTMLElement;
+}): EffectEditorHandle;
+export type EffectEditorHandle = {
+    is_open: () => boolean;
+    toggle: () => void;
+    /**
+     * which effect the editor shows
+     */
+    select: (arg0: string) => void;
+    dispose: () => void;
+};
+//# sourceMappingURL=bonfire_editor.d.ts.map

package/src/shade/playground/particle_ecs/bonfire_editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bonfire_editor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_ecs/bonfire_editor.js"],"names":[],"mappings":"AA0CA;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH;IATkG,OAAO,EAA9F,OAAO,+CAA+C,EAAE,sBAAsB;IAC5B,KAAK,EAAvD,OAAO,oBAAoB,EAAE,YAAY;IACL,OAAO;YAApC,MAAM,GAAE,MAAM,GAAC,IAAI;;IACN,IAAI,EAAxB,WAAW;IACe,QAAQ,EAAlC,iBAAiB;IACG,MAAM,EAA1B,WAAW;IACS,KAAK,EAAzB,WAAW;IACT,kBAAkB,CA+P9B;;mBA9QyB,OAAO;kBACP,IAAI;;;;mBACP,MAAM,KAAG,IAAI;mBACV,IAAI"}

package/src/shade/playground/particle_ecs/bonfire_editor.js

@@ -0,0 +1,315 @@
+import { ActionProcessor } from "../../../core/process/undo/ActionProcessor.js";
+import { ParticleEffect } from "../../../engine/graphics/ecs/particles/ParticleEffect.js";
+import {
+    ParticleEffectEditorView
+} from "../../../../editor/view/particles/effect/ParticleEffectEditorView.js";
+import {
+    BONFIRE_EFFECT_NAMES,
+    bonfire_effect_component,
+    bonfire_effect_document,
+    particle_node_visuals,
+} from "./bonfire_effects.js";
+
+/**
+ * The particle editor, over the fire that is burning.
+ *
+ * Open it, pick an effect, change something, and the fire changes — while it burns, in the scene it
+ * belongs to, lit by the light it is lighting. That is the point: an effect is a thing you judge by
+ * looking at it in place, and an editor on a page of its own can only ever show you a preview of it
+ * against nothing.
+ *
+ * ## How an edit reaches the GPU
+ *
+ * The document recompiles and the entity's component is **replaced** — removed and added back — not
+ * mutated. That is deliberate and it is the reason a live edit is safe at all: an edit can change the
+ * attribute layout, and a layout change repoints every word of a particle record. Replacing the
+ * component retires the emitter's table row and takes its generation with it, so the particles that
+ * were running the old program are killed on the next simulate rather than being reinterpreted
+ * under the new one. Mutating `effect.program` in place would keep the row, keep the particles, and
+ * read their records through a layout that no longer describes them.
+ *
+ * The cost is that the effect restarts. For a fire that is what you want to see anyway.
+ *
+ * ## What it does not do
+ *
+ * It does not write files. A downloaded document is the whole effect — drop it over
+ * `effects/<name>.json` and the page loads it next time, with no porting step, because the file the
+ * editor writes is the file the page reads.
+ */
+
+/** How long the editor waits after the last keystroke before recompiling. Milliseconds. */
+const APPLY_DELAY_MS = 250;
+
+/**
+ * @typedef {object} EffectEditorHandle
+ * @property {function(): boolean} is_open
+ * @property {function(): void} toggle
+ * @property {function(string): void} select which effect the editor shows
+ * @property {function(): void} dispose
+ */
+
+/**
+ * @param {object} params
+ * @param {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} params.dataset
+ * @param {import("./bonfire_world.js").BonfireWorld} params.world
+ * @param {Object<string, string|null>} params.sprites image URL per effect name
+ * @param {HTMLElement} params.host the panel the editor is mounted into; shown and hidden by this
+ * @param {HTMLSelectElement} params.selector which effect is being edited
+ * @param {HTMLElement} params.status one line about the last compile
+ * @param {HTMLElement} params.mount where the editor view's element goes, inside `host`
+ * @returns {EffectEditorHandle}
+ */
+export function install_effect_editor({ dataset, world, sprites, host, selector, status, mount }) {
+    /**
+     * The open documents, by effect name. Kept across close/open, because closing the editor to look
+     * at the fire and losing the edit would make the editor useless for the one thing it is for.
+     *
+     * @type {Map<string, import("../../../../editor/particles/effect/ParticleEffectDocument.js").ParticleEffectDocument>}
+     */
+    const documents = new Map();
+
+    /** @type {Map<string, function():void>} the change subscription of each open document */
+    const subscriptions = new Map();
+
+    const entities = {
+        flame: world.flame,
+        smoke: world.smoke,
+        embers: world.embers,
+        soot: world.soot,
+    };
+
+    const actionProcessor = new ActionProcessor({});
+
+    /** @type {ParticleEffectEditorView|null} */
+    let view = null;
+
+    /** @type {string} */
+    let active = BONFIRE_EFFECT_NAMES[0];
+
+    /** @type {number} */
+    let apply_timer = 0;
+
+    /** @type {boolean} */
+    let open = false;
+
+    for (const name of BONFIRE_EFFECT_NAMES) {
+        const option = document.createElement("option");
+
+        option.value = name;
+        option.textContent = name;
+
+        selector.appendChild(option);
+    }
+
+    /**
+     * @param {string} name
+     * @returns {import("../../../../editor/particles/effect/ParticleEffectDocument.js").ParticleEffectDocument}
+     */
+    function open_document(name) {
+        const existing = documents.get(name);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        const opened = bonfire_effect_document(name);
+
+        documents.set(name, opened);
+
+        const on_changed = () => {
+            clearTimeout(apply_timer);
+
+            // Debounced, because a change is announced per keystroke and per dragged node, and a
+            // recompile is a graph lowering plus the optimizer.
+            apply_timer = setTimeout(() => apply(name), APPLY_DELAY_MS);
+        };
+
+        opened.on.changed.add(on_changed);
+        subscriptions.set(name, () => opened.on.changed.remove(on_changed));
+
+        return opened;
+    }
+
+    /**
+     * Recompile one effect and put the result on its entity.
+     *
+     * @param {string} name
+     */
+    function apply(name) {
+        const source = documents.get(name);
+
+        if (source === undefined) {
+            return;
+        }
+
+        const component = bonfire_effect_component(source, sprites[name]);
+        const index = BONFIRE_EFFECT_NAMES.indexOf(name);
+        const previous = world.effects[index];
+
+        if (component === null) {
+            const errors = source.compile().diagnostics.filter(entry => entry.severity === "error");
+
+            set_status(
+                `${name} does not compile — ${errors.length} error${errors.length === 1 ? "" : "s"}`
+                + `, the previous one is still burning`,
+                true
+            );
+
+            return;
+        }
+
+        // Whether the effect is currently switched off is the page's state rather than the
+        // document's, so it survives the swap: unticking a box and then editing the graph should not
+        // relight it.
+        component.emitting = previous.emitting;
+
+        const entity = entities[name];
+
+        /*
+         Removed and added rather than assigned: see the note at the top. The system's `unlink` takes
+         the emitter node out of the scene, which retires its table row and kills the particles that
+         were running the old program; `link` builds a new one on the next comparison.
+        */
+        dataset.removeComponentFromEntity(entity, ParticleEffect);
+        dataset.addComponentToEntity(entity, component);
+
+        world.effects[index] = component;
+
+        const warnings = source.compile().diagnostics.length;
+
+        set_status(
+            `${name} applied — ${component.program.init.length / 4 | 0} + `
+            + `${component.program.update.length / 4 | 0} instructions, `
+            + `${component.program.register_count} registers`
+            + (warnings > 0 ? `, ${warnings} diagnostic${warnings === 1 ? "" : "s"}` : "")
+        );
+    }
+
+    /**
+     * @param {string} text
+     * @param {boolean} [failed]
+     */
+    function set_status(text, failed = false) {
+        status.textContent = text;
+        status.className = failed ? "failed" : "";
+    }
+
+    /**
+     * Mount the editor over the document for `name`, replacing whatever was mounted.
+     *
+     * A view per document rather than one view re-pointed: `ParticleEffectEditorView` takes its
+     * effect at construction and every panel inside it has subscribed to that one.
+     *
+     * @param {string} name
+     */
+    function mount_view(name) {
+        if (view !== null) {
+            view.unlink();
+            view.el.remove();
+            view = null;
+        }
+
+        view = new ParticleEffectEditorView({ effect: open_document(name), actionProcessor });
+
+        mount.appendChild(view.el);
+
+        view.link();
+
+        resize();
+    }
+
+    function resize() {
+        if (view === null) {
+            return;
+        }
+
+        view.size.set(mount.clientWidth, mount.clientHeight);
+    }
+
+    /**
+     * @param {string} name
+     */
+    function select(name) {
+        if (!BONFIRE_EFFECT_NAMES.includes(name)) {
+            return;
+        }
+
+        active = name;
+        selector.value = name;
+
+        if (open) {
+            mount_view(name);
+            set_status(`editing ${name}`);
+        }
+    }
+
+    function show() {
+        open = true;
+        host.hidden = false;
+
+        mount_view(active);
+
+        set_status(`editing ${active}`);
+    }
+
+    function hide() {
+        open = false;
+        host.hidden = true;
+
+        if (view !== null) {
+            view.unlink();
+            view.el.remove();
+            view = null;
+        }
+    }
+
+    function toggle() {
+        if (open) {
+            hide();
+        } else {
+            show();
+        }
+    }
+
+    selector.addEventListener("change", () => select(selector.value));
+
+    window.addEventListener("resize", resize);
+
+    return {
+        is_open: () => open,
+        toggle,
+        select,
+
+        /** The document currently being edited, for the page's download and import buttons. */
+        current: () => open_document(active),
+
+        /** @param {object} json */
+        import_json: json => {
+            const target = open_document(active);
+
+            target.fromJSON(json, particle_node_visuals());
+
+            // `fromJSON` batches, so the change lands as one — but the apply is debounced off it and
+            // a freshly imported effect should be on screen now rather than in a quarter second.
+            clearTimeout(apply_timer);
+            apply(active);
+
+            if (open) {
+                mount_view(active);
+            }
+        },
+
+        dispose: () => {
+            hide();
+
+            for (const unsubscribe of subscriptions.values()) {
+                unsubscribe();
+            }
+
+            subscriptions.clear();
+            documents.clear();
+
+            window.removeEventListener("resize", resize);
+        },
+    };
+}