@woosh/meep-engine 3.14.6 → 3.16.0

package/src/shade/renderer/particles/data/particle_header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_header.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/particle_header.js"],"names":[],"mappings":"AAuCA;;;;;GAKG;AACH,qDAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;GAIG;AACH,kDAJW,MAAM,cACN,MAAM,GACJ,MAAM,CASlB;AAED;;;GAGG;AACH,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;GAGG;AACH,mDAHW,MAAM,GACJ,MAAM,CAIlB;AA5ED;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qBAAqB;AACrB,2CADW,MAAM,CACkC;AAEnD,qBAAqB;AACrB,+CADW,MAAM,CACkC;AAEnD,qBAAqB;AACrB,8CADW,MAAM,CACqC;AAEtD;;;GAGG;AACH,wCAFU,MAAM,CAE2B;AA4C3C;;;;GAIG;AACH,oCAFU,SAAS,CAkBhB;0BArGuB,oCAAoC"}

package/src/shade/renderer/particles/data/particle_header.js

@@ -0,0 +1,103 @@
+import { assert } from "../../../../core/assert.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Encoding of a particle record's header word: which emitter row the particle belongs to, and the
+ * generation that row had when the particle was born.
+ *
+ * The row alone is not enough. Rows are reused — a removed emitter's row goes to the next emitter
+ * added — and the particles of the removed one are still in flight, carrying that row. Without a
+ * generation they would adopt the newcomer: run its program, follow its node, draw with its atlas.
+ * With one, the simulate pass compares the particle's generation against the row's and kills any
+ * particle whose emitter has gone, within a frame of it going. A freed row is zero-filled by the
+ * table, and a live row's generation is never zero, so the check also covers the window between a
+ * removal and the next add.
+ *
+ * Layout: low 16 bits = emitter row, high 16 bits = generation. Sixteen bits of row is the same
+ * bound the emitter table's page limit implies; sixteen bits of generation wraps after 65535
+ * reuses of one row, which at a removal per frame is eighteen minutes of churn on one row before a
+ * collision is even possible, and the colliding particle would have to have lived that long.
+ *
+ * The WGSL side is {@link chunk_particle_header}; the two must agree, so both read the constants
+ * below.
+ */
+
+/** @type {number} */
+export const PARTICLE_HEADER_EMITTER_MASK = 0xFFFF;
+
+/** @type {number} */
+export const PARTICLE_HEADER_GENERATION_SHIFT = 16;
+
+/** @type {number} */
+export const PARTICLE_HEADER_GENERATION_MASK = 0xFFFF;
+
+/**
+ * The first generation a row is given. Zero is what a freed row reads as, so it is never live.
+ * @type {number}
+ */
+export const PARTICLE_GENERATION_FIRST = 1;
+
+/**
+ * The generation that follows `generation` when a row is reused — skips zero on wrap.
+ *
+ * @param {number} generation
+ * @returns {number}
+ */
+export function particle_generation_next(generation) {
+    const next = (generation + 1) & PARTICLE_HEADER_GENERATION_MASK;
+
+    return next === 0 ? PARTICLE_GENERATION_FIRST : next;
+}
+
+/**
+ * @param {number} emitter_row
+ * @param {number} generation
+ * @returns {number} the packed header word
+ */
+export function particle_header_pack(emitter_row, generation) {
+    assert.isNonNegativeInteger(emitter_row, 'emitter_row');
+    assert.lessThanOrEqual(emitter_row, PARTICLE_HEADER_EMITTER_MASK, 'emitter_row');
+    assert.isNonNegativeInteger(generation, 'generation');
+    assert.lessThanOrEqual(generation, PARTICLE_HEADER_GENERATION_MASK, 'generation');
+
+    return ((generation << PARTICLE_HEADER_GENERATION_SHIFT) | emitter_row) >>> 0;
+}
+
+/**
+ * @param {number} header
+ * @returns {number} emitter row
+ */
+export function particle_header_emitter(header) {
+    return header & PARTICLE_HEADER_EMITTER_MASK;
+}
+
+/**
+ * @param {number} header
+ * @returns {number} generation
+ */
+export function particle_header_generation(header) {
+    return (header >>> PARTICLE_HEADER_GENERATION_SHIFT) & PARTICLE_HEADER_GENERATION_MASK;
+}
+
+/**
+ * The same encoding, for every pass that reads a record's header word.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_header = CodeChunk.from(/* language=wgsl */ `
+const PARTICLE_HEADER_EMITTER_MASK : u32 = ${PARTICLE_HEADER_EMITTER_MASK}u;
+const PARTICLE_HEADER_GENERATION_SHIFT : u32 = ${PARTICLE_HEADER_GENERATION_SHIFT}u;
+const PARTICLE_HEADER_GENERATION_MASK : u32 = ${PARTICLE_HEADER_GENERATION_MASK}u;
+
+fn particle_header_pack(emitter_row : u32, generation : u32) -> u32 {
+    return (generation << PARTICLE_HEADER_GENERATION_SHIFT) | (emitter_row & PARTICLE_HEADER_EMITTER_MASK);
+}
+
+fn particle_header_emitter(header : u32) -> u32 {
+    return header & PARTICLE_HEADER_EMITTER_MASK;
+}
+
+fn particle_header_generation(header : u32) -> u32 {
+    return (header >> PARTICLE_HEADER_GENERATION_SHIFT) & PARTICLE_HEADER_GENERATION_MASK;
+}
+`);

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

