@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,216 @@
+# Particle effect editor — playground
+
+Both layers of the particle editor over one effect, with the effect running next to them.
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+then open <http://localhost:5173/src/shade/playground/particle_editor/index.html>.
+
+Unlike `../particle_system/`, this page needs **no WebGPU at all**: the preview runs the effect's
+compiled bytecode on the CPU through the reference VM. It works in any browser that can run modules,
+Claude Code's in-app pane included.
+
+## The two layers
+
+The engine compiles a particle effect from a node graph down to bytecode for a small VM, and this
+edits it at both altitudes.
+
+**Graph** is the authoring layer: two node graphs, one per lifecycle phase.
+
+- **INIT** runs once per particle, when it spawns. **UPDATE** runs once per frame per live particle.
+  Both are kept built, so switching between them does not lose a camera or a selection.
+- **Getting around**: drag with the **right** button — or the middle one — to pan, and the wheel
+  zooms about the cursor. Drag with the **left** button over open canvas and you pull a selection
+  box instead: it takes every node it touches and every wire it holds whole, `Shift` adds to what
+  was selected, `Ctrl` toggles what the box covers, and the box says which of the three it is
+  while you are still holding it. Which button began the press decides which gesture it is, and
+  how far it travelled decides whether it was a press or a drag — so a right press that stays put
+  is the menu below and one that moves is a pan, the way Unreal's Blueprint canvas arranges the
+  same three gestures.
+- **Right-click the canvas** to add a node. The library opens under the cursor with the caret
+  already in a search field and the first match already chosen: type a few letters, press Enter, and
+  the node lands at the point that was clicked with the defaults its type declares, so it compiles
+  the moment it arrives. Arrow keys move the choice; Escape closes. Nodes are listed and headed by
+  what they are called rather than by the mnemonic they compile as — "Divide", not `div` — each with
+  the glyph its type carries; both are searched, so looking for either finds it.
+- **Copy, paste, duplicate.** `Ctrl+C` takes a copy of the selected nodes and of every wire they hold
+  whole — a wire with one end outside the selection is not brought along, because the node it reached
+  is not part of what was copied. `Ctrl+V` puts it in the middle of what you are looking at, keeping
+  the arrangement it was copied in; a repeat paste steps aside so copies do not hide each other.
+  `Ctrl+D` puts a second of the selection beside it and leaves the clipboard alone. Each is one step
+  on the undo timeline, and what lands is what is selected afterwards, ready to be dragged where it
+  is wanted. One clipboard serves both phases and every group body, so a copy taken in INIT pastes in
+  UPDATE. It is the editor's own clipboard rather than the system one: what it holds is node types,
+  which only mean anything to a canvas that shares the library.
+- **An input holds one wire.** Drop a second one on it and it replaces the first, in one step on the
+  undo timeline — the editor cannot be made to put two sources on an input. Drag *out* of an input
+  that already has one and you are holding that wire rather than making another: let it go on
+  another input to move it there, on the port it came from to leave it alone, and on open canvas to
+  take it off.
+- **Drop a wire on empty canvas** and the same menu opens, narrowed to the types that have a port
+  which could take it — the ones with an input, when the wire came out of an output — and picking one
+  wires it up as it arrives. The node and the wire are one step on the undo timeline, because they
+  were one gesture.
+- Some nodes are **groups**: a node made of other nodes, drawn with a doubled left edge. Double-click
+  one to open it — the canvas shows the group's own graph and the toolbar grows a breadcrumb back
+  out — and groups nest, so the breadcrumb does. The ones shipped with the editor are locked: one
+  body is shared by every instance in every effect, so they open to be read rather than changed.
+  Groups are flattened away before anything is compiled, so a group costs exactly what its contents
+  cost.
+- **Make one**: select some nodes and press `Ctrl+G`, or the **Group** button. The wires that crossed
+  the selection become the group's ports, named after what they feed and typed by what the graph
+  resolved them to, and the group lands where the selection was with everything re-wired around it —
+  one step on the undo timeline. A group an author makes belongs to the effect: it is saved with it,
+  it is offered in the add-node menu like any other type, and it is unlocked, so opening it and
+  renaming it in the breadcrumb are both allowed. `Ctrl+Shift+G` puts one back.
+  A selection that something *outside* it runs in the middle of cannot become one node — the group
+  would have to run both before and after that thing — and the **Group** button says so rather than
+  letting you find out.
+- A map of the whole graph sits in the bottom-right corner, with a frame around the part on screen.
+  Click or drag it to go somewhere; it draws the wires along the routes they actually take, so the
+  map and the canvas are the same picture. The `-` in its corner folds it away to a button, and both
+  phases fold together.
+- Node parameters are edited in the node: four fields for a vector, a swatch and an alpha field for
+  a colour, a picker for an ISA enum, a picker of the effect's own attributes for an attribute
+  reference, `xyzw` for a swizzle.
+- Two of them are **ramps**, edited as a picture. An **RGBA Gradient** (and an RGB one) is a strip of
+  the colour it produces with its stops underneath: drag a stop, click the lane to add one — in the
+  colour the gradient already is there, so adding never changes anything — and middle-click to remove.
+  A **Curve** is the unit square with its keys in it, and the picker under it decides the selected
+  key's tangents. Neither is sampled from a table at runtime: both are written out into the program as
+  arithmetic, which is what the **Code** tab shows. `Curve Table`, which *is* the table, is the other
+  node — it takes a row handle rather than a curve.
+- The strip along the bottom lists every problem with the effect, from **both** phases, loudest
+  first. Click one to jump to the phase it is in and select the node; the node is outlined in the
+  graph too.
+- **A node nothing reads is not a problem.** Only what reaches a sink is compiled, so half-built work
+  sitting next to a working graph cannot break it: such a node is dimmed, noted once at the bottom of
+  the strip, and nothing else found against it — an unbound input, a mistyped value — is reported at
+  all. The strip still says there are no problems, because there are none.
+
+**Code** is the same effect as instructions.
+
+- While the graph is authoritative this is that graph's lowering, read-only, and it re-lowers as the
+  graph changes. Register allocation, constant interning, the order the compiler chose — all of it
+  visible next to the graph that produced it.
+- **Lower to assembly** hands authority to the text. From there the graph is still on screen and
+  still editable, but the program is what is written here. That is the only way to reach an encoding
+  the node library has no node for.
+- Errors are listed with the line they are on, and that line is marked in the gutter.
+
+The syntax is documented at the top of `renderer/particles/isa/particle_assembly.js`.
+
+## The preview
+
+The right-hand panel runs the effect and draws one soft sprite per particle. It is the same bytecode
+a device would run — `execute_particle_vm` is the executor the WGSL interpreter is written to match,
+opcode for opcode and RNG bit for RNG bit — so what you are watching is the simulation, not an
+impression of it.
+
+What it is **not** is the renderer. There is no depth buffer, no lighting, no atlas, no flipbook and
+no transparency pipeline; a billboard is a radial gradient, and order comes from a painter's sort
+rather than from AVBOIT's voxel volume. For the real thing, `../particle_system/` draws the same kind
+of effect through the engine's own `Renderer`. What this preview does show honestly is everything the
+*effect* decides: where particles go, how long they live, how big they are, what colour they are,
+what blend mode they use, and how many are alive at once.
+
+Drag to orbit, wheel to dolly. `Pause` freezes the simulation without freezing the camera; `Restart`
+drops every particle and starts the effect over.
+
+**Editing a broken effect keeps the last program that compiled running**, and the overlay says so. A
+graph is invalid for most of the time anyone spends wiring one, and a preview that blanked out would
+be gone exactly when it is wanted.
+
+## What to try
+
+- Change a `const` node's value in the graph and watch the plume change while you are still typing.
+- Switch to **Code** and read what that graph became. Change the same number there instead — after
+  `Lower to assembly` — and watch the same thing happen from the other end.
+- Break the assembly (misspell a mnemonic). The line is marked, the panel says `does not assemble`,
+  and the preview carries on with the last good program.
+- Add an attribute in the inspector, then bind a render channel to it. Remove one that a channel was
+  bound to: the channel unbinds, and every node that named it is reported against the node.
+- Drag the wire out of a bound input and drop it on the input below. It moves, rather than being
+  copied — and `Ctrl+Z` puts it back in one go. Drag it out again and let go over open canvas: it is
+  gone, and the menu opens offering what could take the value it was carrying.
+- Drag a wire out of an output and let go over open canvas. Only the nodes that could take it are
+  offered; pick one and it arrives already wired.
+- Drag a box around the four or five nodes that build the initial direction and press `Ctrl+G`. The graph gets
+  smaller and the program does not change at all — check it in **Code**. Open the group, rename it in
+  the breadcrumb, and watch the node on the canvas behind it change with it.
+- Select the two or three nodes that make the initial speed, press `Ctrl+D`, and drag the copy
+  somewhere. Then `Ctrl+C`, switch to **UPDATE**, and `Ctrl+V`: the same nodes, wired the same way, in
+  the other phase. `Ctrl+Z` takes the whole paste back in one go.
+- Add a `Simplex Noise 3D` and open it. Three hundred instructions of arithmetic, drawn — and read
+  only, because it is one of the library's own. `Curl Noise 4D` is twelve of those; the **Code** tab
+  is where to see what that means.
+- Add a `Flow Noise 3D` instead and wire `alpha` to the elapsed time. It is the same kind of field
+  with two differences worth the instructions: its gradients turn as `alpha` moves, so the field
+  swirls in place rather than sliding past, and it hands back its own derivative alongside the value.
+  `Tiling Flow Noise 3D` is that with a period you can name, per axis.
+- Drop an `RGBA Gradient` on a `Write Attribute` bound to `color`, wire `t` to the particle's
+  normalised age, and drag the stops while the preview runs. Then look at **Code**: the gradient is a
+  literal, a saturate and a multiply-add per stop, and there is no table anywhere.
+- Set **blend** to `alpha` and back to `additive`. The preview composites accordingly.
+- `Ctrl+Z` in the graph. Every edit — a wire, a move, a parameter, a node from the menu — is one
+  timeline.
+
+## Driving it without a person
+
+The page is deliberately scriptable, because `requestAnimationFrame` is suspended in a hidden or
+headless tab and the preview would otherwise never advance:
+
+| handle | what it does |
+|---|---|
+| `__step(frames, dt)` | run exactly that many preview frames, return the live particle count |
+| `__export()` | the whole document as JSON |
+| `__import(json)` | replace the document with one |
+| `__reset()` | forget the kept document and reload |
+| `effect`, `view`, `actionProcessor` | the document, the root view, the undo timeline |
+
+The document is kept in `localStorage` between reloads, so an effect survives a refresh.
+
+## Where the pieces live
+
+The page owns almost nothing — it builds a document, mounts one view, and wires the window's size and
+`localStorage`. Everything else is the editor's, and is built to be docked as panels rather than
+used only here:
+
+| what | where |
+|---|---|
+| the document both layers edit | `editor/particles/effect/ParticleEffectDocument.js` |
+| the CPU preview simulation | `editor/particles/effect/ParticleReferenceSimulation.js` |
+| graph layer | `editor/view/particles/effect/ParticleGraphEditorView.js` |
+| what each node type is called and drawn as | `src/shade/renderer/particles/graph/particle_node_presentation.js` |
+| the node library the menu offers | `src/shade/renderer/particles/graph/particle_node_library.js` |
+| what a node group is, and its boundary | `src/shade/renderer/particles/graph/ParticleNodeGroup.js` |
+| making one out of a selection | `src/shade/renderer/particles/graph/make_particle_group.js` |
+| a group in a file | `src/shade/renderer/particles/graph/particle_group_json.js` |
+| the groups the editor ships with | `src/shade/renderer/particles/graph/groups/` |
+| a gradient and a curve, and the arithmetic they become | `src/shade/renderer/particles/graph/particle_ramp.js` |
+| the controls those two are edited with | `editor/view/particles/effect/ParticleGradientEditorView.js`, `ParticleCurveEditorView.js` |
+| code layer | `editor/view/particles/effect/ParticleCodeEditorView.js` |
+| emitter + attributes | `editor/view/particles/effect/ParticleEmitterInspectorView.js` |
+| preview | `editor/view/particles/effect/ParticlePreviewView.js` |
+| the four assembled | `editor/view/particles/effect/ParticleEffectEditorView.js` |
+
+Each panel takes nothing but the document, so an editor shell docks them individually and skips the
+assembled view. They share one `ActionProcessor`; pass a host editor's own and particle authoring
+lands on the application's undo timeline.
+
+Styling is two plain CSS files — `editor/view/node-graph/node-graph.css` for the graph views and
+`editor/view/particles/effect/particle-editor.css` for these panels — linked by this page's HTML.
+Plain CSS rather than SCSS so a page with no sass toolchain can serve them; a host that compiles
+`editor/style/editor.scss` includes them the same way.
+
+## Verifying it
+
+```bash
+npx vitest run editor/particles/effect editor/view/particles editor/view/node-graph src/shade/renderer/particles/graph src/shade/renderer/particles/isa
+```
+
+Those cover the document, the reference simulation, the four panels under jsdom, the node-graph base
+they are built on, and the assembly language underneath both layers. What no spec here can see is the
+picture, which is this page's job.

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

