@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -1,234 +1,240 @@
-import { PARTICLE_GRAPH_WARNING } from "./particle_graph_diagnostic.js";
-import { particle_type_conversion } from "./ParticleValueType.js";
-
-/**
- * Resolve the type of every value in a particle graph.
- *
- * A port's declared type says only that a value goes there; which value — one lane or four — is a
- * property of the node instance and what it is wired to. This walks the graph once, sources first,
- * and asks each node's {@link ./ParticleNodeDescription.js ParticleNodeDescription#infer_types}
- * what it produces given what it is fed. The result is what an editor shows on a port, what the
- * validator reports a mismatch from, and what the compiler runs its instructions at.
- *
- * It is tolerant where the compiler is not. An input with nothing on it, a node on a cycle, a
- * parameter that does not describe a width — each of those makes a type *unknown* (`null`) and the
- * walk carries on, because an author with three problems wants to see the types everywhere else.
- * Unknowns propagate only as far as they must: an `add` with one input bound is typed by that
- * input, and its empty port reads as the same type, which is exactly what the port is waiting for.
- *
- * ## What comes back
- *
- * For each node, its output type, and for each input port the type the node *reads* the input
- * as — which is the port's type as a view should show it. Where that differs from what is wired
- * into it, the wire carries a conversion, and {@link ParticleGraphTypes#diagnostics} says so:
- * a scalar broadcasts silently, a vector read narrower or wider is a warning naming the lanes.
- * See {@link ./ParticleValueType.js particle_type_conversion}.
- */
-
-/**
- * The types of one graph. See {@link infer_particle_graph_types}.
- */
-export class ParticleGraphTypes {
-    /**
-     * Node id -> the type of its `out` port; `null` for a sink, and for a node whose type could not
-     * be resolved.
-     * @type {Map<number, import("./ParticleValueType.js").ParticleValueType|null>}
-     */
-    #outputs = new Map();
-
-    /**
-     * Node id -> output port name -> the type of that port, for the nodes that have more than one.
-     *
-     * Only a {@link ./ParticleNodeGroup.js group} does: everything in the stock library produces one
-     * value, and the group that produces four is flattened away long before a compiler sees it. So
-     * this is here for what an editor draws, and {@link #output} falls back to the single answer for
-     * every node that has one.
-     *
-     * @type {Map<number, Object<string, import("./ParticleValueType.js").ParticleValueType|null>>}
-     */
-    #outputs_by_port = new Map();
-
-    /**
-     * Node id -> input port name -> the type the node reads that input as.
-     * @type {Map<number, Object<string, import("./ParticleValueType.js").ParticleValueType|null>>}
-     */
-    #inputs = new Map();
-
-    /**
-     * Every conversion worth a word, against the node whose input it happens on.
-     * @type {import("./particle_graph_diagnostic.js").ParticleGraphDiagnostic[]}
-     */
-    diagnostics = [];
-
-    /**
-     * @param {number} node_id
-     * @param {import("./ParticleValueType.js").ParticleValueType|null} output
-     * @param {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} inputs
-     * @param {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} [outputs]
-     *   one entry per output port, for a node with more than the usual one
-     */
-    set(node_id, output, inputs, outputs = undefined) {
-        this.#outputs.set(node_id, output);
-        this.#inputs.set(node_id, inputs);
-
-        if (outputs !== undefined) {
-            this.#outputs_by_port.set(node_id, outputs);
-        }
-    }
-
-    /**
-     * @param {number} node_id
-     * @returns {boolean}
-     */
-    has(node_id) {
-        return this.#outputs.has(node_id);
-    }
-
-    /**
-     * The type of a node's output, or `null` where there is none or it is unknown.
-     *
-     * @param {number} node_id
-     * @param {string} [port] which output, for a node with more than one
-     * @returns {import("./ParticleValueType.js").ParticleValueType|null}
-     */
-    output(node_id, port = undefined) {
-        if (port !== undefined) {
-            const by_port = this.#outputs_by_port.get(node_id);
-
-            if (by_port !== undefined && port in by_port) {
-                return by_port[port] ?? null;
-            }
-        }
-
-        return this.#outputs.get(node_id) ?? null;
-    }
-
-    /**
-     * The type a node reads one of its inputs as — the input port's type, as far as a view is
-     * concerned. `null` where it is unknown.
-     *
-     * @param {number} node_id
-     * @param {string} port input port name
-     * @returns {import("./ParticleValueType.js").ParticleValueType|null}
-     */
-    input(node_id, port) {
-        return this.#inputs.get(node_id)?.[port] ?? null;
-    }
-
-    /**
-     * Every input port of a node and the type each is read as.
-     *
-     * @param {number} node_id
-     * @returns {Object<string, import("./ParticleValueType.js").ParticleValueType|null>}
-     */
-    inputs(node_id) {
-        return this.#inputs.get(node_id) ?? {};
-    }
-}
-
-/**
- * @param {NodeGraph} graph
- * @param {object} [context]
- * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
- *   attribute schema; without it, attribute reads and writes are of unknown type
- * @returns {ParticleGraphTypes}
- */
-export function infer_particle_graph_types(graph, { layout } = {}) {
-    const types = new ParticleGraphTypes();
-
-    /** @type {Set<number>} nodes on the current path, so a cycle is noticed rather than followed */
-    const visiting = new Set();
-
-    /**
-     * @param {NodeInstance} node
-     * @returns {import("./ParticleValueType.js").ParticleValueType|null} the node's output type
-     */
-    function visit(node) {
-        if (types.has(node.id)) {
-            return types.output(node.id);
-        }
-
-        if (visiting.has(node.id)) {
-            // A cycle has no evaluation order and so no types; the validator says so in its own
-            // words, this only has to not hang.
-            return null;
-        }
-
-        const description = node.description;
-
-        if (description === null || description === undefined || description.isParticleNodeDescription !== true) {
-            types.set(node.id, null, {});
-
-            return null;
-        }
-
-        visiting.add(node.id);
-
-        /** @type {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} */
-        const sources = {};
-
-        for (const port of description.inPorts) {
-            const connections = node.getEndpoint(port.id).inConnections;
-
-            // exactly one source is a value; none or several is a problem the validator reports
-            if (connections.length !== 1) {
-                sources[port.name] = null;
-
-                continue;
-            }
-
-            const source = connections[0].source;
-
-            visit(source.instance);
-
-            // by name, because the source may be a node with several outputs and they need not
-            // agree — a decomposed vector's lanes are scalars however wide the vector was
-            sources[port.name] = types.output(source.instance.id, source.port.name);
-        }
-
-        visiting.delete(node.id);
-
-        const { output, outputs, inputs } = description.infer_types({
-            inputs: sources,
-            parameters: node.parameters,
-            layout,
-        });
-
-        // every declared input is answered for, so a view never finds a port missing from the map
-        /** @type {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} */
-        const read = {};
-
-        for (const port of description.inPorts) {
-            read[port.name] = inputs[port.name] ?? null;
-        }
-
-        types.set(node.id, description.is_sink ? null : output, read, description.is_sink ? undefined : outputs);
-
-        for (const port of description.inPorts) {
-            const from = sources[port.name];
-            const to = read[port.name];
-
-            if (from === null || to === null) {
-                continue;
-            }
-
-            const conversion = particle_type_conversion(from, to);
-
-            if (conversion !== null) {
-                types.diagnostics.push({
-                    node: node.id,
-                    message: `Input '${port.name}' ${conversion.message}`,
-                    severity: PARTICLE_GRAPH_WARNING,
-                });
-            }
-        }
-
-        return types.output(node.id);
-    }
-
-    for (const node of graph.getNodes()) {
-        visit(node);
-    }
-
-    return types;
-}
+import { PARTICLE_GRAPH_WARNING } from "./particle_graph_diagnostic.js";
+import { particle_type_conversion } from "./ParticleValueType.js";
+
+/**
+ * Resolve the type of every value in a particle graph.
+ *
+ * A port's declared type says only that a value goes there; which value — one lane or four — is a
+ * property of the node instance and what it is wired to. This walks the graph once, sources first,
+ * and asks each node's {@link ./ParticleNodeDescription.js ParticleNodeDescription#infer_types}
+ * what it produces given what it is fed. The result is what an editor shows on a port, what the
+ * validator reports a mismatch from, and what the compiler runs its instructions at.
+ *
+ * It is tolerant where the compiler is not. An input with nothing on it, a node on a cycle, a
+ * parameter that does not describe a width — each of those makes a type *unknown* (`null`) and the
+ * walk carries on, because an author with three problems wants to see the types everywhere else.
+ * Unknowns propagate only as far as they must: an `add` with one input bound is typed by that
+ * input, and its empty port reads as the same type, which is exactly what the port is waiting for.
+ *
+ * ## What comes back
+ *
+ * For each node, its output type, and for each input port the type the node *reads* the input
+ * as — which is the port's type as a view should show it. Where that differs from what is wired
+ * into it, the wire carries a conversion, and {@link ParticleGraphTypes#diagnostics} says so:
+ * a scalar broadcasts silently, a vector read narrower or wider is a warning naming the lanes.
+ * See {@link ./ParticleValueType.js particle_type_conversion}.
+ */
+
+/**
+ * The types of one graph. See {@link infer_particle_graph_types}.
+ */
+export class ParticleGraphTypes {
+    /**
+     * Node id -> the type of its `out` port; `null` for a sink, and for a node whose type could not
+     * be resolved.
+     * @type {Map<number, import("./ParticleValueType.js").ParticleValueType|null>}
+     */
+    #outputs = new Map();
+
+    /**
+     * Node id -> output port name -> the type of that port, for the nodes that have more than one.
+     *
+     * Only a {@link ./ParticleNodeGroup.js group} does: everything in the stock library produces one
+     * value, and the group that produces four is flattened away long before a compiler sees it. So
+     * this is here for what an editor draws, and {@link #output} falls back to the single answer for
+     * every node that has one.
+     *
+     * @type {Map<number, Object<string, import("./ParticleValueType.js").ParticleValueType|null>>}
+     */
+    #outputs_by_port = new Map();
+
+    /**
+     * Node id -> input port name -> the type the node reads that input as.
+     * @type {Map<number, Object<string, import("./ParticleValueType.js").ParticleValueType|null>>}
+     */
+    #inputs = new Map();
+
+    /**
+     * Every conversion worth a word, against the node whose input it happens on.
+     * @type {import("./particle_graph_diagnostic.js").ParticleGraphDiagnostic[]}
+     */
+    diagnostics = [];
+
+    /**
+     * @param {number} node_id
+     * @param {import("./ParticleValueType.js").ParticleValueType|null} output
+     * @param {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} inputs
+     * @param {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} [outputs]
+     *   one entry per output port, for a node with more than the usual one
+     */
+    set(node_id, output, inputs, outputs = undefined) {
+        this.#outputs.set(node_id, output);
+        this.#inputs.set(node_id, inputs);
+
+        if (outputs !== undefined) {
+            this.#outputs_by_port.set(node_id, outputs);
+        }
+    }
+
+    /**
+     * @param {number} node_id
+     * @returns {boolean}
+     */
+    has(node_id) {
+        return this.#outputs.has(node_id);
+    }
+
+    /**
+     * The type of a node's output, or `null` where there is none or it is unknown.
+     *
+     * @param {number} node_id
+     * @param {string} [port] which output, for a node with more than one
+     * @returns {import("./ParticleValueType.js").ParticleValueType|null}
+     */
+    output(node_id, port = undefined) {
+        if (port !== undefined) {
+            const by_port = this.#outputs_by_port.get(node_id);
+
+            if (by_port !== undefined && port in by_port) {
+                return by_port[port] ?? null;
+            }
+        }
+
+        return this.#outputs.get(node_id) ?? null;
+    }
+
+    /**
+     * The type a node reads one of its inputs as — the input port's type, as far as a view is
+     * concerned. `null` where it is unknown.
+     *
+     * @param {number} node_id
+     * @param {string} port input port name
+     * @returns {import("./ParticleValueType.js").ParticleValueType|null}
+     */
+    input(node_id, port) {
+        return this.#inputs.get(node_id)?.[port] ?? null;
+    }
+
+    /**
+     * Every input port of a node and the type each is read as.
+     *
+     * @param {number} node_id
+     * @returns {Object<string, import("./ParticleValueType.js").ParticleValueType|null>}
+     */
+    inputs(node_id) {
+        return this.#inputs.get(node_id) ?? {};
+    }
+}
+
+/**
+ * @param {NodeGraph} graph
+ * @param {object} [context]
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
+ *   particle field schema; without it, particle field reads and writes are of unknown type
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [context.emitter_layout] the
+ *   effect's emitter field schema; without it, emitter field reads are of unknown type
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [context.global_layout] the
+ *   global fields the effect imports; without it, global field reads are of unknown type
+ * @returns {ParticleGraphTypes}
+ */
+export function infer_particle_graph_types(graph, { layout, emitter_layout = undefined, global_layout = undefined } = {}) {
+    const types = new ParticleGraphTypes();
+
+    /** @type {Set<number>} nodes on the current path, so a cycle is noticed rather than followed */
+    const visiting = new Set();
+
+    /**
+     * @param {NodeInstance} node
+     * @returns {import("./ParticleValueType.js").ParticleValueType|null} the node's output type
+     */
+    function visit(node) {
+        if (types.has(node.id)) {
+            return types.output(node.id);
+        }
+
+        if (visiting.has(node.id)) {
+            // A cycle has no evaluation order and so no types; the validator says so in its own
+            // words, this only has to not hang.
+            return null;
+        }
+
+        const description = node.description;
+
+        if (description === null || description === undefined || description.isParticleNodeDescription !== true) {
+            types.set(node.id, null, {});
+
+            return null;
+        }
+
+        visiting.add(node.id);
+
+        /** @type {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} */
+        const sources = {};
+
+        for (const port of description.inPorts) {
+            const connections = node.getEndpoint(port.id).inConnections;
+
+            // exactly one source is a value; none or several is a problem the validator reports
+            if (connections.length !== 1) {
+                sources[port.name] = null;
+
+                continue;
+            }
+
+            const source = connections[0].source;
+
+            visit(source.instance);
+
+            // by name, because the source may be a node with several outputs and they need not
+            // agree — a decomposed vector's lanes are scalars however wide the vector was
+            sources[port.name] = types.output(source.instance.id, source.port.name);
+        }
+
+        visiting.delete(node.id);
+
+        const { output, outputs, inputs } = description.infer_types({
+            inputs: sources,
+            parameters: node.parameters,
+            layout,
+            emitter_layout: emitter_layout ?? undefined,
+            global_layout: global_layout ?? undefined,
+        });
+
+        // every declared input is answered for, so a view never finds a port missing from the map
+        /** @type {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} */
+        const read = {};
+
+        for (const port of description.inPorts) {
+            read[port.name] = inputs[port.name] ?? null;
+        }
+
+        types.set(node.id, description.is_sink ? null : output, read, description.is_sink ? undefined : outputs);
+
+        for (const port of description.inPorts) {
+            const from = sources[port.name];
+            const to = read[port.name];
+
+            if (from === null || to === null) {
+                continue;
+            }
+
+            const conversion = particle_type_conversion(from, to);
+
+            if (conversion !== null) {
+                types.diagnostics.push({
+                    node: node.id,
+                    message: `Input '${port.name}' ${conversion.message}`,
+                    severity: PARTICLE_GRAPH_WARNING,
+                });
+            }
+        }
+
+        return types.output(node.id);
+    }
+
+    for (const node of graph.getNodes()) {
+        visit(node);
+    }
+
+    return types;
+}

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