@@ -0,0 +1,179 @@
+/**
+ * Writing a node group's body in JavaScript.
+ *
+ * A group like `simplex3` is two hundred nodes. Assembling that by hand — create a node, look up a
+ * port id, create a connection, repeat — is unreadable and unreviewable, and the thing being written
+ * is an expression, which JavaScript already spells perfectly well. So this builds the graph out of
+ * calls: `g.mul(g.sub(x, low), scale)` creates three nodes and two wires, and reads as what it
+ * computes.
+ *
+ * Every stock operation that takes no parameters of its own is a method here, taken from the library
+ * rather than listed — a type added to it is callable the same day. The rest — `const`, `swizzle`,
+ * `random`, `curve` and the attribute nodes — need a parameter and are reached through
+ * {@link #op}, or through the shorthands below where there is an obvious one.
+ *
+ * A number where a value is expected becomes a literal, so `g.mul(v, 0.5)` is what it looks like.
+ *
+ * Each mention of a number is its own node, deliberately. Sharing one would be fewer instructions and
+ * a great deal worse: a value's registers are held from where it is produced to its last reader, so a
+ * `2.0` shared between the first line of a body and the last would pin its slots across the whole
+ * group. The register file is the scarce thing here — see
+ * {@link ../ParticleConstants.js PARTICLE_VM_REGISTER_SLOTS} — and the constant pool interns the
+ * words anyway, so what the duplication costs is one `LOAD_CONST` and nothing else.
+ *
+ * ## What comes back
+ *
+ * Every call returns a **port reference** — a node and one of its output ports — which is the thing
+ * wires are made between. Multi-output nodes (another group) hand back a map of them.
+ */
+export class ParticleGroupBuilder {
+    /**
+     * @param {object} options see {@link ParticleNodeGroup.create}
+     */
+    constructor(options: object);
+    /**
+     * The group being built.
+     * @type {ParticleNodeGroup}
+     */
+    group: ParticleNodeGroup;
+    /**
+     * The group's inputs, by name: what the body reads its arguments from.
+     * @type {Object<string, {node: NodeInstance, port: Port}>}
+     */
+    in: {
+        [x: string]: {
+            node: NodeInstance;
+            port: Port;
+        };
+    };
+    /**
+     * Create one node of a stock type, wired to the values given.
+     *
+     * Arguments are matched to the type's input ports in declaration order — which is the order the
+     * library declares its operands in, so `op("mad", [a, b, c])` is `a * b + c`. A number stands in
+     * for a literal of that number.
+     *
+     * @param {string} type node type name
+     * @param {Array<{node: NodeInstance, port: Port}|number>} [args] one per input port, in order
+     * @param {object} [parameters] overrides on top of the type's defaults
+     * @returns {{node: NodeInstance, port: Port}} the node's `out` port
+     */
+    op(type: string, args?: (number | {
+        node: NodeInstance;
+        port: Port;
+    })[], parameters?: object): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /**
+     * Create one instance of another group, wired to the values given by name.
+     *
+     * How a group is built out of groups: `curl3` is twelve `simplex3`s and the arithmetic between
+     * them, and says so.
+     *
+     * @param {ParticleNodeGroup} group
+     * @param {Object<string, {node: NodeInstance, port: Port}|number>} args value per input port name
+     * @returns {Object<string, {node: NodeInstance, port: Port}>} a reference per output port name
+     */
+    call(group: ParticleNodeGroup, args?: {
+        [x: string]: number | {
+            node: NodeInstance;
+            port: Port;
+        };
+    }): {
+        [x: string]: {
+            node: NodeInstance;
+            port: Port;
+        };
+    };
+    /**
+     * A literal. One number is a scalar; several are a vector as wide as there are of them.
+     *
+     * @param {...number} components
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    f(...components: number[]): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /**
+     * Pick and reorder lanes, spelled the way the assembly spells it.
+     *
+     * @param {{node: NodeInstance, port: Port}|number} value
+     * @param {string} pattern one to four of `xyzw`
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    swz(value: {
+        node: NodeInstance;
+        port: Port;
+    } | number, pattern: string): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    x(v: {
+        node: NodeInstance;
+        port: Port;
+    } | number): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    y(v: {
+        node: NodeInstance;
+        port: Port;
+    } | number): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    z(v: {
+        node: NodeInstance;
+        port: Port;
+    } | number): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    w(v: {
+        node: NodeInstance;
+        port: Port;
+    } | number): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /**
+     * A value read as a builtin the host provides.
+     *
+     * @param {number} id a {@link ../isa/ParticleVMISA.js VM_BUILTIN}
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    builtin(id: number): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /**
+     * Expose a value as one of the group's outputs.
+     *
+     * @param {string} name one of the group's declared output ports
+     * @param {{node: NodeInstance, port: Port}|number} value
+     * @returns {void}
+     */
+    out(name: string, value: number | {
+        node: NodeInstance;
+        port: Port;
+    }): void;
+    /**
+     * Finish the group, having checked that it is one.
+     *
+     * Everything caught here is caught at the moment the library loads, which is where a broken
+     * built-in group should fail: a group missing an output is a node whose result is nothing, and
+     * finding that out at the far end of a compile in somebody's editor is finding it out too late.
+     *
+     * @returns {ParticleNodeGroup}
+     */
+    build(): ParticleNodeGroup;
+    #private;
+}
+import { ParticleNodeGroup } from "./ParticleNodeGroup.js";
+//# sourceMappingURL=ParticleGroupBuilder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleGroupBuilder.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleGroupBuilder.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAaI;;OAEG;IACH,qBAFW,MAAM,EAoBhB;IAjCD;;;OAGG;IACH,OAFU,iBAAiB,CAErB;IAEN;;;OAGG;IACH;YAFiB,MAAM,GAAE;YAAC,IAAI,eAAe;YAAC,IAAI,OAAM;SAAC;MAEjD;IAyBR;;;;;;;;;;;OAWG;IACH,SALW,MAAM;;;uBAEN,MAAM;;;MAoBhB;IAED;;;;;;;;;OASG;IACH,YAJW,iBAAiB;;;;;;;;;;MA0B3B;IAED;;;;;OAKG;IACH,iBAHc,MAAM,KACP;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAI5C;IAED;;;;;;OAMG;IACH,WAJW;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,WACvC,MAAM,GACJ;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAU5C;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAI5C;IAED;;;;;;OAMG;IACH,UAJW,MAAM;;;QAEJ,IAAI,CAehB;IAED;;;;;;;;OAQG;IACH,SAFa,iBAAiB,CA+B7B;;CAgDJ;kCA7SiC,wBAAwB"}

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

