@woosh/meep-engine 3.14.3 → 3.14.5

package/src/shade/renderer/particles/graph/compile_particle_graph.js

@@ -1,170 +1,205 @@
-import { PARTICLE_VM_REGISTER_COUNT } from "../ParticleConstants.js";
-import { ParticleAssembler } from "../isa/ParticleAssembler.js";
-import { PARTICLE_NODE_TYPES } from "./ParticleNodeRegistry.js";
-
-/**
- * Lower a single-phase {@link ../graph/ParticleGraph.js} into a VM instruction stream.
- *
- * The pipeline:
- * 1. Walk the graph from its sinks (attribute writes / kill), flattening it into an SSA-style value
- *    list in dependency order. Literal input values are materialised as constant-load values, and
- *    shared sub-expressions are evaluated once (DAG sharing via memoisation).
- * 2. Compute each value's last use.
- * 3. Linear-scan register allocation: registers are returned to the pool at a value's last use, so a
- *    result can reuse a just-consumed input register (VM ops read all sources before writing dst).
- * 4. Emit each value's opcode via its node definition.
- *
- * @param {import("./ParticleGraph.js").ParticleGraph} graph
- * @param {import("../isa/ParticleAssembler.js").InstructionStream} stream target section
- * @param {ParticleAssembler} asm assembler owning the shared constant pool
- * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout attribute schema
- */
-export function compile_particle_graph(graph, stream, asm, layout) {
-    const values = flatten(graph);
-    const last_use = compute_last_use(values);
-
-    const register_of = new Array(values.length).fill(-1);
-    const free = [];
-    for (let r = PARTICLE_VM_REGISTER_COUNT - 1; r >= 0; r--) {
-        free.push(r);
-    }
-
-    for (let i = 0; i < values.length; i++) {
-        const value = values[i];
-        const definition = PARTICLE_NODE_TYPES[value.type];
-
-        // Capture the current registers of all inputs before we recycle any of them.
-        const input_registers = {};
-        for (const port of Object.keys(value.inputs)) {
-            input_registers[port] = register_of[value.inputs[port]];
-        }
-
-        // Return registers whose owning value dies at this instruction (its last consumer).
-        const freed = new Set();
-        for (const port of Object.keys(value.inputs)) {
-            const source = value.inputs[port];
-            if (last_use[source] === i && register_of[source] >= 0 && !freed.has(source)) {
-                free.push(register_of[source]);
-                register_of[source] = -1;
-                freed.add(source);
-            }
-        }
-
-        let out;
-        if (definition.produces_value) {
-            if (free.length === 0) {
-                throw new Error(
-                    `Particle graph exceeds the VM register file (${PARTICLE_VM_REGISTER_COUNT} registers). ` +
-                    `Simplify the effect or split it.`
-                );
-            }
-            out = free.pop();
-            register_of[i] = out;
-        }
-
-        definition.emit(stream, {
-            in: (port) => input_registers[port],
-            out,
-            params: value.params,
-            layout,
-            asm,
-        });
-    }
-}
-
-/**
- * Compile a full effect (SPAWN + UPDATE) into a {@link ../isa/ParticleProgram.js}.
- *
- * @param {object} params
- * @param {import("./ParticleGraph.js").ParticleGraph} [params.spawn]
- * @param {import("./ParticleGraph.js").ParticleGraph} [params.update]
- * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
- * @returns {import("../isa/ParticleProgram.js").ParticleProgram}
- */
-export function compile_particle_effect({ spawn, update, layout }) {
-    const asm = new ParticleAssembler();
-    if (spawn !== undefined) {
-        compile_particle_graph(spawn, asm.spawn, asm, layout);
-    }
-    if (update !== undefined) {
-        compile_particle_graph(update, asm.update, asm, layout);
-    }
-    const program = asm.build();
-    program.validate();
-    return program;
-}
-
-/**
- * Flatten a graph into a dependency-ordered value list. Each value is
- * `{ type, params, inputs: { port -> value_index }, sink }`. The array order is a valid topological
- * order (every input has a lower index).
- * @param {import("./ParticleGraph.js").ParticleGraph} graph
- * @returns {Array<{type: string, params: object, inputs: object, sink: boolean}>}
- */
-function flatten(graph) {
-    const values = [];
-    const node_to_value = new Map();
-    const visiting = new Set();
-
-    function visit(node_id) {
-        if (node_to_value.has(node_id)) {
-            return node_to_value.get(node_id);
-        }
-        if (visiting.has(node_id)) {
-            throw new Error(`Cycle detected in particle graph at node ${node_id}`);
-        }
-        visiting.add(node_id);
-
-        const node = graph.nodes.get(node_id);
-        if (node === undefined) {
-            throw new Error(`Particle graph references missing node ${node_id}`);
-        }
-        const definition = PARTICLE_NODE_TYPES[node.type];
-
-        const inputs = {};
-        for (const port of definition.inputs) {
-            const source = node.inputs.get(port);
-            if (source === undefined) {
-                throw new Error(`Node ${node_id} (${node.type}) is missing a binding for input '${port}'`);
-            }
-            if (source.kind === "literal") {
-                const vid = values.length;
-                values.push({ type: "const", params: { value: source.value }, inputs: {}, sink: false });
-                inputs[port] = vid;
-            } else {
-                inputs[port] = visit(source.node);
-            }
-        }
-
-        const vid = values.length;
-        values.push({ type: node.type, params: node.params, inputs, sink: definition.is_sink });
-        node_to_value.set(node_id, vid);
-        visiting.delete(node_id);
-        return vid;
-    }
-
-    for (const [id, node] of graph.nodes) {
-        if (PARTICLE_NODE_TYPES[node.type].is_sink) {
-            visit(id);
-        }
-    }
-
-    return values;
-}
-
-/**
- * @param {Array} values
- * @returns {number[]} last_use[i] = highest index that consumes value i (or -1 if never consumed)
- */
-function compute_last_use(values) {
-    const last_use = new Array(values.length).fill(-1);
-    for (let i = 0; i < values.length; i++) {
-        for (const port of Object.keys(values[i].inputs)) {
-            const source = values[i].inputs[port];
-            if (i > last_use[source]) {
-                last_use[source] = i;
-            }
-        }
-    }
-    return last_use;
-}
+import { PARTICLE_VM_REGISTER_COUNT } from "../ParticleConstants.js";
+import { ParticleAssembler } from "../isa/ParticleAssembler.js";
+
+/**
+ * Lower a single-phase particle {@link ../../../../core/model/node-graph/NodeGraph.js NodeGraph}
+ * into a VM instruction stream.
+ *
+ * The graph describes one lifecycle phase (SPAWN or UPDATE) of a particle effect: nodes are
+ * {@link ParticleNodeDescription} instances, and every connection wires a producing node's `out`
+ * port to a consuming node's named input port.
+ *
+ * The pipeline:
+ * 1. Walk the graph from its sinks (attribute writes / kill), flattening it into an SSA-style value
+ *    list in dependency order. Shared sub-expressions are evaluated once (DAG sharing via
+ *    memoisation).
+ * 2. Compute each value's last use.
+ * 3. Linear-scan register allocation: registers are returned to the pool at a value's last use, so a
+ *    result can reuse a just-consumed input register (VM ops read all sources before writing dst).
+ * 4. Emit each value's opcode via its node description.
+ *
+ * @param {NodeGraph} graph
+ * @param {import("../isa/ParticleAssembler.js").InstructionStream} stream target section
+ * @param {ParticleAssembler} asm assembler owning the shared constant pool
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout attribute schema
+ */
+export function compile_particle_graph(graph, stream, asm, layout) {
+    const values = flatten(graph);
+    const last_use = compute_last_use(values);
+
+    const register_of = new Array(values.length).fill(-1);
+    const free = [];
+    for (let r = PARTICLE_VM_REGISTER_COUNT - 1; r >= 0; r--) {
+        free.push(r);
+    }
+
+    for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+        const description = value.description;
+
+        // Capture the current registers of all inputs before we recycle any of them.
+        const input_registers = {};
+        for (const port of Object.keys(value.inputs)) {
+            input_registers[port] = register_of[value.inputs[port]];
+        }
+
+        // Return registers whose owning value dies at this instruction (its last consumer).
+        const freed = new Set();
+        for (const port of Object.keys(value.inputs)) {
+            const source = value.inputs[port];
+            if (last_use[source] === i && register_of[source] >= 0 && !freed.has(source)) {
+                free.push(register_of[source]);
+                register_of[source] = -1;
+                freed.add(source);
+            }
+        }
+
+        let out;
+        if (!description.is_sink) {
+            if (free.length === 0) {
+                throw new Error(
+                    `Particle graph exceeds the VM register file (${PARTICLE_VM_REGISTER_COUNT} registers). ` +
+                    `Simplify the effect or split it.`
+                );
+            }
+            out = free.pop();
+            register_of[i] = out;
+        }
+
+        description.emit(stream, {
+            in: (port) => input_registers[port],
+            out,
+            parameters: value.parameters,
+            layout,
+            asm,
+        });
+    }
+}
+
+/**
+ * Compile a full effect (SPAWN + UPDATE) into a {@link ../isa/ParticleProgram.js}.
+ *
+ * @param {object} params
+ * @param {NodeGraph} [params.spawn]
+ * @param {NodeGraph} [params.update]
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
+ * @returns {import("../isa/ParticleProgram.js").ParticleProgram}
+ */
+export function compile_particle_effect({ spawn, update, layout }) {
+    const asm = new ParticleAssembler();
+    if (spawn !== undefined) {
+        compile_particle_graph(spawn, asm.spawn, asm, layout);
+    }
+    if (update !== undefined) {
+        compile_particle_graph(update, asm.update, asm, layout);
+    }
+    const program = asm.build();
+    program.validate();
+    return program;
+}
+
+/**
+ * Flatten a graph into a dependency-ordered value list. Each value is
+ * `{ description, parameters, inputs: { port_name -> value_index } }`. The array order is a valid
+ * topological order (every input has a lower index).
+ * @param {NodeGraph} graph
+ * @returns {Array<{description: ParticleNodeDescription, parameters: object, inputs: object}>}
+ */
+function flatten(graph) {
+    const values = [];
+    const node_to_value = new Map();
+    const visiting = new Set();
+
+    /**
+     * @param {NodeInstance} node
+     * @returns {number} index of the node's value
+     */
+    function visit(node) {
+        const existing = node_to_value.get(node.id);
+        if (existing !== undefined) {
+            return existing;
+        }
+        if (visiting.has(node.id)) {
+            throw new Error(`Cycle detected in particle graph at node ${node.id}`);
+        }
+        visiting.add(node.id);
+
+        const description = require_particle_description(node);
+
+        const inputs = {};
+        for (const port of description.inPorts) {
+            inputs[port.name] = visit(resolve_input(node, port));
+        }
+
+        const vid = values.length;
+        values.push({ description, parameters: node.parameters, inputs });
+        node_to_value.set(node.id, vid);
+        visiting.delete(node.id);
+        return vid;
+    }
+
+    for (const node of graph.getNodes()) {
+        if (require_particle_description(node).is_sink) {
+            visit(node);
+        }
+    }
+
+    return values;
+}
+
+/**
+ * @param {NodeInstance} node
+ * @returns {ParticleNodeDescription}
+ */
+function require_particle_description(node) {
+    const description = node.description;
+
+    if (description === null || description === undefined || description.isParticleNodeDescription !== true) {
+        throw new Error(`Node ${node.id} (${description}) is not a particle node, it cannot be compiled`);
+    }
+
+    return description;
+}
+
+/**
+ * Find the node driving one input port of a node.
+ * @param {NodeInstance} node
+ * @param {Port} port an input port of the node's description
+ * @returns {NodeInstance}
+ * @throws if the port has no source, or more than one
+ */
+function resolve_input(node, port) {
+    const endpoint = node.getEndpoint(port.id);
+
+    const connections = endpoint.inConnections;
+
+    if (connections.length === 0) {
+        throw new Error(`Node ${node.id} (${node.description.name}) is missing a binding for input '${port.name}'`);
+    }
+
+    if (connections.length > 1) {
+        throw new Error(
+            `Node ${node.id} (${node.description.name}) has ${connections.length} connections into input '${port.name}', ` +
+            `an input may have at most one`
+        );
+    }
+
+    return connections[0].source.instance;
+}
+
+/**
+ * @param {Array} values
+ * @returns {number[]} last_use[i] = highest index that consumes value i (or -1 if never consumed)
+ */
+function compute_last_use(values) {
+    const last_use = new Array(values.length).fill(-1);
+    for (let i = 0; i < values.length; i++) {
+        for (const port of Object.keys(values[i].inputs)) {
+            const source = values[i].inputs[port];
+            if (i > last_use[source]) {
+                last_use[source] = i;
+            }
+        }
+    }
+    return last_use;
+}

