@woosh/meep-engine 3.15.0 → 3.16.0

package/src/shade/{renderer/particles → playground/particle_system}/particle_prototype.js

@@ -1,181 +1,197 @@
-import { EMITTER_BLEND, EMITTER_PROJECTION } from "./data/PARTICLE_EMITTER_LAYOUT.js";
-import { NodeGraph } from "../../../core/model/node-graph/NodeGraph.js";
-import { particle_node, particle_wire } from "./graph/particle_graph_authoring.js";
-import { VM_BUILTIN, VM_RANDOM_MODE } from "./isa/ParticleVMISA.js";
-import { ParticleLayout } from "./layout/ParticleLayout.js";
-import { create_particle_effect } from "./runtime/create_particle_effect.js";
-
-/**
- * Worked examples of authoring particle effects with the node graph + wiring them into a
- * {@link GPUParticleSystem}. Demonstrates: distinct per-particle lifecycle (no built-in age — the
- * effect declares it), AnimationCurve sampling over life, flipbook frames, random emission,
- * additive vs alpha blending, projection modes, soft depth and lighting toggles.
- *
- * `curves` is a `GPUAnimationManager` (or anything with `register_curve(AnimationCurve) -> handle`);
- * `size_curve` / `alpha_curve` are meep `AnimationCurve`s. Both are optional — passing `undefined`
- * yields effects that use constant size/alpha instead (curve handle 0, evaluated as 0 by the
- * disabled provider), which is handy for the headless tests.
- */
-
-/**
- * A fire effect: buoyant, turbulent, additive-blended camera-facing sprites whose size and opacity
- * follow curves over their lifetime and whose flipbook advances with age.
- *
- * @param {object} [options]
- * @param {number} [options.size_curve] curve handle for size(normalizedAge)
- * @param {number} [options.alpha_curve] curve handle for alpha(normalizedAge)
- * @param {number} [options.flipbook_frames]
- * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
- */
-export function fire_effect({ size_curve, alpha_curve, flipbook_frames = 16 } = {}) {
-    const layout = new ParticleLayout([
-        { name: "position", components: 3 },
-        { name: "velocity", components: 3 },
-        { name: "age", components: 1 },
-        { name: "lifetime", components: 1 },
-        { name: "size", components: 1 },
-        { name: "color", components: 4 },
-        { name: "frame", components: 1 },
-    ]);
-
-    // --- SPAWN: seed each particle's state ---
-    const spawn = new NodeGraph();
-    {
-        // position = emitter position + a small disk of jitter on the ground
-        const ep = particle_node(spawn, "builtin", { id: VM_BUILTIN.EMITTER_POSITION });
-        const disk = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIT_DISK });
-        const jitter = particle_node(spawn, "scale"); particle_wire(spawn, jitter, "v", disk); particle_wire(spawn, jitter, "s", [0.2]);
-        const p0 = particle_node(spawn, "add"); particle_wire(spawn, p0, "a", ep); particle_wire(spawn, p0, "b", jitter);
-        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "position" }), "value", p0);
-
-        // velocity = upward buoyancy + signed turbulence
-        const up = particle_node(spawn, "const", { value: [0, 2.0, 0, 0] });
-        const turb = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIFORM_SIGNED });
-        const turbS = particle_node(spawn, "scale"); particle_wire(spawn, turbS, "v", turb); particle_wire(spawn, turbS, "s", [0.5]);
-        const v0 = particle_node(spawn, "add"); particle_wire(spawn, v0, "a", up); particle_wire(spawn, v0, "b", turbS);
-        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "velocity" }), "value", v0);
-
-        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "age" }), "value", [0]);
-        // lifetime 1.2..1.8s
-        const lr = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIFORM });
-        const ls = particle_node(spawn, "mad"); particle_wire(spawn, ls, "a", lr); particle_wire(spawn, ls, "b", [0.6]); particle_wire(spawn, ls, "c", [1.2]);
-        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "lifetime" }), "value", ls);
-
-        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "size" }), "value", [0.4]);
-        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "color" }), "value", [1.0, 0.6, 0.2, 1.0]);
-        particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "frame" }), "value", [0]);
-    }
-
-    // --- UPDATE: advance + destroy ---
-    const update = new NodeGraph();
-    {
-        const dt = particle_node(update, "builtin", { id: VM_BUILTIN.DELTA_TIME });
-
-        // age += dt
-        const age = particle_node(update, "attribute", { name: "age" });
-        const newAge = particle_node(update, "add"); particle_wire(update, newAge, "a", age); particle_wire(update, newAge, "b", dt);
-        particle_wire(update, particle_node(update, "setAttribute", { name: "age" }), "value", newAge);
-
-        // normalizedAge = age / lifetime
-        const lifetime = particle_node(update, "attribute", { name: "lifetime" });
-        const nAge = particle_node(update, "div"); particle_wire(update, nAge, "a", newAge); particle_wire(update, nAge, "b", lifetime);
-
-        // kill when normalizedAge >= 1
-        const dead = particle_node(update, "compare", { op: "ge" }); particle_wire(update, dead, "a", nAge); particle_wire(update, dead, "b", [1]);
-        particle_wire(update, particle_node(update, "kill"), "condition", dead);
-
-        // buoyant rise + drift: velocity += (0, 1, 0)*dt ; position += velocity*dt
-        const vel = particle_node(update, "attribute", { name: "velocity" });
-        const buoy = particle_node(update, "const", { value: [0, 1.0, 0, 0] });
-        const buoyDt = particle_node(update, "scale"); particle_wire(update, buoyDt, "v", buoy); particle_wire(update, buoyDt, "s", dt);
-        const nVel = particle_node(update, "add"); particle_wire(update, nVel, "a", vel); particle_wire(update, nVel, "b", buoyDt);
-        particle_wire(update, particle_node(update, "setAttribute", { name: "velocity" }), "value", nVel);
-        const pos = particle_node(update, "attribute", { name: "position" });
-        const velDt = particle_node(update, "scale"); particle_wire(update, velDt, "v", nVel); particle_wire(update, velDt, "s", dt);
-        const nPos = particle_node(update, "add"); particle_wire(update, nPos, "a", pos); particle_wire(update, nPos, "b", velDt);
-        particle_wire(update, particle_node(update, "setAttribute", { name: "position" }), "value", nPos);
-
-        // size + alpha from curves over life (or constants if no curve provided)
-        if (size_curve !== undefined) {
-            const sc = particle_node(update, "curve", { handle: size_curve }); particle_wire(update, sc, "t", nAge);
-            particle_wire(update, particle_node(update, "setAttribute", { name: "size" }), "value", sc);
-        }
-        const color = particle_node(update, "attribute", { name: "color" });
-        if (alpha_curve !== undefined) {
-            const ac = particle_node(update, "curve", { handle: alpha_curve }); particle_wire(update, ac, "t", nAge);
-            // color.rgb unchanged, color.a = ac : rebuild via select on a swizzle mask is overkill;
-            // simplest: multiply color by (1,1,1,ac_normalized) — approximate by scaling alpha only.
-            const alphaVec = particle_node(update, "mul");
-            particle_wire(update, alphaVec, "a", color);
-            particle_wire(update, alphaVec, "b", ac); // broadcasts ac to all lanes (rgb also fades — a warm ember look)
-            particle_wire(update, particle_node(update, "setAttribute", { name: "color" }), "value", alphaVec);
-        }
-
-        // flipbook frame = floor(normalizedAge * frames)
-        const framesN = particle_node(update, "const", { value: [flipbook_frames, 0, 0, 0] });
-        const fscaled = particle_node(update, "mul"); particle_wire(update, fscaled, "a", nAge); particle_wire(update, fscaled, "b", framesN);
-        const fframe = particle_node(update, "floor"); particle_wire(update, fframe, "x", fscaled);
-        particle_wire(update, particle_node(update, "setAttribute", { name: "frame" }), "value", fframe);
-    }
-
-    const effect = create_particle_effect({ layout, spawn, update });
-
-    const emitter = {
-        effect,
-        spawn_rate: 120,
-        flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
-        render: { position: "position", size: "size", color: "color", frame: "frame" },
-        bounds: { center: [0, 1.5, 0], radius: 2.5 },
-        // A 4x4 flipbook packed as the whole atlas here; a real atlas would use a sub-rect.
-        atlas_region: [0, 0, 1, 1],
-        flipbook: [4, 4],
-    };
-
-    return { layout, effect, emitter };
-}
-
-/**
- * A smoke effect: slow, expanding, alpha-blended, lit, soft-depth billboards. Same authoring
- * surface as fire; the differences are all data (blend/lighting/soft flags, rates, colours).
- * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
- */
-export function smoke_effect() {
-    const { layout, effect } = fire_effect({ flipbook_frames: 8 });
-    const emitter = {
-        effect,
-        spawn_rate: 25,
-        flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true, lighting: true, sort: true },
-        render: { position: "position", size: "size", color: "color", frame: "frame" },
-        bounds: { center: [0, 3, 0], radius: 5 },
-        atlas_region: [0, 0, 1, 1],
-        flipbook: [1, 1],
-    };
-    return { layout, effect, emitter };
-}
-
-/**
- * Register a fire + smoke plume on a particle system, optionally attaching the fire to a bone.
- *
- * The per-frame loop the integrator runs:
- * ```js
- * const spawn_requests = system.update(dt, { is_visible });     // CPU: bone transforms + spawn counts
- * system.uploadFrame(spawn_requests);                           // upload emitters (if dirty) + requests
- * graph_particles({ graph, gpu: system.gpuHandles(), frame });  // reset -> emit -> simulate -> indirect
- * // caller appends the depth sort + billboard render into its own graph
- * ```
- *
- * @param {import("./GPUParticleSystem.js").GPUParticleSystem} system
- * @param {object} [options]
- * @param {object} [options.bone] a Node3D to attach the fire emitter to
- * @returns {{fire: number, smoke: number}} emitter indices
- */
-export function register_campfire(system, { bone } = {}) {
-    const fire = system.addEmitter(fire_effect().emitter);
-    const smoke = system.addEmitter(smoke_effect().emitter);
-    if (bone !== undefined) {
-        system.attachToNode(fire, bone);
-        system.attachToNode(smoke, bone);
-    }
-    system.buildEmitterData();
-    return { fire, smoke };
-}
+import { EMITTER_BLEND, EMITTER_PROJECTION } from "../../renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
+import { NodeGraph } from "../../../core/model/node-graph/NodeGraph.js";
+import { particle_node, particle_wire } from "../../renderer/particles/graph/particle_graph_authoring.js";
+import {
+    particle_unit_disk,
+    particle_uniform_signed,
+} from "../../renderer/particles/graph/particle_graph_distributions.js";
+import { VM_BUILTIN } from "../../renderer/particles/isa/ParticleVMISA.js";
+import { ParticleLayout } from "../../renderer/particles/layout/ParticleLayout.js";
+import { create_particle_effect } from "../../renderer/particles/runtime/create_particle_effect.js";
+import { ParticleEmitter } from "../../renderer/particles/runtime/ParticleEmitter.js";
+
+/**
+ * Worked examples of authoring particle effects with the node graph + placing them in a scene for a
+ * {@link GPUParticleSystem} to run. Demonstrates: distinct per-particle lifecycle (no built-in age — the
+ * effect declares it), AnimationCurve sampling over life, flipbook frames, random emission,
+ * additive vs alpha blending, projection modes, soft depth and lighting toggles.
+ *
+ * These are examples, not engine code, which is why they sit here rather than under
+ * `renderer/particles/`: the only thing that opens them is this playground's page, and keeping them
+ * on this side of the line means the dependency runs playground -> renderer and never back.
+ *
+ * `curves` is a `GPUAnimationManager` (or anything with `register_curve(AnimationCurve) -> handle`);
+ * `size_curve` / `alpha_curve` are meep `AnimationCurve`s. Both are optional — passing `undefined`
+ * yields effects that use constant size/alpha instead (curve handle 0, evaluated as 0 by the
+ * disabled provider), which is handy for the headless tests.
+ */
+
+/**
+ * A fire effect: buoyant, turbulent, additive-blended camera-facing sprites whose size and opacity
+ * follow curves over their lifetime and whose flipbook advances with age.
+ *
+ * @param {object} [options]
+ * @param {number} [options.size_curve] curve handle for size(normalizedAge)
+ * @param {number} [options.alpha_curve] curve handle for alpha(normalizedAge)
+ * @param {number} [options.flipbook_frames]
+ * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
+ */
+export function fire_effect({ size_curve, alpha_curve, flipbook_frames = 16 } = {}) {
+    const layout = new ParticleLayout([
+        { name: "position", components: 3 },
+        { name: "velocity", components: 3 },
+        { name: "age", components: 1 },
+        { name: "lifetime", components: 1 },
+        { name: "size", components: 1 },
+        { name: "color", components: 4 },
+        { name: "frame", components: 1 },
+    ]);
+
+    // --- INIT: seed each particle's state ---
+    const init = new NodeGraph();
+    {
+        // position = emitter position + a small disk of jitter on the ground: the disk is a vec2,
+        // and the ground is the xz plane, so it is laid down with a constructor
+        const ep = particle_node(init, "builtin", { id: VM_BUILTIN.EMITTER_POSITION });
+        const disk = particle_unit_disk(init);
+        const jitter = particle_node(init, "scale"); particle_wire(init, jitter, "v", disk); particle_wire(init, jitter, "s", [0.2]);
+        const jx = particle_node(init, "swizzle", { pattern: [0] }); particle_wire(init, jx, "x", jitter);
+        const jz = particle_node(init, "swizzle", { pattern: [1] }); particle_wire(init, jz, "x", jitter);
+        const ground = particle_node(init, "vec3");
+        particle_wire(init, ground, "x", jx); particle_wire(init, ground, "y", [0]); particle_wire(init, ground, "z", jz);
+        const p0 = particle_node(init, "add"); particle_wire(init, p0, "a", ep); particle_wire(init, p0, "b", ground);
+        particle_wire(init, particle_node(init, "setAttribute", { name: "position" }), "value", p0);
+
+        // velocity = upward buoyancy + signed turbulence, a draw per lane
+        const up = particle_node(init, "const", { value: [0, 2.0, 0] });
+        const turb = particle_uniform_signed(init, 3);
+        const turbS = particle_node(init, "scale"); particle_wire(init, turbS, "v", turb); particle_wire(init, turbS, "s", [0.5]);
+        const v0 = particle_node(init, "add"); particle_wire(init, v0, "a", up); particle_wire(init, v0, "b", turbS);
+        particle_wire(init, particle_node(init, "setAttribute", { name: "velocity" }), "value", v0);
+
+        particle_wire(init, particle_node(init, "setAttribute", { name: "age" }), "value", [0]);
+        // lifetime 1.2..1.8s
+        const lr = particle_node(init, "random", { components: 1 });
+        const ls = particle_node(init, "mad"); particle_wire(init, ls, "a", lr); particle_wire(init, ls, "b", [0.6]); particle_wire(init, ls, "c", [1.2]);
+        particle_wire(init, particle_node(init, "setAttribute", { name: "lifetime" }), "value", ls);
+
+        particle_wire(init, particle_node(init, "setAttribute", { name: "size" }), "value", [0.4]);
+        particle_wire(init, particle_node(init, "setAttribute", { name: "color" }), "value", [1.0, 0.6, 0.2, 1.0]);
+        particle_wire(init, particle_node(init, "setAttribute", { name: "frame" }), "value", [0]);
+    }
+
+    // --- UPDATE: advance + destroy ---
+    const update = new NodeGraph();
+    {
+        const dt = particle_node(update, "builtin", { id: VM_BUILTIN.DELTA_TIME });
+
+        // age += dt
+        const age = particle_node(update, "attribute", { name: "age" });
+        const newAge = particle_node(update, "add"); particle_wire(update, newAge, "a", age); particle_wire(update, newAge, "b", dt);
+        particle_wire(update, particle_node(update, "setAttribute", { name: "age" }), "value", newAge);
+
+        // normalizedAge = age / lifetime
+        const lifetime = particle_node(update, "attribute", { name: "lifetime" });
+        const nAge = particle_node(update, "div"); particle_wire(update, nAge, "a", newAge); particle_wire(update, nAge, "b", lifetime);
+
+        // kill when normalizedAge >= 1
+        const dead = particle_node(update, "compare", { op: "ge" }); particle_wire(update, dead, "a", nAge); particle_wire(update, dead, "b", [1]);
+        particle_wire(update, particle_node(update, "kill"), "condition", dead);
+
+        // buoyant rise + drift: velocity += (0, 1, 0)*dt ; position += velocity*dt
+        const vel = particle_node(update, "attribute", { name: "velocity" });
+        const buoy = particle_node(update, "const", { value: [0, 1.0, 0] });
+        const buoyDt = particle_node(update, "scale"); particle_wire(update, buoyDt, "v", buoy); particle_wire(update, buoyDt, "s", dt);
+        const nVel = particle_node(update, "add"); particle_wire(update, nVel, "a", vel); particle_wire(update, nVel, "b", buoyDt);
+        particle_wire(update, particle_node(update, "setAttribute", { name: "velocity" }), "value", nVel);
+        const pos = particle_node(update, "attribute", { name: "position" });
+        const velDt = particle_node(update, "scale"); particle_wire(update, velDt, "v", nVel); particle_wire(update, velDt, "s", dt);
+        const nPos = particle_node(update, "add"); particle_wire(update, nPos, "a", pos); particle_wire(update, nPos, "b", velDt);
+        particle_wire(update, particle_node(update, "setAttribute", { name: "position" }), "value", nPos);
+
+        // size + alpha from curves over life (or constants if no curve provided)
+        if (size_curve !== undefined) {
+            const sc = particle_node(update, "curve", { handle: size_curve }); particle_wire(update, sc, "t", nAge);
+            particle_wire(update, particle_node(update, "setAttribute", { name: "size" }), "value", sc);
+        }
+        const color = particle_node(update, "attribute", { name: "color" });
+        if (alpha_curve !== undefined) {
+            const ac = particle_node(update, "curve", { handle: alpha_curve }); particle_wire(update, ac, "t", nAge);
+            // color.rgb unchanged, color.a = ac : rebuild via select on a swizzle mask is overkill;
+            // simplest: multiply color by (1,1,1,ac_normalized) — approximate by scaling alpha only.
+            const alphaVec = particle_node(update, "mul");
+            particle_wire(update, alphaVec, "a", color);
+            particle_wire(update, alphaVec, "b", ac); // a scalar, so it scales every lane (rgb also fades — a warm ember look)
+            particle_wire(update, particle_node(update, "setAttribute", { name: "color" }), "value", alphaVec);
+        }
+
+        // flipbook frame = floor(normalizedAge * frames)
+        const framesN = particle_node(update, "const", { value: [flipbook_frames] });
+        const fscaled = particle_node(update, "mul"); particle_wire(update, fscaled, "a", nAge); particle_wire(update, fscaled, "b", framesN);
+        const fframe = particle_node(update, "floor"); particle_wire(update, fframe, "x", fscaled);
+        particle_wire(update, particle_node(update, "setAttribute", { name: "frame" }), "value", fframe);
+    }
+
+    const effect = create_particle_effect({ layout, init, update });
+
+    const emitter = {
+        effect,
+        spawn_rate: 120,
+        flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
+        render: { position: "position", size: "size", color: "color", frame: "frame" },
+        bounds: { center: [0, 1.5, 0], radius: 2.5 },
+        // A 4x4 flipbook packed as the whole atlas here; a real atlas would use a sub-rect.
+        atlas_region: [0, 0, 1, 1],
+        flipbook: [4, 4],
+    };
+
+    return { layout, effect, emitter };
+}
+
+/**
+ * A smoke effect: slow, expanding, alpha-blended, lit, soft-depth billboards. Same authoring
+ * surface as fire; the differences are all data (blend/lighting/soft flags, rates, colours).
+ * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
+ */
+export function smoke_effect() {
+    const { layout, effect } = fire_effect({ flipbook_frames: 8 });
+    const emitter = {
+        effect,
+        spawn_rate: 25,
+        flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true, lighting: true, sort: true },
+        render: { position: "position", size: "size", color: "color", frame: "frame" },
+        bounds: { center: [0, 3, 0], radius: 5 },
+        atlas_region: [0, 0, 1, 1],
+        flipbook: [1, 1],
+    };
+    return { layout, effect, emitter };
+}
+
+/**
+ * Put a fire + smoke plume in a scene, optionally riding a bone.
+ *
+ * An emitter is a scene node, so this is scene-graph work and nothing else: build the two emitters,
+ * parent them to the bone if there is one, add them to the scene. The particle system finds them
+ * on its next frame, gives them rows, and the GPU composes the bone's motion into every particle
+ * they spawn — there is no per-frame call to make.
+ *
+ * @param {import("../../renderer/scene/Scene.js").Scene} scene
+ * @param {object} [options]
+ * @param {import("../../renderer/scene/Node3D.js").Node3D} [options.bone] a node, already in the
+ *        scene, for both emitters to hang off
+ * @returns {{fire: ParticleEmitter, smoke: ParticleEmitter}}
+ */
+export function register_campfire(scene, { bone } = {}) {
+    const fire = ParticleEmitter.from({ ...fire_effect().emitter, name: "fire" });
+    const smoke = ParticleEmitter.from({ ...smoke_effect().emitter, name: "smoke" });
+
+    if (bone !== undefined) {
+        bone.addChild(fire);
+        bone.addChild(smoke);
+        bone.updateMatrices();
+    }
+
+    scene.add([fire, smoke]);
+
+    return { fire, smoke };
+}

