@woosh/meep-engine 3.14.3 → 3.14.5

package/src/shade/renderer/particles/particle_prototype.js

@@ -1,180 +1,181 @@
-import { EMITTER_BLEND, EMITTER_PROJECTION } from "./data/PARTICLE_EMITTER_LAYOUT.js";
-import { ParticleGraph } from "./graph/ParticleGraph.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 ParticleGraph();
-    {
-        // position = emitter position + a small disk of jitter on the ground
-        const ep = spawn.add("builtin", { id: VM_BUILTIN.EMITTER_POSITION });
-        const disk = spawn.add("random", { mode: VM_RANDOM_MODE.UNIT_DISK });
-        const jitter = spawn.add("scale"); spawn.wire(jitter, "v", disk); spawn.wire(jitter, "s", [0.2]);
-        const p0 = spawn.add("add"); spawn.wire(p0, "a", ep); spawn.wire(p0, "b", jitter);
-        spawn.wire(spawn.add("setAttribute", { name: "position" }), "value", p0);
-
-        // velocity = upward buoyancy + signed turbulence
-        const up = spawn.add("const", { value: [0, 2.0, 0, 0] });
-        const turb = spawn.add("random", { mode: VM_RANDOM_MODE.UNIFORM_SIGNED });
-        const turbS = spawn.add("scale"); spawn.wire(turbS, "v", turb); spawn.wire(turbS, "s", [0.5]);
-        const v0 = spawn.add("add"); spawn.wire(v0, "a", up); spawn.wire(v0, "b", turbS);
-        spawn.wire(spawn.add("setAttribute", { name: "velocity" }), "value", v0);
-
-        spawn.wire(spawn.add("setAttribute", { name: "age" }), "value", [0]);
-        // lifetime 1.2..1.8s
-        const lr = spawn.add("random", { mode: VM_RANDOM_MODE.UNIFORM });
-        const ls = spawn.add("mad"); spawn.wire(ls, "a", lr); spawn.wire(ls, "b", [0.6]); spawn.wire(ls, "c", [1.2]);
-        spawn.wire(spawn.add("setAttribute", { name: "lifetime" }), "value", ls);
-
-        spawn.wire(spawn.add("setAttribute", { name: "size" }), "value", [0.4]);
-        spawn.wire(spawn.add("setAttribute", { name: "color" }), "value", [1.0, 0.6, 0.2, 1.0]);
-        spawn.wire(spawn.add("setAttribute", { name: "frame" }), "value", [0]);
-    }
-
-    // --- UPDATE: advance + destroy ---
-    const update = new ParticleGraph();
-    {
-        const dt = update.add("builtin", { id: VM_BUILTIN.DELTA_TIME });
-
-        // age += dt
-        const age = update.add("attribute", { name: "age" });
-        const newAge = update.add("add"); update.wire(newAge, "a", age); update.wire(newAge, "b", dt);
-        update.wire(update.add("setAttribute", { name: "age" }), "value", newAge);
-
-        // normalizedAge = age / lifetime
-        const lifetime = update.add("attribute", { name: "lifetime" });
-        const nAge = update.add("div"); update.wire(nAge, "a", newAge); update.wire(nAge, "b", lifetime);
-
-        // kill when normalizedAge >= 1
-        const dead = update.add("compare", { op: "ge" }); update.wire(dead, "a", nAge); update.wire(dead, "b", [1]);
-        update.wire(update.add("kill"), "condition", dead);
-
-        // buoyant rise + drift: velocity += (0, 1, 0)*dt ; position += velocity*dt
-        const vel = update.add("attribute", { name: "velocity" });
-        const buoy = update.add("const", { value: [0, 1.0, 0, 0] });
-        const buoyDt = update.add("scale"); update.wire(buoyDt, "v", buoy); update.wire(buoyDt, "s", dt);
-        const nVel = update.add("add"); update.wire(nVel, "a", vel); update.wire(nVel, "b", buoyDt);
-        update.wire(update.add("setAttribute", { name: "velocity" }), "value", nVel);
-        const pos = update.add("attribute", { name: "position" });
-        const velDt = update.add("scale"); update.wire(velDt, "v", nVel); update.wire(velDt, "s", dt);
-        const nPos = update.add("add"); update.wire(nPos, "a", pos); update.wire(nPos, "b", velDt);
-        update.wire(update.add("setAttribute", { name: "position" }), "value", nPos);
-
-        // size + alpha from curves over life (or constants if no curve provided)
-        if (size_curve !== undefined) {
-            const sc = update.add("curve", { handle: size_curve }); update.wire(sc, "t", nAge);
-            update.wire(update.add("setAttribute", { name: "size" }), "value", sc);
-        }
-        const color = update.add("attribute", { name: "color" });
-        if (alpha_curve !== undefined) {
-            const ac = update.add("curve", { handle: alpha_curve }); update.wire(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 = update.add("mul");
-            update.wire(alphaVec, "a", color);
-            update.wire(alphaVec, "b", ac); // broadcasts ac to all lanes (rgb also fades — a warm ember look)
-            update.wire(update.add("setAttribute", { name: "color" }), "value", alphaVec);
-        }
-
-        // flipbook frame = floor(normalizedAge * frames)
-        const framesN = update.add("const", { value: [flipbook_frames, 0, 0, 0] });
-        const fscaled = update.add("mul"); update.wire(fscaled, "a", nAge); update.wire(fscaled, "b", framesN);
-        const fframe = update.add("floor"); update.wire(fframe, "x", fscaled);
-        update.wire(update.add("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 "./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 };
+}

package/src/shade/renderer/particles/runtime/create_particle_effect.d.ts

@@ -7,14 +7,14 @@
  *
  * @param {object} params
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
- * @param {import("../graph/ParticleGraph.js").ParticleGraph} [params.spawn]
- * @param {import("../graph/ParticleGraph.js").ParticleGraph} [params.update]
+ * @param {NodeGraph} [params.spawn]
+ * @param {NodeGraph} [params.update]
  * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
  */
 export function create_particle_effect({ layout, spawn, update }: {
     layout: import("../layout/ParticleLayout.js").ParticleLayout;
-    spawn?: import("../graph/ParticleGraph.js").ParticleGraph;
-    update?: import("../graph/ParticleGraph.js").ParticleGraph;
+    spawn?: NodeGraph;
+    update?: NodeGraph;
 }): {
     layout: import("../layout/ParticleLayout.js").ParticleLayout;
     program: import("../isa/ParticleProgram.js").ParticleProgram;

package/src/shade/renderer/particles/runtime/create_particle_effect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACO,KAAK,GAAhE,OAAO,2BAA2B,EAAE,aAAa;IACU,MAAM,GAAjE,OAAO,2BAA2B,EAAE,aAAa;;YACrC,OAAO,6BAA6B,EAAE,cAAc;aAAW,OAAO,2BAA2B,EAAE,eAAe;EAKxI"}
+{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,KAAK;IACL,MAAM;;YACb,OAAO,6BAA6B,EAAE,cAAc;aAAW,OAAO,2BAA2B,EAAE,eAAe;EAKxI"}

package/src/shade/renderer/particles/runtime/create_particle_effect.js

@@ -1,19 +1,19 @@
-import { compile_particle_effect } from "../graph/compile_particle_graph.js";
-
-/**
- * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus SPAWN
- * and UPDATE node graphs, lowered to VM bytecode.
- *
- * The returned value bundles the layout with the compiled program so the {@link ./EmitterRegistry.js}
- * can resolve render-attribute names to record offsets and pack the program into the arena.
- *
- * @param {object} params
- * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
- * @param {import("../graph/ParticleGraph.js").ParticleGraph} [params.spawn]
- * @param {import("../graph/ParticleGraph.js").ParticleGraph} [params.update]
- * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
- */
-export function create_particle_effect({ layout, spawn, update }) {
-    const program = compile_particle_effect({ spawn, update, layout });
-    return { layout, program };
-}
+import { compile_particle_effect } from "../graph/compile_particle_graph.js";
+
+/**
+ * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus SPAWN
+ * and UPDATE node graphs, lowered to VM bytecode.
+ *
+ * The returned value bundles the layout with the compiled program so the {@link ./EmitterRegistry.js}
+ * can resolve render-attribute names to record offsets and pack the program into the arena.
+ *
+ * @param {object} params
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
+ * @param {NodeGraph} [params.spawn]
+ * @param {NodeGraph} [params.update]
+ * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
+ */
+export function create_particle_effect({ layout, spawn, update }) {
+    const program = compile_particle_effect({ spawn, update, layout });
+    return { layout, program };
+}

package/src/shade/renderer/particles/shaders/chunk_particle_curve_animation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_curve_animation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_curve_animation.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;GAgBG;AACH,6CAFU,SAAS,CAO0C;0BA1BnC,oCAAoC"}
+{"version":3,"file":"chunk_particle_curve_animation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_curve_animation.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;GAgBG;AACH,6CAFU,SAAS,CAS0C;0BA5BnC,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_curve_animation.js

@@ -21,9 +21,11 @@ const CURVE_TABLE = ANIMATION_DATABASE_SPEC.get("animation_curves");
  *
  * @type {CodeChunk}
  */
-export const chunk_particle_curve_animation = CodeChunk.from(/* wgsl */ `
+export const chunk_particle_curve_animation = CodeChunk.from(
+    /* language=wgsl */
+    `
 fn particle_vm_sample_curve(handle : u32, t : f32) -> f32 {
     let header = ${CURVE_TABLE.marshalling_method_read}(&particle_curve_database, handle);
     return animation_curve_evaluate(t, &particle_curve_database, header);
 }
-`, [CURVE_TABLE.chunk_read, chunk_animation_curve_evaluate]);
+`, [CURVE_TABLE.chunk_read, chunk_animation_curve_evaluate]);

package/src/shade/renderer/particles/shaders/chunk_particle_lighting.d.ts

@@ -1,9 +1,9 @@
 /**
- * Pluggable lighting hook for the billboard fragment shader. `particle_apply_lighting(color, world,
- * normal)` returns the lit colour; the default is a pass-through (unlit / emissive).
+ * Pluggable lighting hook for the billboard fragment shader. `particle_apply_lighting(color, world, normal)`
+ * returns the lit colour; the default is a pass-through (unlit / emissive).
  *
- * The production feature swaps this for a chunk that binds {@link
- * ../../deferred/SHADING_LIGHT_RESOURCE_GROUP.js} and calls `shade_standard_material_direct` + IBL —
+ * The production feature swaps this for a chunk that binds
+ * {@link ../../deferred/SHADING_LIGHT_RESOURCE_GROUP.js} and calls `shade_standard_material_direct` + IBL —
  * i.e. billboards reuse the exact same lighting path as opaque surfaces when an emitter opts in via
  * its `lighting` flag. Keeping it a hook means unlit emitters compile without pulling in the whole
  * clustered-lighting resource group.

package/src/shade/renderer/particles/shaders/chunk_particle_lighting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_lighting.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_lighting.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,4CAFU,SAAS,CAMhB;0BAlBuB,oCAAoC"}
+{"version":3,"file":"chunk_particle_lighting.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_lighting.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,4CAFU,SAAS,CAQhB;0BApBuB,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_lighting.js

@@ -1,18 +1,20 @@
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 
 /**
- * Pluggable lighting hook for the billboard fragment shader. `particle_apply_lighting(color, world,
- * normal)` returns the lit colour; the default is a pass-through (unlit / emissive).
+ * Pluggable lighting hook for the billboard fragment shader. `particle_apply_lighting(color, world, normal)`
+ * returns the lit colour; the default is a pass-through (unlit / emissive).
  *
- * The production feature swaps this for a chunk that binds {@link
- * ../../deferred/SHADING_LIGHT_RESOURCE_GROUP.js} and calls `shade_standard_material_direct` + IBL —
+ * The production feature swaps this for a chunk that binds
+ * {@link ../../deferred/SHADING_LIGHT_RESOURCE_GROUP.js} and calls `shade_standard_material_direct` + IBL —
  * i.e. billboards reuse the exact same lighting path as opaque surfaces when an emitter opts in via
  * its `lighting` flag. Keeping it a hook means unlit emitters compile without pulling in the whole
  * clustered-lighting resource group.
  *
  * @type {CodeChunk}
  */
-export const chunk_particle_lighting_unlit = CodeChunk.from(/* wgsl */ `
+export const chunk_particle_lighting_unlit = CodeChunk.from(
+    /* language=wgsl */
+    `
 fn particle_apply_lighting(color : vec4<f32>, world_position : vec3<f32>, normal : vec3<f32>) -> vec4<f32> {
     return color;
 }

package/src/shade/renderer/particles/shaders/chunk_particle_render_math.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_render_math.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_render_math.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,yCAFU,SAAS,CAyFhB;0BAzGuB,oCAAoC"}
+{"version":3,"file":"chunk_particle_render_math.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_render_math.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,yCAFU,SAAS,CA2FhB;0BA3GuB,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_render_math.js

@@ -16,7 +16,9 @@ import { EMITTER_BLEND, EMITTER_PROJECTION } from "../data/PARTICLE_EMITTER_LAYO
  *
  * @type {CodeChunk}
  */
-export const chunk_particle_render_math = CodeChunk.from(/* wgsl */ `
+export const chunk_particle_render_math = CodeChunk.from(
+    /* language=wgsl */
+    `
 const PARTICLE_PROJ_BILLBOARD : u32 = ${EMITTER_PROJECTION.BILLBOARD}u;
 const PARTICLE_PROJ_STRETCHED : u32 = ${EMITTER_PROJECTION.STRETCHED}u;
 const PARTICLE_PROJ_HORIZONTAL : u32 = ${EMITTER_PROJECTION.HORIZONTAL}u;

package/src/shade/renderer/particles/shaders/shader_particle_emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_emit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;GAYG;AAEH,2CAHU,aAAa,CAGwB;AA6F/C,iDAIG;8BAhI2B,+BAA+B"}
+{"version":3,"file":"shader_particle_emit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;GAYG;AAEH,2CAHU,aAAa,CAGwB;AA+F/C,iDAIG;8BAlI2B,+BAA+B"}

package/src/shade/renderer/particles/shaders/shader_particle_emit.js

@@ -64,7 +64,9 @@ resources.createGroup()
     .addStorageBuffer("alive_out", WebGPUArray.u32, true)
     .addStorageBuffer("dead", WebGPUArray.u32, true)
     .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
-const body = CodeChunk.from(/* wgsl */ `
+const body = CodeChunk.from(
+    /* language=wgsl */
+    `
 const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
 const PARTICLE_USER_WORD_START : u32 = ${PARTICLE_RECORD_USER_WORD_START}u;
 const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;

package/src/shade/renderer/particles/shaders/shader_particle_finalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AA4BA,2DAWG;AAaH,2DAwBG;;8BA1E2B,+BAA+B;iDAIZ,+BAA+B"}
+{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AA4BA,2DAYG;AAaH,2DA0BG;;8BA7E2B,+BAA+B;iDAIZ,+BAA+B"}

package/src/shade/renderer/particles/shaders/shader_particle_finalize.js

@@ -29,7 +29,8 @@ reset_resources.createGroup().addStorageBuffer("counters", WebGPUArray.from(atom
 export const shader_particle_reset_counters = ComputeShader.from({
     label: "Particle Reset Counters",
     resources: reset_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(
+        /* language=wgsl */ `
 @compute @workgroup_size(1, 1, 1)
 fn main() {
     atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
@@ -53,7 +54,9 @@ indirect_resources.createGroup()
 export const shader_particle_build_indirect = ComputeShader.from({
     label: "Particle Build Indirect",
     resources: indirect_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(
+        /* language=wgsl */
+        `
 @compute @workgroup_size(1, 1, 1)
 fn main() {
     let alive = atomicLoad(&counters[${PARTICLE_COUNTER.ALIVE}u]);

package/src/shade/renderer/particles/shaders/shader_particle_render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_render.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_render.js"],"names":[],"mappings":"AA6JA;;;;;;;;;GASG;AACH;IAP4B,YAAY,GAA7B,MAAM;IACgB,YAAY,GAAlC,MAAM,GAAC,IAAI;IAEkB,aAAa;IAExC,wBAAwB,CAqBpC;;;;;;;;;;;;;;;;AAED,yFAAyF;AACzF,uEAAsD;yCA7Lb,iEAAiE;4CAO9D,sDAAsD"}
+{"version":3,"file":"shader_particle_render.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_render.js"],"names":[],"mappings":"AA8JA;;;;;;;;;GASG;AACH;IAP4B,YAAY,GAA7B,MAAM;IACgB,YAAY,GAAlC,MAAM,GAAC,IAAI;IAEkB,aAAa;IAExC,wBAAwB,CA2BpC;;;;;;;;;;;;;;;;AAED,yFAAyF;AACzF,uEAAsD;yCApMb,iEAAiE;4CAO9D,sDAAsD"}