@@ -0,0 +1,303 @@
+import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
+import { ParticleNodeGroup } from "./ParticleNodeGroup.js";
+import { get_particle_node_description, PARTICLE_NODE_OUTPUT_PORT } from "./ParticleNodeRegistry.js";
+import {
+    particle_node_default_parameters,
+    PARTICLE_NODES_WITHOUT_PARAMETERS,
+} from "./particle_node_parameters.js";
+
+/**
+ * Writing a node group's body in JavaScript.
+ *
+ * A group like `simplex3` is two hundred nodes. Assembling that by hand — create a node, look up a
+ * port id, create a connection, repeat — is unreadable and unreviewable, and the thing being written
+ * is an expression, which JavaScript already spells perfectly well. So this builds the graph out of
+ * calls: `g.mul(g.sub(x, low), scale)` creates three nodes and two wires, and reads as what it
+ * computes.
+ *
+ * Every stock operation that takes no parameters of its own is a method here, taken from the library
+ * rather than listed — a type added to it is callable the same day. The rest — `const`, `swizzle`,
+ * `random`, `curve` and the attribute nodes — need a parameter and are reached through
+ * {@link #op}, or through the shorthands below where there is an obvious one.
+ *
+ * A number where a value is expected becomes a literal, so `g.mul(v, 0.5)` is what it looks like.
+ *
+ * Each mention of a number is its own node, deliberately. Sharing one would be fewer instructions and
+ * a great deal worse: a value's registers are held from where it is produced to its last reader, so a
+ * `2.0` shared between the first line of a body and the last would pin its slots across the whole
+ * group. The register file is the scarce thing here — see
+ * {@link ../ParticleConstants.js PARTICLE_VM_REGISTER_SLOTS} — and the constant pool interns the
+ * words anyway, so what the duplication costs is one `LOAD_CONST` and nothing else.
+ *
+ * ## What comes back
+ *
+ * Every call returns a **port reference** — a node and one of its output ports — which is the thing
+ * wires are made between. Multi-output nodes (another group) hand back a map of them.
+ */
+export class ParticleGroupBuilder {
+    /**
+     * The group being built.
+     * @type {ParticleNodeGroup}
+     */
+    group;
+
+    /**
+     * The group's inputs, by name: what the body reads its arguments from.
+     * @type {Object<string, {node: NodeInstance, port: Port}>}
+     */
+    in = {};
+
+    /**
+     * @param {object} options see {@link ParticleNodeGroup.create}
+     */
+    constructor(options) {
+        this.group = ParticleNodeGroup.create(options);
+
+        for (const port of this.group.description.inPorts) {
+            // the input block's port of the same name: inside the group, an input is read from
+            this.in[port.name] = {
+                node: this.group.inputNode,
+                port: this.group.inputNode.description.findPortByNameAndDirection(port.name, PortDirection.Out),
+            };
+        }
+
+        for (const name of PARTICLE_NODES_WITHOUT_PARAMETERS) {
+            if (this[name] !== undefined) {
+                continue;
+            }
+
+            this[name] = (...args) => this.op(name, args);
+        }
+    }
+
+    /**
+     * Create one node of a stock type, wired to the values given.
+     *
+     * Arguments are matched to the type's input ports in declaration order — which is the order the
+     * library declares its operands in, so `op("mad", [a, b, c])` is `a * b + c`. A number stands in
+     * for a literal of that number.
+     *
+     * @param {string} type node type name
+     * @param {Array<{node: NodeInstance, port: Port}|number>} [args] one per input port, in order
+     * @param {object} [parameters] overrides on top of the type's defaults
+     * @returns {{node: NodeInstance, port: Port}} the node's `out` port
+     */
+    op(type, args = [], parameters = {}) {
+        const description = get_particle_node_description(type);
+
+        const node = this.#create(description, parameters);
+
+        const ports = description.inPorts;
+
+        if (args.length !== ports.length) {
+            throw new Error(
+                `'${type}' takes ${ports.length} input${ports.length === 1 ? "" : "s"} `
+                + `(${ports.map(port => port.name).join(", ") || "none"}), given ${args.length}.`
+            );
+        }
+
+        ports.forEach((port, index) => this.#wire(this.#value(args[index]), node, port));
+
+        return { node, port: description.findPortByNameAndDirection(PARTICLE_NODE_OUTPUT_PORT, PortDirection.Out) };
+    }
+
+    /**
+     * Create one instance of another group, wired to the values given by name.
+     *
+     * How a group is built out of groups: `curl3` is twelve `simplex3`s and the arithmetic between
+     * them, and says so.
+     *
+     * @param {ParticleNodeGroup} group
+     * @param {Object<string, {node: NodeInstance, port: Port}|number>} args value per input port name
+     * @returns {Object<string, {node: NodeInstance, port: Port}>} a reference per output port name
+     */
+    call(group, args = {}) {
+        const description = group.description;
+
+        const node = this.#create(description, {});
+
+        for (const port of description.inPorts) {
+            const argument = args[port.name];
+
+            if (argument === undefined) {
+                throw new Error(`Group '${group.name}' has an input '${port.name}' and nothing was given for it.`);
+            }
+
+            this.#wire(this.#value(argument), node, port);
+        }
+
+        const result = {};
+
+        for (const port of description.outPorts) {
+            result[port.name] = { node, port };
+        }
+
+        return result;
+    }
+
+    /**
+     * A literal. One number is a scalar; several are a vector as wide as there are of them.
+     *
+     * @param {...number} components
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    f(...components) {
+        return this.op("const", [], { value: components.slice() });
+    }
+
+    /**
+     * Pick and reorder lanes, spelled the way the assembly spells it.
+     *
+     * @param {{node: NodeInstance, port: Port}|number} value
+     * @param {string} pattern one to four of `xyzw`
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    swz(value, pattern) {
+        const lanes = Array.from(pattern).map(lane => "xyzw".indexOf(lane));
+
+        if (lanes.length === 0 || lanes.some(lane => lane === -1)) {
+            throw new Error(`'${pattern}' is not a swizzle: one to four of x, y, z, w.`);
+        }
+
+        return this.op("swizzle", [value], { pattern: lanes });
+    }
+
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    x(v) {
+        return this.swz(v, "x");
+    }
+
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    y(v) {
+        return this.swz(v, "y");
+    }
+
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    z(v) {
+        return this.swz(v, "z");
+    }
+
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    w(v) {
+        return this.swz(v, "w");
+    }
+
+    /**
+     * A value read as a builtin the host provides.
+     *
+     * @param {number} id a {@link ../isa/ParticleVMISA.js VM_BUILTIN}
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    builtin(id) {
+        return this.op("builtin", [], { id });
+    }
+
+    /**
+     * Expose a value as one of the group's outputs.
+     *
+     * @param {string} name one of the group's declared output ports
+     * @param {{node: NodeInstance, port: Port}|number} value
+     * @returns {void}
+     */
+    out(name, value) {
+        const outputNode = this.group.outputNode;
+
+        const port = outputNode.description.findPortByNameAndDirection(name, PortDirection.In);
+
+        if (port === undefined) {
+            throw new Error(
+                `Group '${this.group.name}' has no output called '${name}'. It has: `
+                + `${this.group.outputs.map(o => o.name).join(", ") || "none"}.`
+            );
+        }
+
+        this.#wire(this.#value(value), outputNode, port);
+    }
+
+    /**
+     * Finish the group, having checked that it is one.
+     *
+     * Everything caught here is caught at the moment the library loads, which is where a broken
+     * built-in group should fail: a group missing an output is a node whose result is nothing, and
+     * finding that out at the far end of a compile in somebody's editor is finding it out too late.
+     *
+     * @returns {ParticleNodeGroup}
+     */
+    build() {
+        const group = this.group;
+
+        for (const port of group.outputNode.description.inPorts) {
+            const wired = group.outputNode.getEndpoint(port.id).inConnections.length;
+
+            if (wired !== 1) {
+                throw new Error(
+                    `Group '${group.name}' output '${port.name}' has ${wired} sources; it takes exactly one.`
+                );
+            }
+        }
+
+        for (const node of group.graph.getNodes()) {
+            if (node === group.inputNode || node === group.outputNode) {
+                continue;
+            }
+
+            for (const port of node.description.inPorts) {
+                if (node.getEndpoint(port.id).inConnections.length !== 1) {
+                    throw new Error(
+                        `Group '${group.name}': input '${port.name}' of a '${node.description.name}' `
+                        + "is not wired to exactly one source."
+                    );
+                }
+            }
+        }
+
+        return group;
+    }
+
+    /**
+     * @param {ParticleNodeDescription} description
+     * @param {object} parameters
+     * @returns {NodeInstance}
+     */
+    #create(description, parameters) {
+        const graph = this.group.graph;
+
+        const node = graph.getNodeSafe(graph.createNode(description));
+
+        // the type's own defaults underneath, so a body written before a type gained a parameter
+        // still builds a node that compiles
+        node.setParameters({
+            ...(description.isParticleGroupNodeDescription === true
+                ? {}
+                : particle_node_default_parameters(description.name)),
+            ...parameters,
+        });
+
+        return node;
+    }
+
+    /**
+     * @param {{node: NodeInstance, port: Port}|number} value
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    #value(value) {
+        if (typeof value === "number") {
+            return this.f(value);
+        }
+
+        if (value === undefined || value === null || value.node === undefined || value.port === undefined) {
+            throw new Error(`Group '${this.group.name}': ${value} is not a value.`);
+        }
+
+        return value;
+    }
+
+    /**
+     * @param {{node: NodeInstance, port: Port}} source
+     * @param {NodeInstance} node
+     * @param {Port} port
+     */
+    #wire(source, node, port) {
+        this.group.graph.createConnection(source.node.id, source.port.id, node.id, port.id);
+    }
+}