@@ -0,0 +1,76 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — particle effect editor</title>
+
+    <link rel="stylesheet" href="/editor/view/node-graph/node-graph.css">
+    <link rel="stylesheet" href="/editor/view/particles/effect/particle-editor.css">
+
+    <style>
+        :root {
+            color-scheme: dark;
+
+            /* the editor's own tokens, so the panels theme as they would inside the editor shell */
+            --meep-panel-bg: #1a1e25;
+            --meep-header-bg: #22262e;
+            --meep-divider-color: #10131a;
+            --meep-fg: #d6dae0;
+            --meep-fg-muted: #8b939f;
+            --meep-accent: #2d7dd2;
+            --meep-error: #ff7a7a;
+            --meep-warning: #e2b341;
+            --meep-font: 12px 'Segoe UI', system-ui, sans-serif;
+            --meep-graph-bg: #12151b;
+            --meep-graph-bg-glow: #1a1e26;
+            --meep-graph-node-bg: #232830;
+            --meep-graph-node-header: #2b313b;
+            --meep-graph-node-border: #363c46;
+            --meep-graph-input-bg: #171b21;
+        }
+
+        * { box-sizing: border-box; }
+
+        html, body {
+            height: 100%;
+            margin: 0;
+            overflow: hidden;
+            background: var(--meep-panel-bg);
+            color: var(--meep-fg);
+            font: var(--meep-font);
+        }
+
+        #root {
+            position: relative;
+            width: 100%;
+            height: 100%;
+        }
+
+        #message {
+            position: fixed;
+            inset: 0;
+            display: none;
+            align-items: center;
+            justify-content: center;
+            padding: 32px;
+            text-align: center;
+            background: #0a0d12e6;
+            color: var(--meep-error);
+            font-size: 15px;
+            white-space: pre-wrap;
+            z-index: 100;
+        }
+
+        #message:not(:empty) { display: flex; }
+    </style>
+</head>
+<body>
+
+<div id="root"></div>
+
+<div id="message"></div>
+
+<script type="module" src="./main.js"></script>
+
+</body>
+</html>