package/src/shade/renderer/particles/graph/particle_graph_authoring.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Authoring sugar for building particle effects on a plain
+ * {@link ../../../../core/model/node-graph/NodeGraph.js NodeGraph}.
+ *
+ * These are convenience wrappers only — the graph, its nodes and its connections are the standard
+ * node-graph model, so the editor, serializers and graph utilities all work on particle effects
+ * unchanged. Everything downstream (see {@link ./compile_particle_graph.js}) consumes `NodeGraph`
+ * directly and never sees these helpers.
+ */
+/**
+ * Add a node to a particle graph.
+ *
+ * @param {NodeGraph} graph
+ * @param {string} type a node type name registered in {@link ./ParticleNodeRegistry.js}
+ * @param {object} [parameters] static parameters (attribute name, builtin id, constant value, …)
+ * @returns {number} the new node instance id
+ */
+export function particle_node(graph: NodeGraph, type: string, parameters?: object): number;
+/**
+ * Bind an input port of a node to a source, replacing whatever was bound to it before.
+ *
+ * The source may be:
+ * - a node id (number) → that node's `out` port,
+ * - `{ node, port }` → an explicit port,
+ * - a number array → a literal `vec4`, materialised as a `const` node (scalar broadcast is NOT
+ *   applied; `[5]` means `[5,0,0,0]`).
+ *
+ * @param {NodeGraph} graph
+ * @param {number} node_id
+ * @param {string} port input port name
+ * @param {number|number[]|{node: number, port?: string}} source
+ * @returns {number} connection id
+ */
+export function particle_wire(graph: NodeGraph, node_id: number, port: string, source: number | number[] | {
+    node: number;
+    port?: string;
+}): number;
+/**
+ * Wrap a scalar or vector as a literal source (so it is unambiguous vs. a node id).
+ * @param {...number} components
+ * @returns {number[]}
+ */
+export function literal(...components: number[]): number[];
+//# sourceMappingURL=particle_graph_authoring.d.ts.map

