@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,64 @@
+import "./groups/particle_builtin_groups.js";
+import { get_particle_group, particle_groups } from "./particle_group_library.js";
+import { particle_node_descriptions } from "./ParticleNodeRegistry.js";
+
+/**
+ * The whole node library an author picks from: the stock types, and the
+ * {@link ./ParticleNodeGroup.js groups} built out of them.
+ *
+ * One accessor rather than two because a library with the groups missing is a library that cannot
+ * open half the effects saved with it — a group is addressed by name in a document exactly as a
+ * stock type is, and a loader that only knew about the stock ones would refuse a file it wrote
+ * itself. Importing this is what guarantees the built-in groups have been registered; nothing else
+ * should reach for `groups/particle_builtin_groups.js` directly.
+ *
+ * The two halves stay separate underneath. A stock type's id is its position in
+ * {@link ./ParticleNodeRegistry.js} and that is a wire format; a group is built at load time out of
+ * stock types and has no such position to lose. Keeping them apart is what lets a group be added
+ * without renumbering a node type.
+ */
+
+/**
+ * Every type an author can place, stock types first and then the groups.
+ *
+ * @returns {import("./ParticleNodeDescription.js").ParticleNodeDescription[]}
+ */
+export function particle_library_descriptions() {
+    return [
+        ...particle_node_descriptions(),
+        ...particle_groups().map(group => group.description),
+    ];
+}
+
+/**
+ * Look a type up by the name a document holds.
+ *
+ * @param {string} name
+ * @returns {import("./ParticleNodeDescription.js").ParticleNodeDescription}
+ * @throws if the library has no such type
+ */
+export function get_particle_library_description(name) {
+    const description = particle_library_description_or_undefined(name);
+
+    if (description === undefined) {
+        throw new Error(`Unknown particle node type '${name}'`);
+    }
+
+    return description;
+}
+
+/**
+ * The same lookup, for a caller that has something to say about a missing type itself.
+ *
+ * @param {string} name
+ * @returns {import("./ParticleNodeDescription.js").ParticleNodeDescription|undefined}
+ */
+export function particle_library_description_or_undefined(name) {
+    const group = get_particle_group(name);
+
+    if (group !== undefined) {
+        return group.description;
+    }
+
+    return particle_node_descriptions().find(description => description.name === name);
+}

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