package/src/shade/playground/particle_editor/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/particle_editor/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_editor/main.js"],"names":[],"mappings":""}

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

@@ -0,0 +1,139 @@
+import { ActionProcessor } from "../../../core/process/undo/ActionProcessor.js";
+import { NodeDescriptionVisualRegistry } from "../../../core/model/node-graph/visual/NodeDescriptionVisualRegistry.js";
+import { PARTICLE_NODE_REGISTRY } from "../../renderer/particles/graph/ParticleNodeRegistry.js";
+import "../../renderer/particles/graph/particle_node_library.js";
+import { make_starter_particle_effect } from "../../../../editor/particles/effect/make_starter_particle_effect.js";
+import { ParticleEffectDocument } from "../../../../editor/particles/effect/ParticleEffectDocument.js";
+import {
+    ParticleEffectEditorView
+} from "../../../../editor/view/particles/effect/ParticleEffectEditorView.js";
+
+/**
+ * The particle effect editor, on a page of its own.
+ *
+ * Both authoring layers and the live preview, over one {@link ParticleEffectDocument} — which is the
+ * whole point of the page: the graph, the instructions it compiles to, the emitter settings and the
+ * effect running are four views of one thing, and an edit in any of them is visible in the rest
+ * before you have finished making it.
+ *
+ * The page owns almost nothing. It builds a document, mounts
+ * {@link ParticleEffectEditorView} over the whole window, and wires the browser-shaped edges the
+ * views deliberately do not have: the window's size, the address bar, and load/save through a file.
+ *
+ * Serve the workspace with `npm run dev --workspace @woosh/meep-engine` and open
+ * `/src/shade/playground/particle_editor/index.html`. See README.md for what to look at.
+ */
+
+/** Key the working document is kept under between reloads. @type {string} */
+const STORAGE_KEY = "meep.particle_editor.document";
+
+const element = id => document.getElementById(id);
+
+function main() {
+    const root = element("root");
+
+    const visualRegistry = new NodeDescriptionVisualRegistry();
+
+    PARTICLE_NODE_REGISTRY.getNodesAsArray().forEach(description => visualRegistry.generate(description));
+
+    const effect = restore(visualRegistry) ?? make_starter_particle_effect();
+
+    const actionProcessor = new ActionProcessor({});
+
+    const view = new ParticleEffectEditorView({ effect, actionProcessor });
+
+    root.appendChild(view.el);
+
+    view.link();
+
+    const resize = () => view.size.set(root.clientWidth, root.clientHeight);
+
+    resize();
+
+    window.addEventListener("resize", resize);
+
+    // The document is kept across reloads, because an editor that loses an effect to a refresh is
+    // one nobody trusts with an effect. Debounced: an edit is a change on every keystroke.
+    let save_timer = 0;
+
+    effect.on.changed.add(() => {
+        clearTimeout(save_timer);
+
+        save_timer = setTimeout(() => {
+            try {
+                localStorage.setItem(STORAGE_KEY, JSON.stringify(effect.toJSON()));
+            } catch (e) {
+                console.warn("could not keep the effect:", e.message);
+            }
+        }, 500);
+    });
+
+    // Everything a session might want to reach for, and the handles a scripted one needs. `__step`
+    // drives the preview by hand where requestAnimationFrame is suspended — a hidden or headless
+    // tab — which is what makes the page verifiable without a person watching it.
+    Object.assign(globalThis, {
+        effect,
+        view,
+        actionProcessor,
+        visualRegistry,
+
+        __step: (frames = 1, dt = 1 / 60) => {
+            for (let i = 0; i < frames; i++) {
+                view.preview.step(dt);
+            }
+
+            return view.preview.simulation.count;
+        },
+
+        __reset: () => {
+            localStorage.removeItem(STORAGE_KEY);
+            location.reload();
+        },
+
+        __export: () => JSON.stringify(effect.toJSON(), null, 2),
+
+        __import: json => {
+            effect.fromJSON(typeof json === "string" ? JSON.parse(json) : json, visualRegistry);
+        },
+    });
+}
+
+/**
+ * The document kept from the last session, if there is one and it still loads.
+ *
+ * A stored document that cannot be read is dropped rather than raised: it is almost always one
+ * written by an older build, and an editor that will not open because of it is worse than one that
+ * opens on the starting effect.
+ *
+ * @param {NodeDescriptionVisualRegistry} visualRegistry
+ * @returns {ParticleEffectDocument|null}
+ */
+function restore(visualRegistry) {
+    let stored;
+
+    try {
+        stored = localStorage.getItem(STORAGE_KEY);
+    } catch (e) {
+        return null;
+    }
+
+    if (stored === null) {
+        return null;
+    }
+
+    try {
+        return new ParticleEffectDocument().fromJSON(JSON.parse(stored), visualRegistry);
+    } catch (e) {
+        console.warn("the kept effect could not be opened, starting fresh:", e.message);
+
+        return null;
+    }
+}
+
+try {
+    main();
+} catch (e) {
+    console.error(e);
+
+    element("message").textContent = "The particle editor failed to start — see the console.\n\n" + e.message;
+}