@woosh/meep-engine 3.14.4 → 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/vm/chunk_particle_vm.js

@@ -33,7 +33,7 @@ import { VM_BUILTIN, VM_OP, VM_RANDOM_MODE } from "../isa/ParticleVMISA.js";
 
 const R = PARTICLE_VM_REGISTER_COUNT;
 
-const source = /* wgsl */ `
+const source = /* language=wgsl */ `
 const PARTICLE_VM_REGISTER_COUNT : u32 = ${R}u;
 const PARTICLE_VM_MAX_INSTRUCTIONS : u32 = ${PARTICLE_VM_MAX_INSTRUCTIONS}u;
 const PARTICLE_VM_TWO_PI : f32 = 6.28318530717958647692;

package/src/shade/renderer/scene/SkinnedMesh.d.ts

@@ -28,6 +28,17 @@
  * see {@link chunk_skin_blend_mesh_local} for why it goes into each
  * matrix rather than onto the blended position.
  *
+ * **`transform_global` on a skinned mesh is the engine's, not the
+ * asset's.** It cancels out of the rendered position, so glTF declares
+ * it meaningless — and the one meaning it does have is the frame the
+ * clone's vertices are written in, which the fold above requires to be
+ * rigid against the skin. {@link GPUAnimationManager#register_skin}
+ * therefore overwrites it, by way of
+ * {@link skin_normalize_mesh_frame}, with the skin's own bind
+ * transform. Whatever the file put there is discarded, and anything
+ * reading this expecting the file's value is reading the wrong thing.
+ * See `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ *
  * The mesh's **skin id** — a row in a GPU table — lives in
  * {@link GPUMeshSkinningContext} and nowhere else. The CPU-side
  * {@link Skin} it was registered with is a different thing, pure data

package/src/shade/renderer/scene/SkinnedMesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SkinnedMesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/SkinnedMesh.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH;IAEI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAFU,OAAK,IAAI,CAEP;IAEZ;;OAEG;IACH,SAFa,WAAW,CAMvB;IAED;;OAEG;IACH,YAFW,WAAW,QAYrB;IA4CL;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;qBAnJoB,WAAW"}
+{"version":3,"file":"SkinnedMesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/SkinnedMesh.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH;IAEI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAFU,OAAK,IAAI,CAEP;IAEZ;;OAEG;IACH,SAFa,WAAW,CAMvB;IAED;;OAEG;IACH,YAFW,WAAW,QAYrB;IA4CL;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;qBA9JoB,WAAW"}

package/src/shade/renderer/scene/SkinnedMesh.js

@@ -31,6 +31,17 @@ import { Mesh } from "./Mesh.js";
  * see {@link chunk_skin_blend_mesh_local} for why it goes into each
  * matrix rather than onto the blended position.
  *
+ * **`transform_global` on a skinned mesh is the engine's, not the
+ * asset's.** It cancels out of the rendered position, so glTF declares
+ * it meaningless — and the one meaning it does have is the frame the
+ * clone's vertices are written in, which the fold above requires to be
+ * rigid against the skin. {@link GPUAnimationManager#register_skin}
+ * therefore overwrites it, by way of
+ * {@link skin_normalize_mesh_frame}, with the skin's own bind
+ * transform. Whatever the file put there is discarded, and anything
+ * reading this expecting the file's value is reading the wrong thing.
+ * See `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ *
  * The mesh's **skin id** — a row in a GPU table — lives in
  * {@link GPUMeshSkinningContext} and nowhere else. The CPU-side
  * {@link Skin} it was registered with is a different thing, pure data

package/src/shade/renderer/shader/chunk/geometry/quaternion/dual/chunk_dual_quat_from_m4.d.ts

@@ -1,7 +1,37 @@
 /**
- * @see https://github.com/KosRud/DQ-skinning-for-Unity/blob/9d096e2db57677f0f67a823432f8b735ad622404/Code/DQ%20skinning/Shaders/Compute/DQ.cginc#L59
- * @see http://www.euclideanspace.com/maths/geometry/rotations/conversions/matrixToQuaternion/index.htm
- * Alternative Method by Christian
+ * A rigid transform as a dual quaternion: the rotation in the real part, the translation carried in
+ * the dual part as `0.5 · t · real`.
+ *
+ * The matrix's upper 3×3 is read as a rotation and its fourth column as a translation. Anything else
+ * in the matrix — a scale, a shear — has nowhere to go, and comes back as neither itself nor a
+ * warning: see {@link m4_rigidity_defect} for the number that says so and
+ * `renderer/animation/SKINNING_FRAME_PLAN.md` for the frame arrangement that keeps a skinning
+ * matrix rigid in the first place.
+ *
+ * ## Why the rotation goes through `quat_from_m3`
+ *
+ * This used to take all four quaternion components as `sqrt(max(0, 1 ± m00 ± m11 ± m22)) · 0.5` and
+ * recover their signs from the off-diagonal differences. That is exact in exact arithmetic and
+ * badly conditioned in floating point: near the identity three of those radicands are near zero, and
+ * a square root turns an input error of `e` into an output error of `sqrt(e)`. A matrix that is the
+ * identity to `1e-6` — which is what a skin's folded joint matrices are at bind pose — yielded
+ * quaternion components off by `9e-4`, an angular error of `1.8e-3` radians, and a millimetre and a
+ * half of vertex displacement on a 1.66 m character. Measured, on `Michelle.glb`.
+ *
+ * {@link chunk_quat_from_m3} is Shoemake's branch-picking form: it computes whichever component the
+ * matrix's diagonal says is largest, and derives the other three from it by division. Every branch
+ * divides by at least 2, so the components come out **linear** in the input error rather than as its
+ * square root — the same `1e-6` matrix now gives `2.5e-7`, three and a half orders better — and the
+ * near-180° case, where the trace form is ill-conditioned for the opposite reason, is a branch of its
+ * own. One `sqrt` and a reciprocal where there were four `sqrt`s.
+ *
+ * The normalize stays, on top of that. It is a no-op for the orthonormal input this is meant to be
+ * given; what it earns its rsqrt for is the input that is not — a degenerate 3×3 leaves
+ * `quat_from_m3` on a branch whose answer has length 0.5, and this is what keeps the documented
+ * postcondition, a unit real part, true anyway.
+ *
+ * @see https://gitlab.com/libeigen/eigen/-/blob/master/Eigen/src/Geometry/Quaternion.h#L813
+ * @type {CodeChunk}
  */
 export const chunk_dual_quat_from_m4: CodeChunk;
 import { CodeChunk } from "../../../../compiler/CodeChunk.js";

package/src/shade/renderer/shader/chunk/geometry/quaternion/dual/chunk_dual_quat_from_m4.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_dual_quat_from_m4.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/shader/chunk/geometry/quaternion/dual/chunk_dual_quat_from_m4.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,gDA2BC;0BApCyB,mCAAmC"}
+{"version":3,"file":"chunk_dual_quat_from_m4.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/shader/chunk/geometry/quaternion/dual/chunk_dual_quat_from_m4.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,sCAFU,SAAS,CAoBlB;0BAzDyB,mCAAmC"}