package/src/shade/renderer/particles/graph/particle_graph_authoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_graph_authoring.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_graph_authoring.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,sDAJW,MAAM,eACN,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDALW,MAAM,QACN,MAAM;UACiB,MAAM;WAAS,MAAM;IAC1C,MAAM,CA2BlB;AA6BD;;;;GAIG;AACH,uCAHc,MAAM,KACP,MAAM,EAAE,CAIpB"}

package/src/shade/renderer/particles/graph/particle_graph_authoring.js

@@ -0,0 +1,108 @@
+import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
+import { get_particle_node_description, PARTICLE_NODE_OUTPUT_PORT } from "./ParticleNodeRegistry.js";
+
+/**
+ * Authoring sugar for building particle effects on a plain
+ * {@link ../../../../core/model/node-graph/NodeGraph.js NodeGraph}.
+ *
+ * These are convenience wrappers only — the graph, its nodes and its connections are the standard
+ * node-graph model, so the editor, serializers and graph utilities all work on particle effects
+ * unchanged. Everything downstream (see {@link ./compile_particle_graph.js}) consumes `NodeGraph`
+ * directly and never sees these helpers.
+ */
+
+/**
+ * Add a node to a particle graph.
+ *
+ * @param {NodeGraph} graph
+ * @param {string} type a node type name registered in {@link ./ParticleNodeRegistry.js}
+ * @param {object} [parameters] static parameters (attribute name, builtin id, constant value, …)
+ * @returns {number} the new node instance id
+ */
+export function particle_node(graph, type, parameters = {}) {
+    const description = get_particle_node_description(type);
+
+    const id = graph.createNode(description);
+
+    graph.getNodeSafe(id).setParameters(parameters);
+
+    return id;
+}
+
+/**
+ * Bind an input port of a node to a source, replacing whatever was bound to it before.
+ *
+ * The source may be:
+ * - a node id (number) → that node's `out` port,
+ * - `{ node, port }` → an explicit port,
+ * - a number array → a literal `vec4`, materialised as a `const` node (scalar broadcast is NOT
+ *   applied; `[5]` means `[5,0,0,0]`).
+ *
+ * @param {NodeGraph} graph
+ * @param {number} node_id
+ * @param {string} port input port name
+ * @param {number|number[]|{node: number, port?: string}} source
+ * @returns {number} connection id
+ */
+export function particle_wire(graph, node_id, port, source) {
+    const node = graph.getNodeSafe(node_id);
+
+    const port_object = node.description.findPortByNameAndDirection(port, PortDirection.In);
+
+    if (port_object === undefined) {
+        throw new Error(`Node ${node_id} (${node.description.name}) has no input port '${port}'`);
+    }
+
+    // snapshot before connecting, so the replacement is only committed once the new wiring holds
+    const previous = node.getEndpoint(port_object.id).inConnections;
+
+    const resolved = resolve_source(graph, source);
+
+    const connection_id = graph.createConnectionByPortName(
+        resolved.node, resolved.port,
+        node_id, port
+    );
+
+    // an input may have at most one source, so binding it again replaces rather than adds
+    for (const connection of previous) {
+        graph.deleteConnection(connection.id);
+    }
+
+    return connection_id;
+}
+
+/**
+ * @param {NodeGraph} graph
+ * @param {number|number[]|{node: number, port?: string}} source
+ * @returns {{node: number, port: string}}
+ */
+function resolve_source(graph, source) {
+    if (typeof source === "number") {
+        // Could be a node id or a scalar literal — ambiguous, so literals must use the array form.
+        return { node: source, port: PARTICLE_NODE_OUTPUT_PORT };
+    }
+
+    if (Array.isArray(source)) {
+        const value = [source[0] ?? 0, source[1] ?? 0, source[2] ?? 0, source[3] ?? 0];
+
+        return {
+            node: particle_node(graph, "const", { value }),
+            port: PARTICLE_NODE_OUTPUT_PORT
+        };
+    }
+
+    if (source !== null && typeof source === "object" && typeof source.node === "number") {
+        return { node: source.node, port: source.port ?? PARTICLE_NODE_OUTPUT_PORT };
+    }
+
+    throw new Error(`Invalid input source: ${JSON.stringify(source)}`);
+}
+
+/**
+ * Wrap a scalar or vector as a literal source (so it is unambiguous vs. a node id).
+ * @param {...number} components
+ * @returns {number[]}
+ */
+export function literal(...components) {
+    return components;
+}

