@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -1,170 +1,170 @@
-import { particle_node, particle_wire } from "./particle_graph_authoring.js";
-
-/**
- * Shaped random distributions, built out of the particle node library.
- *
- * The VM's `RANDOM` opcode is one uniform draw in `[0, 1)` per lane and nothing else. It used to
- * carry a distribution mode — signed, unit disk, unit sphere — and the modes went because every one
- * of them is arithmetic over that draw, and there is no principled place to stop adding the next
- * one. A sampler is still a useful thing to have, so it lives here, one level up, where it is a
- * graph an author can open and change rather than a switch arm in the interpreter.
- *
- * These are ordinary functions over {@link ./particle_graph_authoring.js}: they add nodes to a
- * graph and return the id of the one carrying the result. Nothing downstream knows they were used.
- *
- * ## Shape
- *
- * Each result has the type its shape has: a disk is a `vec2`, a sphere a `vec3`. What is wired
- * past that is a conversion the compiler makes and the validator names — a disk written to a
- * three-component position reads zero in `z`, as it always did — and what is wired narrower keeps
- * its leading lanes. A scalar draw meeting a vector broadcasts, so a signed draw that is meant to
- * differ per lane says how many lanes it wants.
- *
- * ## What they cost
- *
- * As the graph compiler lowers them: a disk is 10 instructions and a sphere 19, against a section
- * budget of {@link ../ParticleConstants.js PARTICLE_VM_MAX_INSTRUCTIONS}. The vector constructors
- * are what brought that down from 15 and 24: assembling `(cos a, sin a)` used to take a broadcast
- * of each and a masked select, and is now a `MOV` per lane. Writing the disk to a three-component
- * attribute is one more, the zero for `z`. {@link ../optimizer/optimize_particle_program.js} takes
- * the sphere to 17 on top of that; hand-written assembly does the same work in 7 and 10.
- *
- * ## Draw order
- *
- * A composition consumes the same number of draws the opcode mode did (two for the geometric ones,
- * one per lane for {@link particle_uniform_signed}), but *which* draw feeds which term is now the
- * compiler's scheduling of two independent `random` nodes rather than a fixed order inside an
- * opcode. Samples therefore differ from the old modes' even from the same seed; the distributions
- * do not.
- */
-
-/** @type {number} */
-const TWO_PI = Math.PI * 2;
-
-/**
- * A uniform draw in `[-1, 1)`, one independent value per lane.
- *
- * @param {NodeGraph} graph
- * @param {number} [components] how many lanes, each its own draw; one is a scalar
- * @returns {number} node id of the result
- */
-export function particle_uniform_signed(graph, components = 1) {
-    const uniform = particle_node(graph, "random", { components });
-    const signed = particle_node(graph, "mad");
-
-    particle_wire(graph, signed, "a", uniform);
-    particle_wire(graph, signed, "b", [2]);
-    particle_wire(graph, signed, "c", [-1]);
-
-    return signed;
-}
-
-/**
- * A uniformly distributed point in the unit disk, a `vec2`.
- *
- * `sqrt` on the radius is what makes it uniform by area rather than crowded at the centre.
- *
- * @param {NodeGraph} graph
- * @returns {number} node id of the result
- */
-export function particle_unit_disk(graph) {
-    const radius = particle_node(graph, "sqrt");
-
-    particle_wire(graph, radius, "x", particle_node(graph, "random", { components: 1 }));
-
-    const point = particle_node(graph, "scale");
-
-    particle_wire(graph, point, "v", unit_circle(graph));
-    particle_wire(graph, point, "s", radius);
-
-    return point;
-}
-
-/**
- * A uniformly distributed point on the unit sphere, a `vec3`.
- *
- * Archimedes' hat-box: the projection of the sphere onto its bounding cylinder preserves area, so a
- * uniform height and a uniform angle around it give a uniform point. It is also the only shape of
- * sampler this VM can run — rejection sampling needs a loop, and there is no control flow.
- *
- * @param {NodeGraph} graph
- * @returns {number} node id of the result
- */
-export function particle_unit_sphere(graph) {
-    // height, uniform in [-1, 1)
-    const height = particle_uniform_signed(graph, 1);
-
-    // radius of the circle of latitude at that height: sqrt(1 - z^2)
-    const height_squared = particle_node(graph, "mul");
-
-    particle_wire(graph, height_squared, "a", height);
-    particle_wire(graph, height_squared, "b", height);
-
-    const radius_squared = particle_node(graph, "sub");
-
-    particle_wire(graph, radius_squared, "a", [1]);
-    particle_wire(graph, radius_squared, "b", height_squared);
-
-    const radius = particle_node(graph, "sqrt");
-
-    particle_wire(graph, radius, "x", radius_squared);
-
-    // the point on that circle, and the height dropped in beside it
-    const { cosine, sine } = unit_angle(graph);
-
-    const x = particle_node(graph, "mul");
-
-    particle_wire(graph, x, "a", cosine);
-    particle_wire(graph, x, "b", radius);
-
-    const y = particle_node(graph, "mul");
-
-    particle_wire(graph, y, "a", sine);
-    particle_wire(graph, y, "b", radius);
-
-    const point = particle_node(graph, "vec3");
-
-    particle_wire(graph, point, "x", x);
-    particle_wire(graph, point, "y", y);
-    particle_wire(graph, point, "z", height);
-
-    return point;
-}
-
-/**
- * A uniformly distributed point on the unit circle, a `vec2`.
- *
- * @param {NodeGraph} graph
- * @returns {number} node id of the result
- */
-function unit_circle(graph) {
-    const { cosine, sine } = unit_angle(graph);
-
-    const circle = particle_node(graph, "vec2");
-
-    particle_wire(graph, circle, "x", cosine);
-    particle_wire(graph, circle, "y", sine);
-
-    return circle;
-}
-
-/**
- * The cosine and sine of a uniform angle, as two scalars off one draw.
- *
- * @param {NodeGraph} graph
- * @returns {{cosine: number, sine: number}} node ids
- */
-function unit_angle(graph) {
-    const angle = particle_node(graph, "mul");
-
-    particle_wire(graph, angle, "a", particle_node(graph, "random", { components: 1 }));
-    particle_wire(graph, angle, "b", [TWO_PI]);
-
-    const cosine = particle_node(graph, "cos");
-    const sine = particle_node(graph, "sin");
-
-    particle_wire(graph, cosine, "x", angle);
-    particle_wire(graph, sine, "x", angle);
-
-    return { cosine, sine };
-}
+import { particle_node, particle_wire } from "./particle_graph_authoring.js";
+
+/**
+ * Shaped random distributions, built out of the particle node library.
+ *
+ * The VM's `RANDOM` opcode is one uniform draw in `[0, 1)` per lane and nothing else. It used to
+ * carry a distribution mode — signed, unit disk, unit sphere — and the modes went because every one
+ * of them is arithmetic over that draw, and there is no principled place to stop adding the next
+ * one. A sampler is still a useful thing to have, so it lives here, one level up, where it is a
+ * graph an author can open and change rather than a switch arm in the interpreter.
+ *
+ * These are ordinary functions over {@link ./particle_graph_authoring.js}: they add nodes to a
+ * graph and return the id of the one carrying the result. Nothing downstream knows they were used.
+ *
+ * ## Shape
+ *
+ * Each result has the type its shape has: a disk is a `vec2`, a sphere a `vec3`. What is wired
+ * past that is a conversion the compiler makes and the validator names — a disk written to a
+ * three-component position reads zero in `z`, as it always did — and what is wired narrower keeps
+ * its leading lanes. A scalar draw meeting a vector broadcasts, so a signed draw that is meant to
+ * differ per lane says how many lanes it wants.
+ *
+ * ## What they cost
+ *
+ * As the graph compiler lowers them: a disk is 10 instructions and a sphere 19, against a section
+ * budget of {@link ../ParticleConstants.js PARTICLE_VM_MAX_INSTRUCTIONS}. The vector constructors
+ * are what brought that down from 15 and 24: assembling `(cos a, sin a)` used to take a broadcast
+ * of each and a masked select, and is now a `MOV` per lane. Writing the disk to a three-component
+ * particle field is one more, the zero for `z`. {@link ../optimizer/optimize_particle_program.js}
+ * takes the sphere to 17 on top of that; hand-written assembly does the same work in 7 and 10.
+ *
+ * ## Draw order
+ *
+ * A composition consumes the same number of draws the opcode mode did (two for the geometric ones,
+ * one per lane for {@link particle_uniform_signed}), but *which* draw feeds which term is now the
+ * compiler's scheduling of two independent `random` nodes rather than a fixed order inside an
+ * opcode. Samples therefore differ from the old modes' even from the same seed; the distributions
+ * do not.
+ */
+
+/** @type {number} */
+const TWO_PI = Math.PI * 2;
+
+/**
+ * A uniform draw in `[-1, 1)`, one independent value per lane.
+ *
+ * @param {NodeGraph} graph
+ * @param {number} [components] how many lanes, each its own draw; one is a scalar
+ * @returns {number} node id of the result
+ */
+export function particle_uniform_signed(graph, components = 1) {
+    const uniform = particle_node(graph, "random", { components });
+    const signed = particle_node(graph, "mad");
+
+    particle_wire(graph, signed, "a", uniform);
+    particle_wire(graph, signed, "b", [2]);
+    particle_wire(graph, signed, "c", [-1]);
+
+    return signed;
+}
+
+/**
+ * A uniformly distributed point in the unit disk, a `vec2`.
+ *
+ * `sqrt` on the radius is what makes it uniform by area rather than crowded at the centre.
+ *
+ * @param {NodeGraph} graph
+ * @returns {number} node id of the result
+ */
+export function particle_unit_disk(graph) {
+    const radius = particle_node(graph, "sqrt");
+
+    particle_wire(graph, radius, "x", particle_node(graph, "random", { components: 1 }));
+
+    const point = particle_node(graph, "scale");
+
+    particle_wire(graph, point, "v", unit_circle(graph));
+    particle_wire(graph, point, "s", radius);
+
+    return point;
+}
+
+/**
+ * A uniformly distributed point on the unit sphere, a `vec3`.
+ *
+ * Archimedes' hat-box: the projection of the sphere onto its bounding cylinder preserves area, so a
+ * uniform height and a uniform angle around it give a uniform point. It is also the only shape of
+ * sampler this VM can run — rejection sampling needs a loop, and there is no control flow.
+ *
+ * @param {NodeGraph} graph
+ * @returns {number} node id of the result
+ */
+export function particle_unit_sphere(graph) {
+    // height, uniform in [-1, 1)
+    const height = particle_uniform_signed(graph, 1);
+
+    // radius of the circle of latitude at that height: sqrt(1 - z^2)
+    const height_squared = particle_node(graph, "mul");
+
+    particle_wire(graph, height_squared, "a", height);
+    particle_wire(graph, height_squared, "b", height);
+
+    const radius_squared = particle_node(graph, "sub");
+
+    particle_wire(graph, radius_squared, "a", [1]);
+    particle_wire(graph, radius_squared, "b", height_squared);
+
+    const radius = particle_node(graph, "sqrt");
+
+    particle_wire(graph, radius, "x", radius_squared);
+
+    // the point on that circle, and the height dropped in beside it
+    const { cosine, sine } = unit_angle(graph);
+
+    const x = particle_node(graph, "mul");
+
+    particle_wire(graph, x, "a", cosine);
+    particle_wire(graph, x, "b", radius);
+
+    const y = particle_node(graph, "mul");
+
+    particle_wire(graph, y, "a", sine);
+    particle_wire(graph, y, "b", radius);
+
+    const point = particle_node(graph, "vec3");
+
+    particle_wire(graph, point, "x", x);
+    particle_wire(graph, point, "y", y);
+    particle_wire(graph, point, "z", height);
+
+    return point;
+}
+
+/**
+ * A uniformly distributed point on the unit circle, a `vec2`.
+ *
+ * @param {NodeGraph} graph
+ * @returns {number} node id of the result
+ */
+function unit_circle(graph) {
+    const { cosine, sine } = unit_angle(graph);
+
+    const circle = particle_node(graph, "vec2");
+
+    particle_wire(graph, circle, "x", cosine);
+    particle_wire(graph, circle, "y", sine);
+
+    return circle;
+}
+
+/**
+ * The cosine and sine of a uniform angle, as two scalars off one draw.
+ *
+ * @param {NodeGraph} graph
+ * @returns {{cosine: number, sine: number}} node ids
+ */
+function unit_angle(graph) {
+    const angle = particle_node(graph, "mul");
+
+    particle_wire(graph, angle, "a", particle_node(graph, "random", { components: 1 }));
+    particle_wire(graph, angle, "b", [TWO_PI]);
+
+    const cosine = particle_node(graph, "cos");
+    const sine = particle_node(graph, "sin");
+
+    particle_wire(graph, cosine, "x", angle);
+    particle_wire(graph, sine, "x", angle);
+
+    return { cosine, sine };
+}

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