package/src/shade/playground/particle_system/particle_scene.d.ts

@@ -1,35 +1,143 @@
+/**
+ * The five emitters, and the node one of them rides. Pure data: no device, no scene, nothing
+ * uploaded — {@link build_particle_scene} is what places them.
+ *
+ * Every one carries a bounds sphere that holds the effect it emits. Under AVBOIT that sphere is
+ * not just the culling test it used to be: it is what marks the depth slices the emitter may
+ * occlude in, so an emitter whose particles outrun it occludes at slightly the wrong depth. The
+ * spheres are sized to hold where the effect actually goes rather than to the last reachable
+ * corner of its jitter: 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.
+ *
+ * @returns {{fire: ParticleEmitter, smoke: ParticleEmitter, sparks: ParticleEmitter, dust: ParticleEmitter, torch: ParticleEmitter, orbit: Node3D}}
+ */
+export function create_particle_emitters(): {
+    fire: ParticleEmitter;
+    smoke: ParticleEmitter;
+    sparks: ParticleEmitter;
+    dust: ParticleEmitter;
+    torch: ParticleEmitter;
+    orbit: Node3D;
+};
+/**
+ * Build the scene: geometry, a light, and the emitters as nodes of it.
+ *
+ * Async because the meshlet builder runs on a WASM instance that instantiates asynchronously at
+ * import; building geometry before it is ready reads an instance that is not there yet.
+ *
+ * @returns {Promise<{scene: Scene, emitters: ReturnType<create_particle_emitters>, meshes: {floor: Mesh, pillar: Mesh, block: Mesh, pane: Mesh}}>}
+ */
+export function build_particle_scene(): Promise<{
+    scene: Scene;
+    emitters: ReturnType<typeof create_particle_emitters>;
+    meshes: {
+        floor: Mesh;
+        pillar: Mesh;
+        block: Mesh;
+        pane: Mesh;
+    };
+}>;
+/**
+ * Turn the particles on for this scene and give the system its sprite.
+ *
+ * This is the whole integration. The emitters are already scene nodes, so there is nothing to
+ * register: the system finds them the next time it sweeps, gives each a row pointed at the node's
+ * `transforms` row, and the renderer records the simulation and the three AVBOIT contributions.
+ *
+ * @param {import("../../renderer/Renderer.js").Renderer} renderer initialized
+ * @param {Scene} scene the one {@link build_particle_scene} returned
+ * @returns {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem}
+ */
+export function configure_particles(renderer: import("../../renderer/Renderer.js").Renderer, scene: Scene): import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem;
+/**
+ * Move what moves. One call, so the page's frame loop stays three lines and the motion is here
+ * with the scene it belongs to.
+ *
+ * @param {ReturnType<create_particle_emitters>} emitters
+ * @param {number} time seconds since start
+ */
+export function animate_particle_scene(emitters: ReturnType<typeof create_particle_emitters>, time: number): void;
+/**
+ * Copy the counters and both indirect arg buffers into a {@link PARTICLE_STATS_BYTES}-byte
+ * MAP_READ destination, for display. Read back to *look at*: nothing here may size a pass.
+ *
+ * @param {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem} system
+ * @param {GPUCommandEncoder} encoder
+ * @param {GPUBuffer} destination
+ */
+export function encode_stats_copy(system: import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem, encoder: GPUCommandEncoder, destination: GPUBuffer): void;
+/**
+ * Interpret the bytes {@link encode_stats_copy} wrote.
+ *
+ * @param {ArrayBuffer} bytes
+ * @returns {ParticleSceneStats}
+ */
+export function read_stats(bytes: ArrayBuffer): ParticleSceneStats;
+/**
+ * A 64x64 radial-falloff sprite (white, alpha falloff) for soft additive and alpha blobs.
+ *
+ * @param {GPUDevice} device
+ * @returns {GPUTexture}
+ */
+export function make_sprite_texture(device: GPUDevice): GPUTexture;
+/**
+ * The scene the particle playground shows, and the two lines of renderer configuration that make
+ * the particles part of it.
+ *
+ * The page draws through the whole {@link ../../renderer/Renderer.js} — the same one a game uses —
+ * so the particles arrive where they belong: inside the AVBOIT transparency pipeline, as a side
+ * channel of the transparent meshes, sorted against nothing and composited against everything. The
+ * page owns no pass, no pipeline, no camera buffer and no depth texture; it owns a {@link Scene}
+ * and a camera, and the renderer does the rest.
+ *
+ * Split from `main.js` so the part with no device in it can be spec'd: what emitters the scene has,
+ * what each is set to, and that {@link configure_particles} turns the feature on and hands the
+ * system its atlas. What a frame *encodes* is not this file's business any more — the renderer's
+ * own `graph_particles.spec.js` and `graph_particles_avboit.spec.js` hold that, against the
+ * software device, pass by pass.
+ *
+ * What is on screen:
+ *
+ * - opaque geometry (a floor, a pillar, a block) and one transparent pane, so the particles have
+ *   both something to be occluded by and something to composite with,
+ * - five emitters sharing one pool, each set up to exercise a different path: additive billboards,
+ *   an alpha soft-depth column, velocity-stretched sparks, a wide alpha drift, and one riding a
+ *   node that orbits, so a moving emitter is on screen,
+ * - a sunlight and (from the page) the default environment, because the meshes are lit.
+ */
+/** Bytes {@link encode_stats_copy} writes: 8 counters, then both indirect arg buffers. */
+export const PARTICLE_STATS_BYTES: 64;
 /**
  * @typedef {object} ParticleSceneStats
  * @property {number} alive particles alive at the end of the captured frame
  * @property {number} dead free slots left in the pool
+ * @property {number} spawn_budget free slots the frame's emitters left unclaimed
  * @property {number} alive_in the snapshot next frame's simulate reads as its input length — the
  *   PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
  * @property {number} sim_padded length of the program-coherent list the coherence pass built this
  *   frame; the gap to `alive` is the lanes padding costs to keep each wave on one VM program
  * @property {number[]} dispatch simulate's indirect dispatch args, `[x, y, z]` workgroups
- * @property {number[]} draw the billboard draw's indirect args, `[vertices, instances]`
+ * @property {number[]} draw the draw's indirect args, `[vertices, instances]`
  */
 /**
- * Build the scene against a live (or mock) device.
+ * What each of the four parametric emitters emits, apart from the fire, whose effect is the worked
+ * example next door. Exported because the bounds spheres below are authored against these numbers
+ * and a spec can check that they still hold: an emitter that travels further than its sphere
+ * occludes at the wrong depth now that the sphere is the occupancy hint.
  *
- * @param {GraphicsContext} graphics
- * @param {object} options
- * @param {GPUTextureFormat} options.color_format format of the colour target frames are encoded into
- * @param {number} [options.capacity] particle pool size
- * @returns {object} the scene, see the returned object's own members
- */
-export function create_particle_scene(graphics: GraphicsContext, { color_format, capacity }: {
-    color_format: GPUTextureFormat;
-    capacity?: number;
-}): object;
-/**
- * The largest immediate block any of the three compute passes declares (emit's 20-byte settings
- * struct). Immediate data is an optional WebGPU capability, so callers check for it up front rather
- * than letting pipeline creation fail with an error that names neither pass nor feature.
+ * @type {Object<string, {velocity: number[], velocityJitter: number, posJitter: number, accel: number, life: number[], size: number, color: number[]}>}
  */