@@ -0,0 +1,146 @@
+/**
+ * The parameters of one node type.
+ *
+ * @param {string} type node type name
+ * @returns {ParticleNodeParameter[]} empty when the type takes none
+ * @throws if the type is not described — which is a missing entry above, not an unknown node
+ */
+export function particle_node_parameters(type: string): ParticleNodeParameter[];
+/**
+ * The parameter object a freshly created node of this type should start with.
+ *
+ * Every parameter the type declares is present, so a new node compiles without the author having to
+ * fill anything in — which is the difference between a palette that drops working nodes into a
+ * graph and one that drops broken ones.
+ *
+ * Attribute parameters have no default of their own: the only sensible one is a name from the
+ * effect being authored, so the layout has to be supplied. With no layout (or an empty one) they
+ * come back as the empty string, which will not compile — the caller is expected to know that and
+ * either pass a layout or fill the name in.
+ *
+ * @param {string} type node type name
+ * @param {object} [context]
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
+ *   attribute schema, used to pick a default for attribute parameters
+ * @returns {object}
+ */
+export function particle_node_default_parameters(type: string, { layout }?: {
+    layout?: import("../layout/ParticleLayout.js").ParticleLayout;
+}): object;
+/**
+ * Every node type in the library paired with its parameters, for a palette to list.
+ *
+ * @returns {Array<{description: import("./ParticleNodeDescription.js").ParticleNodeDescription, parameters: ParticleNodeParameter[]}>}
+ */
+export function particle_node_catalogue(): Array<{
+    description: import("./ParticleNodeDescription.js").ParticleNodeDescription;
+    parameters: ParticleNodeParameter[];
+}>;
+/**
+ * The kinds of value a particle node parameter can hold.
+ */
+export type PARTICLE_PARAMETER_KIND = string;
+/**
+ * What each particle node type's static parameters *are* — the contract between the `emit` closures
+ * in {@link ./ParticleNodeRegistry.js}, which read `context.parameters.<name>`, and anything that
+ * has to produce those parameters without being told: an editor building controls, a default-value
+ * factory, a serializer checking an authored graph.
+ *
+ * The engine's generic {@link ../../../../core/model/node-graph/node/NodeDescription.js} parameter
+ * mechanism is not used for these. Its parameters are keyed by a numeric id and typed as
+ * number / string / boolean, and a particle node's are keyed by name and are vectors, layout
+ * attribute references, ISA enum members and swizzle patterns. Rather than flatten them into three
+ * scalar types and lose what they mean, they are described here in their own terms, and the editor
+ * renders a control per kind.
+ *
+ * Living beside the node library rather than in the editor is what keeps the two honest:
+ * {@link ./particle_node_parameters.spec.js} asserts that every registered type is described here,
+ * and that a node built from nothing but these defaults compiles.
+ */
+/**
+ * The kinds of value a particle node parameter can hold.
+ * @enum {string}
+ */
+export const PARTICLE_PARAMETER_KIND: Readonly<{
+    /** one to four floats; how many there are is the value's type, a scalar or a `vec2..4` */
+    VECTOR: "vector";
+    /** four floats that are a colour: red, green, blue and alpha, each in `[0, 1]` */
+    COLOR: "color";
+    /** the name of an attribute in the effect's {@link ../layout/ParticleLayout.js} */
+    ATTRIBUTE: "attribute";
+    /** one member of {@link PARTICLE_NODE_PARAMETER_SCHEMA}'s `options` map */
+    ENUM: "enum";
+    /** one to four lane selectors in `[0, 4)`, one per output lane */
+    SWIZZLE: "swizzle";
+    /** a non-negative integer — a curve handle */
+    INTEGER: "integer";
+}>;
+/**
+ * One parameter of one node type.
+ *
+ * @typedef {object} ParticleNodeParameter
+ * @property {string} name the key the node's `emit` reads off `context.parameters`
+ * @property {string} kind a {@link PARTICLE_PARAMETER_KIND}
+ * @property {*} [default] the value a freshly created node takes; absent for
+ *   {@link PARTICLE_PARAMETER_KIND.ATTRIBUTE}, whose default can only come from the effect's layout
+ * @property {Object<string, *>} [options] for {@link PARTICLE_PARAMETER_KIND.ENUM}: label -> value
+ * @property {string} [description] one line of help, shown by the editor
+ */
+/**
+ * The node types whose whole configuration is their wiring — every arithmetic, vector and logic
+ * operation, plus the two sinks that take only a value.
+ *
+ * Listed rather than inferred so that "takes no parameters" is a claim someone made, and a node
+ * type added to the library without a word about its parameters is caught by
+ * {@link ./particle_node_parameters.spec.js} instead of silently reading as taking none.
+ *
+ * @type {string[]}
+ */
+export const PARTICLE_NODES_WITHOUT_PARAMETERS: string[];
+/**
+ * A lane count offered as a type: what a `random` is asked to be, and what a literal's width picker
+ * says. Labelled by the type's name, valued by its width.
+ *
+ * @type {Object<string, number>}
+ */
+export const PARTICLE_WIDTH_OPTIONS: {
+    [x: string]: number;
+};
+/**
+ * Node type name -> its parameters, in the order an editor should present them. A type with no
+ * static parameters is present with an empty array, so "missing" and "has none" are distinct.
+ *
+ * @type {Object<string, ParticleNodeParameter[]>}
+ */
+export const PARTICLE_NODE_PARAMETER_SCHEMA: {
+    [x: string]: ParticleNodeParameter[];
+};
+/**
+ * One parameter of one node type.
+ */
+export type ParticleNodeParameter = {
+    /**
+     * the key the node's `emit` reads off `context.parameters`
+     */
+    name: string;
+    /**
+     * a {@link PARTICLE_PARAMETER_KIND }
+     */
+    kind: string;
+    /**
+     * the value a freshly created node takes; absent for
+     * {@link PARTICLE_PARAMETER_KIND.ATTRIBUTE }, whose default can only come from the effect's layout
+     */
+    default?: any;
+    /**
+     * for {@link PARTICLE_PARAMETER_KIND.ENUM }: label -> value
+     */
+    options?: {
+        [x: string]: any;
+    };
+    /**
+     * one line of help, shown by the editor
+     */
+    description?: string;
+};
+//# sourceMappingURL=particle_node_parameters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particle_node_parameters.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_node_parameters.js"],"names":[],"mappings":"AAqKA;;;;;;GAMG;AACH,+CAJW,MAAM,GACJ,qBAAqB,EAAE,CAcnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,uDANW,MAAM;IAEyD,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAElD,MAAM,CAoBlB;AAED;;;;GAIG;AACH,2CAFa,MAAM;IAAC,WAAW,EAAE,OAAO,8BAA8B,EAAE,uBAAuB,CAAC;IAAC,UAAU,EAAE,qBAAqB,EAAE,CAAA;CAAC,CAAC,CAOrI;;;;sCAjNS,MAAM;AApBhB;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH;IACI,0FAA0F;;IAE1F,kFAAkF;;IAElF,mFAAmF;;IAEnF,2EAA2E;;IAE3E,kEAAkE;;IAElE,8CAA8C;;GAE/C;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,gDAFU,MAAM,EAAE,CAUf;AAEH;;;;;GAKG;AACH;QAFiB,MAAM,GAAE,MAAM;EAI7B;AAEF;;;;;GAKG;AACH;QAFiB,MAAM,GAAE,qBAAqB,EAAE;EA4E7C;;;;;;;;UAtHW,MAAM;;;;UACN,MAAM;;;;;;;;;;YAGC,MAAM;;;;;kBACb,MAAM"}

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