@@ -1,19 +1,3 @@
-/**
- * Read and write a particle {@link NodeGraph} as JSON.
- *
- * The engine's generic graph serializer writes each {@link NodeDescription} out by value. That
- * cannot work here: a {@link ./ParticleNodeDescription.js} carries an `emit` closure, which is the
- * whole of what the node *is*, and no amount of JSON brings a closure back. So a particle node is
- * written as its **type name** and looked up in the library on the way in — the same thing authoring
- * does, and the reason node type names, not ids, are the stable identity of the library.
- *
- * Ports are written by name for the same reason. A particle node's ports are uniquely named within
- * a direction, so a name survives the library gaining a port where a positional id would not.
- *
- * Node positions ride along when a {@link NodeGraphVisualData} is supplied. An effect whose layout
- * is not saved with it is an effect that has to be re-arranged every time it is opened, so they
- * belong in the same document even though one is model and the other is presentation.
- */
 /**
  * @typedef {object} ParticleGraphJSON
  * @property {Array<{id: number, type: string, parameters: object, x?: number, y?: number}>} nodes
@@ -69,6 +53,31 @@ export function deserialize_particle_graph({ json, graph, visual, visualRegistry
 export function particle_graph_serialization_problems(graph: NodeGraph, { resolve }?: {
     resolve?: (arg0: string) => (ParticleNodeDescription | undefined);
 }): string[];
+/**
+ * Read and write a particle {@link NodeGraph} as JSON.
+ *
+ * The engine's generic graph serializer writes each {@link NodeDescription} out by value. That
+ * cannot work here: a {@link ./ParticleNodeDescription.js} carries an `emit` closure, which is the
+ * whole of what the node *is*, and no amount of JSON brings a closure back. So a particle node is
+ * written as its **type name** and looked up in the library on the way in — the same thing authoring
+ * does, and the reason node type names, not ids, are the stable identity of the library.
+ *
+ * A name, once written, is read forever. A node type that is renamed keeps its old name in
+ * {@link PARTICLE_NODE_TYPE_RENAMES}, so a file saved before the rename reads as the graph it was.
+ *
+ * Ports are written by name for the same reason. A particle node's ports are uniquely named within
+ * a direction, so a name survives the library gaining a port where a positional id would not.
+ *
+ * Node positions ride along when a {@link NodeGraphVisualData} is supplied. An effect whose layout
+ * is not saved with it is an effect that has to be re-arranged every time it is opened, so they
+ * belong in the same document even though one is model and the other is presentation.
+ */
+/**
+ * Older node type names, mapped to the current ones, so a graph saved under them still reads.
+ *
+ * @type {ReadonlyMap<string, string>}
+ */
+export const PARTICLE_NODE_TYPE_RENAMES: ReadonlyMap<string, string>;
 export type ParticleGraphJSON = {
     nodes: Array<{
         id: number;

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

@@ -1 +1 @@
-{"version":3,"file":"particle_graph_json.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_graph_json.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AAEH;;;;;GAKG;AACH;IAJ6B,KAAK;IACM,MAAM;IACjC,iBAAiB,CAiC7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH;IAVqC,IAAI,EAA9B,iBAAiB;IACC,KAAK;IACM,MAAM;IACI,cAAc;IACS,OAAO,UAA5D,MAAM,KAAE,CAAC,0BAAwB,SAAS,CAAC;cAwD9D;AAED;;;;;;;;;;;GAWG;AACH;IAJ0E,OAAO,UAA7D,MAAM,KAAE,CAAC,0BAAwB,SAAS,CAAC;IAElD,MAAM,EAAE,CA6CpB;;WAxKa,MAAM;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;iBAC7E,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC"}
+{"version":3,"file":"particle_graph_json.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_graph_json.js"],"names":[],"mappings":"AAsCA;;;;GAIG;AAEH;;;;;GAKG;AACH;IAJ6B,KAAK;IACM,MAAM;IACjC,iBAAiB,CAiC7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH;IAVqC,IAAI,EAA9B,iBAAiB;IACC,KAAK;IACM,MAAM;IACI,cAAc;IACS,OAAO,UAA5D,MAAM,KAAE,CAAC,0BAAwB,SAAS,CAAC;cAyD9D;AAED;;;;;;;;;;;GAWG;AACH;IAJ0E,OAAO,UAA7D,MAAM,KAAE,CAAC,0BAAwB,SAAS,CAAC;IAElD,MAAM,EAAE,CA6CpB;AAzMD;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,yCAFU,YAAY,MAAM,EAAE,MAAM,CAAC,CAKlC;;WAIW,MAAM;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;iBAC7E,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC"}

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

@@ -15,6 +15,9 @@ import { is_particle_group_description } from "./ParticleNodeGroup.js";
  * written as its **type name** and looked up in the library on the way in — the same thing authoring
  * does, and the reason node type names, not ids, are the stable identity of the library.
  *
+ * A name, once written, is read forever. A node type that is renamed keeps its old name in
+ * {@link PARTICLE_NODE_TYPE_RENAMES}, so a file saved before the rename reads as the graph it was.
+ *
  * Ports are written by name for the same reason. A particle node's ports are uniquely named within
  * a direction, so a name survives the library gaining a port where a positional id would not.
  *
@@ -23,6 +26,16 @@ import { is_particle_group_description } from "./ParticleNodeGroup.js";
  * belong in the same document even though one is model and the other is presentation.
  */
 
+/**
+ * Older node type names, mapped to the current ones, so a graph saved under them still reads.
+ *
+ * @type {ReadonlyMap<string, string>}
+ */
+export const PARTICLE_NODE_TYPE_RENAMES = new Map([
+    ["attribute", "particleField"],
+    ["setAttribute", "setParticleField"],
+]);
+
 /**
  * @typedef {object} ParticleGraphJSON
  * @property {Array<{id: number, type: string, parameters: object, x?: number, y?: number}>} nodes
@@ -96,7 +109,8 @@ export function deserialize_particle_graph({ json, graph, visual, visualRegistry
     }
 
     for (const record of json.nodes ?? []) {
-        const description = resolve?.(record.type) ?? get_particle_library_description(record.type);
+        const type = PARTICLE_NODE_TYPE_RENAMES.get(record.type) ?? record.type;
+        const description = resolve?.(type) ?? get_particle_library_description(type);
 
         if (!Number.isInteger(record.id) || record.id < 0) {
             throw new Error(`Particle graph node id must be a non-negative integer, got ${record.id}`);
@@ -116,7 +130,7 @@ export function deserialize_particle_graph({ json, graph, visual, visualRegistry
         // declares none — its configuration is the wiring inside it — and has no defaults to ask for.
         const defaults = is_particle_group_description(description)
             ? {}
-            : particle_node_default_parameters(record.type);
+            : particle_node_default_parameters(type);
 
         node.setParameters({ ...defaults, ...(record.parameters ?? {}) });
 

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

@@ -32,19 +32,25 @@ export function particle_node_parameters(type: string): ParticleNodeParameter[];
  * 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.
+ * Field parameters have no default of their own: the only sensible one is a name from the effect
+ * being authored, so the layout the field lives in has to be supplied, and the default is its
+ * first field. 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
+ *   particle field schema, for particle field parameters
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [context.emitter_layout] the
+ *   effect's emitter field schema, for emitter field parameters
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [context.global_layout] the
+ *   global fields the effect imports, for global field parameters
  * @returns {object}
  */
-export function particle_node_default_parameters(type: string, { layout }?: {
+export function particle_node_default_parameters(type: string, { layout, emitter_layout, global_layout }?: {
     layout?: import("../layout/ParticleLayout.js").ParticleLayout;
+    emitter_layout?: import("../layout/ParticleLayout.js").ParticleLayout | null;
+    global_layout?: import("../layout/ParticleLayout.js").ParticleLayout | null;
 }): object;
 /**
  * Every node type in the library paired with its parameters, for a palette to list.
@@ -68,9 +74,9 @@ export type PARTICLE_PARAMETER_KIND = string;
  * 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.
+ * particle field 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,
@@ -85,8 +91,12 @@ export const PARTICLE_PARAMETER_KIND: Readonly<{
     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";
+    /** the name of a particle field in the effect's {@link ../layout/ParticleLayout.js} */
+    PARTICLE_FIELD: "particle_field";
+    /** the name of an emitter field in the effect's emitter layout */
+    EMITTER_FIELD: "emitter_field";
+    /** the name of a global field the effect imports */
+    GLOBAL_FIELD: "global_field";
     /** 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 */
@@ -108,8 +118,10 @@ export const PARTICLE_PARAMETER_KIND: Readonly<{
  * @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 {*} [default] the value a freshly created node takes; absent for the field kinds
+ *   ({@link PARTICLE_PARAMETER_KIND.PARTICLE_FIELD}, {@link PARTICLE_PARAMETER_KIND.EMITTER_FIELD},
+ *   {@link PARTICLE_PARAMETER_KIND.GLOBAL_FIELD}), whose default can only come from the effect's
+ *   layouts
  * @property {Object<string, *>} [options] for {@link PARTICLE_PARAMETER_KIND.ENUM}: label -> value
  * @property {boolean} [alpha] for {@link PARTICLE_PARAMETER_KIND.GRADIENT}: whether the node reads
  *   the alpha channel. Both gradients *store* one — see {@link ./particle_ramp.js} — so that a
@@ -159,8 +171,10 @@ export type ParticleNodeParameter = {
      */
     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
+     * the value a freshly created node takes; absent for the field kinds
+     * ({@link PARTICLE_PARAMETER_KIND.PARTICLE_FIELD }, {@link PARTICLE_PARAMETER_KIND.EMITTER_FIELD },
+     * {@link PARTICLE_PARAMETER_KIND.GLOBAL_FIELD }), whose default can only come from the effect's
+     * layouts
      */
     default?: any;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"particle_node_parameters.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_node_parameters.js"],"names":[],"mappings":"AAgMA;;;;;;;;;;;;;;;;;GAiBG;AACH,sDAHW,MAAM,GACJ,MAAM,CAIlB;AAwBD;;;;;;GAMG;AACH,+CAJW,MAAM,GACJ,qBAAqB,EAAE,CAcnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,uDANW,MAAM;IAEyD,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAElD,MAAM,CAmBlB;AAED;;;;GAIG;AACH,2CAFa,MAAM;IAAC,WAAW,EAAE,OAAO,8BAA8B,EAAE,uBAAuB,CAAC;IAAC,UAAU,EAAE,qBAAqB,EAAE,CAAA;CAAC,CAAC,CAOrI;;;;sCArRS,MAAM;AApBhB;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH;IACI,0FAA0F;;IAE1F,kFAAkF;;IAElF,mFAAmF;;IAEnF,2EAA2E;;IAE3E,kEAAkE;;IAElE;;;OAGG;;IAEH;;;OAGG;;GAEJ;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH,gDAFU,MAAM,EAAE,CAYf;AAEH;;;;;GAKG;AACH;QAFiB,MAAM,GAAE,MAAM;EAI7B;AAEF;;;;;GAKG;AACH;QAFiB,MAAM,GAAE,qBAAqB,EAAE;EAuF7C;;;;;;;;UAvIW,MAAM;;;;UACN,MAAM;;;;;;;;;;YAGC,MAAM;;;;;;;;YACb,OAAO;;;;kBAIP,MAAM"}
+{"version":3,"file":"particle_node_parameters.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_node_parameters.js"],"names":[],"mappings":"AAkNA;;;;;;;;;;;;;;;;;GAiBG;AACH,sDAHW,MAAM,GACJ,MAAM,CAIlB;AAwBD;;;;;;GAMG;AACH,+CAJW,MAAM,GACJ,qBAAqB,EAAE,CAcnC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,uDAVW,MAAM;IAEyD,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAEgB,cAAc,GAAlF,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI;IAEW,aAAa,GAAjF,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI;IAEvD,MAAM,CA6BlB;AAED;;;;GAIG;AACH,2CAFa,MAAM;IAAC,WAAW,EAAE,OAAO,8BAA8B,EAAE,uBAAuB,CAAC;IAAC,UAAU,EAAE,qBAAqB,EAAE,CAAA;CAAC,CAAC,CAOrI;;;;sCArTS,MAAM;AApBhB;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH;IACI,0FAA0F;;IAE1F,kFAAkF;;IAElF,uFAAuF;;IAEvF,kEAAkE;;IAElE,oDAAoD;;IAEpD,2EAA2E;;IAE3E,kEAAkE;;IAElE;;;OAGG;;IAEH;;;OAGG;;GAEJ;AAEH;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;GASG;AACH,gDAFU,MAAM,EAAE,CAYf;AAEH;;;;;GAKG;AACH;QAFiB,MAAM,GAAE,MAAM;EAI7B;AAEF;;;;;GAKG;AACH;QAFiB,MAAM,GAAE,qBAAqB,EAAE;EAmG7C;;;;;;;;UArJW,MAAM;;;;UACN,MAAM;;;;;;;;;;;;YAKC,MAAM;;;;;;;;YACb,OAAO;;;;kBAIP,MAAM"}