-export const PARTICLE_IMMEDIATE_BYTES: 20;
-/** Bytes of stats {@link ParticleScene#encode_stats_copy} writes: 8 counters, then both arg buffers. */
-export const PARTICLE_STATS_BYTES: 64;
+export const PARTICLE_EMITTER_MOTION: {
+    [x: string]: {
+        velocity: number[];
+        velocityJitter: number;
+        posJitter: number;
+        accel: number;
+        life: number[];
+        size: number;
+        color: number[];
+    };
+};
 export type ParticleSceneStats = {
     /**
      * particles alive at the end of the captured frame
@@ -39,6 +147,10 @@ export type ParticleSceneStats = {
      * free slots left in the pool
      */
     dead: number;
+    /**
+     * free slots the frame's emitters left unclaimed
+     */
+    spawn_budget: number;
     /**
      * the snapshot next frame's simulate reads as its input length — the
      * PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
@@ -54,8 +166,12 @@ export type ParticleSceneStats = {
      */
     dispatch: number[];
     /**
-     * the billboard draw's indirect args, `[vertices, instances]`
+     * the draw's indirect args, `[vertices, instances]`
      */
     draw: number[];
 };
+import { ParticleEmitter } from "../../renderer/particles/runtime/ParticleEmitter.js";
+import { Node3D } from "../../renderer/scene/Node3D.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { Mesh } from "../../renderer/scene/Mesh.js";
 //# sourceMappingURL=particle_scene.d.ts.map