@@ -0,0 +1,234 @@
+import { VM_BUILTIN } from "../isa/ParticleVMISA.js";
+import { PARTICLE_COMPARE_OPCODES, particle_node_descriptions } from "./ParticleNodeRegistry.js";
+import { PARTICLE_VALUE_TYPES } from "./ParticleValueType.js";
+
+/**
+ * What each particle node type's static parameters *are* — the contract between the `emit` closures
+ * in {@link ./ParticleNodeRegistry.js}, which read `context.parameters.<name>`, and anything that
+ * has to produce those parameters without being told: an editor building controls, a default-value
+ * factory, a serializer checking an authored graph.
+ *
+ * The engine's generic {@link ../../../../core/model/node-graph/node/NodeDescription.js} parameter
+ * mechanism is not used for these. Its parameters are keyed by a numeric id and typed as
+ * number / string / boolean, and a particle node's are keyed by name and are vectors, layout
+ * attribute references, ISA enum members and swizzle patterns. Rather than flatten them into three
+ * scalar types and lose what they mean, they are described here in their own terms, and the editor
+ * renders a control per kind.
+ *
+ * Living beside the node library rather than in the editor is what keeps the two honest:
+ * {@link ./particle_node_parameters.spec.js} asserts that every registered type is described here,
+ * and that a node built from nothing but these defaults compiles.
+ */
+
+/**
+ * The kinds of value a particle node parameter can hold.
+ * @enum {string}
+ */
+export const PARTICLE_PARAMETER_KIND = Object.freeze({
+    /** one to four floats; how many there are is the value's type, a scalar or a `vec2..4` */
+    VECTOR: "vector",
+    /** four floats that are a colour: red, green, blue and alpha, each in `[0, 1]` */
+    COLOR: "color",
+    /** the name of an attribute in the effect's {@link ../layout/ParticleLayout.js} */
+    ATTRIBUTE: "attribute",
+    /** one member of {@link PARTICLE_NODE_PARAMETER_SCHEMA}'s `options` map */
+    ENUM: "enum",
+    /** one to four lane selectors in `[0, 4)`, one per output lane */
+    SWIZZLE: "swizzle",
+    /** a non-negative integer — a curve handle */
+    INTEGER: "integer",
+});
+
+/**
+ * One parameter of one node type.
+ *
+ * @typedef {object} ParticleNodeParameter
+ * @property {string} name the key the node's `emit` reads off `context.parameters`
+ * @property {string} kind a {@link PARTICLE_PARAMETER_KIND}
+ * @property {*} [default] the value a freshly created node takes; absent for
+ *   {@link PARTICLE_PARAMETER_KIND.ATTRIBUTE}, whose default can only come from the effect's layout
+ * @property {Object<string, *>} [options] for {@link PARTICLE_PARAMETER_KIND.ENUM}: label -> value
+ * @property {string} [description] one line of help, shown by the editor
+ */
+
+/**
+ * The node types whose whole configuration is their wiring — every arithmetic, vector and logic
+ * operation, plus the two sinks that take only a value.
+ *
+ * Listed rather than inferred so that "takes no parameters" is a claim someone made, and a node
+ * type added to the library without a word about its parameters is caught by
+ * {@link ./particle_node_parameters.spec.js} instead of silently reading as taking none.
+ *
+ * @type {string[]}
+ */
+export const PARTICLE_NODES_WITHOUT_PARAMETERS = Object.freeze([
+    "kill",
+    "add", "sub", "mul", "div", "min", "max", "pow", "step",
+    "mad", "mix", "clamp", "smoothstep", "scale",
+    "neg", "abs", "floor", "fract", "sqrt", "sin", "cos", "exp", "log", "normalize", "length",
+    "dot", "cross", "distance",
+    "vec2", "vec3", "vec4",
+    "select",
+]);
+
+/**
+ * A lane count offered as a type: what a `random` is asked to be, and what a literal's width picker
+ * says. Labelled by the type's name, valued by its width.
+ *
+ * @type {Object<string, number>}
+ */
+export const PARTICLE_WIDTH_OPTIONS = Object.freeze(
+    Object.fromEntries(PARTICLE_VALUE_TYPES.map(type => [type.name, type.components]))
+);
+
+/**
+ * Node type name -> its parameters, in the order an editor should present them. A type with no
+ * static parameters is present with an empty array, so "missing" and "has none" are distinct.
+ *
+ * @type {Object<string, ParticleNodeParameter[]>}
+ */
+export const PARTICLE_NODE_PARAMETER_SCHEMA = Object.freeze({
+    ...Object.fromEntries(PARTICLE_NODES_WITHOUT_PARAMETERS.map(name => [name, Object.freeze([])])),
+
+    const: [{
+        name: "value",
+        kind: PARTICLE_PARAMETER_KIND.VECTOR,
+        default: [0],
+        description: "The literal this node produces — a scalar, or a vector as wide as there are numbers. "
+            + "Interned into the program's constant pool.",
+    }],
+
+    // Opaque white by default, which is the colour that changes nothing about whatever it is
+    // multiplied into and is visible against any background it is written to.
+    color: [{
+        name: "value",
+        kind: PARTICLE_PARAMETER_KIND.COLOR,
+        default: [1, 1, 1, 1],
+        description: "The colour this node produces. A vec4 of red, green, blue and alpha, "
+            + "interned into the program's constant pool like any other literal.",
+    }],
+
+    builtin: [{
+        name: "id",
+        kind: PARTICLE_PARAMETER_KIND.ENUM,
+        options: VM_BUILTIN,
+        default: VM_BUILTIN.DELTA_TIME,
+        description: "Which per-invocation value the host shader hands the VM.",
+    }],
+
+    attribute: [{
+        name: "name",
+        kind: PARTICLE_PARAMETER_KIND.ATTRIBUTE,
+        description: "The per-particle attribute to read, by name in the effect's layout.",
+    }],
+
+    // Four is the width a draw had before it had one — as wide as anything could read it — so an
+    // effect saved without saying is read the way it was written. A draw that is meant to be one
+    // value says so, and reads as a scalar.
+    random: [{
+        name: "components",
+        kind: PARTICLE_PARAMETER_KIND.ENUM,
+        options: PARTICLE_WIDTH_OPTIONS,
+        default: 4,
+        description: "How many independent draws, one per lane: a scalar, or a vector of them.",
+    }],
+
+    setAttribute: [{
+        name: "name",
+        kind: PARTICLE_PARAMETER_KIND.ATTRIBUTE,
+        description: "The per-particle attribute to write, by name in the effect's layout.",
+    }],
+
+    compare: [{
+        name: "op",
+        kind: PARTICLE_PARAMETER_KIND.ENUM,
+        // the operator NAMES are the values here: `emit` looks the opcode up by name
+        options: Object.fromEntries(Object.keys(PARTICLE_COMPARE_OPCODES).map(key => [key, key])),
+        default: "lt",
+        description: "Comparison to apply, component-wise. Produces 1 where it holds and 0 where it does not.",
+    }],
+
+    swizzle: [{
+        name: "pattern",
+        kind: PARTICLE_PARAMETER_KIND.SWIZZLE,
+        default: [0, 1, 2, 3],
+        description: "Which input lane each output lane reads; one to four of them, and that count is the result's width.",
+    }],
+
+    curve: [{
+        name: "handle",
+        kind: PARTICLE_PARAMETER_KIND.INTEGER,
+        default: 0,
+        description: "Row of the animation-curve table to sample.",
+    }],
+});
+
+/**
+ * The parameters of one node type.
+ *
+ * @param {string} type node type name
+ * @returns {ParticleNodeParameter[]} empty when the type takes none
+ * @throws if the type is not described — which is a missing entry above, not an unknown node
+ */
+export function particle_node_parameters(type) {
+    const parameters = PARTICLE_NODE_PARAMETER_SCHEMA[type];
+
+    if (parameters === undefined) {
+        throw new Error(
+            `Particle node type '${type}' has no parameter description. `
+            + `Add one to PARTICLE_NODE_PARAMETER_SCHEMA, even if it is empty.`
+        );
+    }
+
+    return parameters;
+}
+
+/**
+ * The parameter object a freshly created node of this type should start with.
+ *
+ * Every parameter the type declares is present, so a new node compiles without the author having to
+ * fill anything in — which is the difference between a palette that drops working nodes into a
+ * graph and one that drops broken ones.
+ *
+ * Attribute parameters have no default of their own: the only sensible one is a name from the
+ * effect being authored, so the layout has to be supplied. With no layout (or an empty one) they
+ * come back as the empty string, which will not compile — the caller is expected to know that and
+ * either pass a layout or fill the name in.
+ *
+ * @param {string} type node type name
+ * @param {object} [context]
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
+ *   attribute schema, used to pick a default for attribute parameters
+ * @returns {object}
+ */
+export function particle_node_default_parameters(type, { layout } = {}) {
+    const result = {};
+
+    const first_attribute = layout === undefined ? undefined : layout.attributes.keys().next().value;
+
+    for (const parameter of particle_node_parameters(type)) {
+        if (parameter.kind === PARTICLE_PARAMETER_KIND.ATTRIBUTE) {
+            result[parameter.name] = first_attribute ?? "";
+        } else if (Array.isArray(parameter.default)) {
+            // arrays are mutable and a node writes through to its own; a shared one would make two
+            // nodes of the same type the same node
+            result[parameter.name] = parameter.default.slice();
+        } else {
+            result[parameter.name] = parameter.default;
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Every node type in the library paired with its parameters, for a palette to list.
+ *
+ * @returns {Array<{description: import("./ParticleNodeDescription.js").ParticleNodeDescription, parameters: ParticleNodeParameter[]}>}
+ */
+export function particle_node_catalogue() {
+    return particle_node_descriptions().map(description => ({
+        description,
+        parameters: particle_node_parameters(description.name),
+    }));
+}

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

@@ -0,0 +1,30 @@
+/**
+ * What to show for a node type. A type with no entry falls back to its own name and no artwork,
+ * which is what the base {@link NodeDescription} does anyway — a library extended at runtime shows
+ * up plainly rather than not at all.
+ *
+ * @param {string} name node type name
+ * @returns {{label: string, icon: string, help: string}}
+ */
+export function particle_node_presentation(name: string): {
+    label: string;
+    icon: string;
+    help: string;
+};
+/**
+ * Everything the editor shows about a node type, by the type's name.
+ *
+ * Every type in the library has an entry, and no entry names a type the library does not have —
+ * both directions are checked by `ParticleNodeRegistry.spec.js`, so a node type added without a
+ * label fails a test rather than quietly showing up in the graph as `smoothstep`.
+ *
+ * @type {Object<string, {label: string, icon: string, help: string}>}
+ */
+export const PARTICLE_NODE_PRESENTATION: {
+    [x: string]: {
+        label: string;
+        icon: string;
+        help: string;
+    };
+};
+//# sourceMappingURL=particle_node_presentation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particle_node_presentation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_node_presentation.js"],"names":[],"mappings":"AAmRA;;;;;;;GAOG;AACH,iDAHW,MAAM,GACJ;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAIvD;AAnPD;;;;;;;;GAQG;AACH;QAFiB,MAAM,GAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC;EAgOjE"}