package/src/shade/renderer/particles/isa/InstructionStream.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A single VM instruction stream (a SPAWN or UPDATE section). Instructions are appended in order;
+ * {@link toWords} flattens them to the packed `Uint32Array` the program consumes.
+ *
+ * Register usage is tracked as instructions are emitted so the assembler can report how many
+ * registers the program touches without a separate pass.
+ */
+export class InstructionStream {
+    /** @type {number[][]} */
+    instructions: number[][];
+    /** @type {number} highest register index referenced, plus one */
+    register_count: number;
+    /**
+     * Emit a raw instruction. Validates the opcode and tracks register usage. Prefer the typed
+     * helpers below where they exist — they document the non-obvious operand packing.
+     *
+     * @param {number} op
+     * @param {number} [dst]
+     * @param {number} [s0]
+     * @param {number} [s1]
+     * @param {number} [s2]
+     * @returns {InstructionStream} this, for chaining
+     */
+    emit(op: number, dst?: number, s0?: number, s1?: number, s2?: number): InstructionStream;
+    /**
+     * @param {number} dst
+     * @param {number} src
+     * @returns {InstructionStream}
+     */
+    mov(dst: number, src: number): InstructionStream;
+    /**
+     * @param {number} dst
+     * @param {number} constant_index
+     * @returns {InstructionStream}
+     */
+    loadConst(dst: number, constant_index: number): InstructionStream;
+    /**
+     * @param {number} dst
+     * @param {number} word_offset
+     * @param {number} component_count
+     * @returns {InstructionStream}
+     */
+    loadAttr(dst: number, word_offset: number, component_count: number): InstructionStream;
+    /**
+     * @param {number} src_register
+     * @param {number} word_offset
+     * @param {number} component_count
+     * @returns {InstructionStream}
+     */
+    storeAttr(src_register: number, word_offset: number, component_count: number): InstructionStream;
+    /**
+     * @param {number} dst
+     * @param {number} builtin_id
+     * @returns {InstructionStream}
+     */
+    loadBuiltin(dst: number, builtin_id: number): InstructionStream;
+    /**
+     * @param {number} condition_register
+     * @returns {InstructionStream}
+     */
+    kill(condition_register: number): InstructionStream;
+    /**
+     * @param {number} dst
+     * @param {number} mode
+     * @returns {InstructionStream}
+     */
+    random(dst: number, mode: number): InstructionStream;
+    /**
+     * @param {number} dst
+     * @param {number} curve_handle
+     * @param {number} t_register
+     * @returns {InstructionStream}
+     */
+    curve(dst: number, curve_handle: number, t_register: number): InstructionStream;
+    /**
+     * @returns {InstructionStream}
+     */
+    halt(): InstructionStream;
+    /**
+     * @returns {number}
+     */
+    get instruction_count(): number;
+    /**
+     * @returns {Uint32Array}
+     */
+    toWords(): Uint32Array;
+    #private;
+}
+//# sourceMappingURL=InstructionStream.d.ts.map

package/src/shade/renderer/particles/isa/InstructionStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstructionStream.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/InstructionStream.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH;IACI,yBAAyB;IACzB,cADW,MAAM,EAAE,EAAE,CACH;IAClB,iEAAiE;IACjE,gBADW,MAAM,CACE;IAUnB;;;;;;;;;;OAUG;IACH,SAPW,MAAM,QACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,iBAAiB,CAsB7B;IAID;;;;OAIG;IACH,SAJW,MAAM,OACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;OAIG;IACH,eAJW,MAAM,kBACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;OAKG;IACH,cALW,MAAM,eACN,MAAM,mBACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;OAKG;IACH,wBALW,MAAM,eACN,MAAM,mBACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;OAIG;IACH,iBAJW,MAAM,cACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;OAGG;IACH,yBAHW,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;OAIG;IACH,YAJW,MAAM,QACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;OAKG;IACH,WALW,MAAM,gBACN,MAAM,cACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;OAEG;IACH,QAFa,iBAAiB,CAI7B;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,WAFa,WAAW,CAWvB;;CACJ"}