package/src/shade/playground/particle_system/particle_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AA4FA;;;;;;;;;;GAUG;AAEH;;;;;;;;GAQG;AACH;IAJqC,YAAY;IACrB,QAAQ,GAAzB,MAAM;IACJ,MAAM,CAiUlB;AAjWD;;;;GAIG;AACH,0CAA2C;AAE3C,wGAAwG;AACxG,sCAAuC;;;;;WAOzB,MAAM;;;;UACN,MAAM;;;;;cACN,MAAM;;;;;gBAEN,MAAM;;;;cAEN,MAAM,EAAE;;;;UACR,MAAM,EAAE"}
+{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AA0FA;;;;;;;;;;;;GAYG;AACH;UAFoB,eAAe;WAAS,eAAe;YAAU,eAAe;UAAQ,eAAe;WAAS,eAAe;WAAS,MAAM;EAmEjJ;AAED;;;;;;;GAOG;AACH;WAF6B,KAAK;cAAY,2CAAoC;;eAAkB,IAAI;gBAAU,IAAI;eAAS,IAAI;cAAQ,IAAI;;GAuD9I;AAED;;;;;;;;;;GAUG;AACH,8CAJW,OAAO,4BAA4B,EAAE,QAAQ,SAC7C,KAAK,GACH,OAAO,+CAA+C,EAAE,iBAAiB,CAmBrF;AAED;;;;;;GAMG;AACH,iDAHW,2CAAoC,QACpC,MAAM,QAWhB;AAED;;;;;;;GAOG;AACH,0CAJW,OAAO,+CAA+C,EAAE,iBAAiB,4DAUnF;AAED;;;;;GAKG;AACH,kCAHW,WAAW,GACT,kBAAkB,CAgB9B;AAED;;;;;GAKG;AACH,mEA4BC;AAnUD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,0FAA0F;AAC1F,sCAAuC;AAKvC;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH;QAFiB,MAAM,GAAE;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC;EAOpJ;;;;;WAxBY,MAAM;;;;UACN,MAAM;;;;kBACN,MAAM;;;;;cACN,MAAM;;;;;gBAEN,MAAM;;;;cAEN,MAAM,EAAE;;;;UACR,MAAM,EAAE;;gCAjDU,qDAAqD;uBAE9D,gCAAgC;sBACjC,+BAA+B;qBAFhC,8BAA8B"}