@@ -58,7 +58,7 @@
  * @param {NodeDescriptionVisualRegistry} [params.visualRegistry] where the boundary blocks get their
  *        boxes from; told about this group's own node types on the way
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} [params.layout] the effect's
- *        attribute schema, for resolving the types the ports are declared with
+ *        particle field schema, for resolving the types the ports are declared with
  * @returns {{
  *   group: ParticleNodeGroup,
  *   inputs: Array<{port: string, from: {node: number, port: number}}>,

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

@@ -64,7 +64,7 @@ import { is_particle_group_boundary, ParticleNodeGroup } from "./ParticleNodeGro
  * @param {NodeDescriptionVisualRegistry} [params.visualRegistry] where the boundary blocks get their
  *        boxes from; told about this group's own node types on the way
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} [params.layout] the effect's
- *        attribute schema, for resolving the types the ports are declared with
+ *        particle field schema, for resolving the types the ports are declared with
  * @returns {{
  *   group: ParticleNodeGroup,
  *   inputs: Array<{port: string, from: {node: number, port: number}}>,

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

@@ -13,12 +13,13 @@
  * Parameters the caller leaves out take the type's defaults (see
  * {@link ./particle_node_parameters.js particle_node_default_parameters}), so what lands in the
  * graph is a node that compiles — the same footing a node dropped from the editor's palette
- * starts on. An attribute reference has no default worth having and is left empty.
+ * starts on. A field reference — particle, emitter or global — has no default worth having and is
+ * left empty.
  *
  * @param {NodeGraph} graph
  * @param {string} type a node type name from the library — a stock type or a
  *   {@link ./ParticleNodeGroup.js group}
- * @param {object} [parameters] static parameters (attribute name, builtin id, constant value, …)
+ * @param {object} [parameters] static parameters (field name, builtin id, constant value, …)
  * @returns {number} the new node instance id
  */
 export function particle_node(graph: NodeGraph, type: string, parameters?: object): number;

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

@@ -1 +1 @@
-{"version":3,"file":"particle_graph_authoring.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_graph_authoring.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;GAaG;AACH,sDALW,MAAM,eAEN,MAAM,GACJ,MAAM,CAelB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDALW,MAAM,QACN,MAAM,UACN,MAAM,GAAC,MAAM,EAAE,GAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAC,GAC3C,MAAM,CA2BlB;AA2BD;;;;;GAKG;AACH,uCAHc,MAAM,KACP,MAAM,EAAE,CAIpB"}
+{"version":3,"file":"particle_graph_authoring.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_graph_authoring.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;GAcG;AACH,sDALW,MAAM,eAEN,MAAM,GACJ,MAAM,CAelB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDALW,MAAM,QACN,MAAM,UACN,MAAM,GAAC,MAAM,EAAE,GAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAC,GAC3C,MAAM,CA2BlB;AA2BD;;;;;GAKG;AACH,uCAHc,MAAM,KACP,MAAM,EAAE,CAIpB"}

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

@@ -20,12 +20,13 @@ import { PARTICLE_NODE_OUTPUT_PORT } from "./ParticleNodeRegistry.js";
  * Parameters the caller leaves out take the type's defaults (see
  * {@link ./particle_node_parameters.js particle_node_default_parameters}), so what lands in the
  * graph is a node that compiles — the same footing a node dropped from the editor's palette
- * starts on. An attribute reference has no default worth having and is left empty.
+ * starts on. A field reference — particle, emitter or global — has no default worth having and is
+ * left empty.
  *
  * @param {NodeGraph} graph
  * @param {string} type a node type name from the library — a stock type or a
  *   {@link ./ParticleNodeGroup.js group}
- * @param {object} [parameters] static parameters (attribute name, builtin id, constant value, …)
+ * @param {object} [parameters] static parameters (field name, builtin id, constant value, …)
  * @returns {number} the new node instance id
  */
 export function particle_node(graph, type, parameters = {}) {