@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -13,9 +13,9 @@ import { PARTICLE_VALUE_TYPES } from "./ParticleValueType.js";
  * 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,
@@ -31,8 +31,12 @@ export const PARTICLE_PARAMETER_KIND = Object.freeze({
     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 */
@@ -55,8 +59,10 @@ export const PARTICLE_PARAMETER_KIND = Object.freeze({
  * @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
@@ -132,10 +138,22 @@ export const PARTICLE_NODE_PARAMETER_SCHEMA = Object.freeze({
         description: "Which per-invocation value the host shader hands the VM.",
     }],
 
-    attribute: [{
+    particleField: [{
         name: "name",
-        kind: PARTICLE_PARAMETER_KIND.ATTRIBUTE,
-        description: "The per-particle attribute to read, by name in the effect's layout.",
+        kind: PARTICLE_PARAMETER_KIND.PARTICLE_FIELD,
+        description: "The particle field to read, by name in the effect's layout.",
+    }],
+
+    emitterField: [{
+        name: "name",
+        kind: PARTICLE_PARAMETER_KIND.EMITTER_FIELD,
+        description: "The emitter field to read, by name in the effect's emitter layout.",
+    }],
+
+    globalField: [{
+        name: "name",
+        kind: PARTICLE_PARAMETER_KIND.GLOBAL_FIELD,
+        description: "The global field to read, by name among the ones the effect imports.",
     }],
 
     // Four is the width a draw had before it had one — as wide as anything could read it — so an
@@ -149,10 +167,10 @@ export const PARTICLE_NODE_PARAMETER_SCHEMA = Object.freeze({
         description: "How many independent draws, one per lane: a scalar, or a vector of them.",
     }],
 
-    setAttribute: [{
+    setParticleField: [{
         name: "name",
-        kind: PARTICLE_PARAMETER_KIND.ATTRIBUTE,
-        description: "The per-particle attribute to write, by name in the effect's layout.",
+        kind: PARTICLE_PARAMETER_KIND.PARTICLE_FIELD,
+        description: "The particle field to write, by name in the effect's layout.",
     }],
 
     compare: [{
@@ -261,25 +279,39 @@ export function particle_node_parameters(type) {
  * 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, { layout } = {}) {
+export function particle_node_default_parameters(type, { layout, emitter_layout, global_layout } = {}) {
     const result = {};
 
-    const first_attribute = layout === undefined ? undefined : layout.attributes.keys().next().value;
+    const first_particle_field = layout === undefined ? undefined : layout.fields.keys().next().value;
+    const first_emitter_field = emitter_layout === undefined || emitter_layout === null
+        ? undefined
+        : emitter_layout.fields.keys().next().value;
+    const first_global_field = global_layout === undefined || global_layout === null
+        ? undefined
+        : global_layout.fields.keys().next().value;
 
     for (const parameter of particle_node_parameters(type)) {
-        if (parameter.kind === PARTICLE_PARAMETER_KIND.ATTRIBUTE) {
-            result[parameter.name] = first_attribute ?? "";
+        if (parameter.kind === PARTICLE_PARAMETER_KIND.PARTICLE_FIELD) {
+            result[parameter.name] = first_particle_field ?? "";
+        } else if (parameter.kind === PARTICLE_PARAMETER_KIND.EMITTER_FIELD) {
+            result[parameter.name] = first_emitter_field ?? "";
+        } else if (parameter.kind === PARTICLE_PARAMETER_KIND.GLOBAL_FIELD) {
+            result[parameter.name] = first_global_field ?? "";
         } else {
             // A default that is not a number is mutable, and a node writes through to its own: a
             // shared one would make every node of the type the same node, and editing one gradient

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

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

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

@@ -4,8 +4,8 @@
  *
  * The library's own names are addresses — they are what a saved graph holds and what
  * {@link ./ParticleNodeRegistry.js get_particle_node_description} looks a type up by — so they are
- * terse and they do not change. `div`, `mad`, `setAttribute`. Nobody reads those as "divide",
- * "multiply-add" and "write attribute" without translating, and an editor that shows only them
+ * terse and they do not change. `div`, `mad`, `setParticleField`. Nobody reads those as "divide",
+ * "multiply-add" and "write particle field" without translating, and an editor that shows only them
  * makes every author do that translation on every node, every time.
  *
  * So the names stay what they are and this says what to draw instead. Kept out of the registry
@@ -66,10 +66,20 @@ export const PARTICLE_NODE_PRESENTATION = Object.freeze({
         icon: "M6 7h12v10H6z M9 4v3 M15 4v3 M9 17v3 M15 17v3",
         help: "a value the host provides — delta time, emitter position…",
     },
-    attribute: {
-        label: "Read Attribute",
+    particleField: {
+        label: "Read Particle Field",
         icon: "M5 5v14 M8 12h11 M16 9l3 3-3 3",
-        help: "read one of this effect's per-particle attributes",
+        help: "read one of this effect's particle fields",
+    },
+    globalField: {
+        label: "Read Global Field",
+        icon: "M12 4a8 8 0 1 0 0 16a8 8 0 1 0 0-16 M4 12h16 M12 4c-3 3-3 13 0 16 M12 4c3 3 3 13 0 16",
+        help: "read one of the system's global fields, which every effect shares",
+    },
+    emitterField: {
+        label: "Read Emitter Field",
+        icon: "M4 5h5v14H4z M11 12h8 M16 9l3 3-3 3",
+        help: "read one of the fields every emitter of this effect carries for itself",
     },
     random: {
         label: "Random",
@@ -78,10 +88,10 @@ export const PARTICLE_NODE_PRESENTATION = Object.freeze({
     },
 
     // --- sinks ---
-    setAttribute: {
-        label: "Write Attribute",
+    setParticleField: {
+        label: "Write Particle Field",
         icon: "M19 5v14 M5 12h11 M13 9l3 3-3 3",
-        help: "write a per-particle attribute",
+        help: "write one of this effect's particle fields",
     },
     kill: {
         label: "Kill Particle",

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

@@ -2,13 +2,20 @@
  * @param {NodeGraph} graph
  * @param {object} [context]
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
- *   attribute schema; without it, attribute references cannot be checked and are left alone
+ *   particle field schema; without it, particle field references cannot be checked and are left
+ *   alone
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [context.emitter_layout] the
+ *   effect's emitter field schema; without it, emitter field references are left alone
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [context.global_layout] the
+ *   global fields the effect imports; without it, global field references are left alone
  * @param {string} [context.phase] which {@link PARTICLE_GRAPH_PHASE} this graph is; without it the
  *   checks that only hold for one phase are skipped rather than guessed at
  * @returns {ParticleGraphDiagnostic[]}
  */
-export function validate_particle_graph(graph: NodeGraph, { layout, phase }?: {
+export function validate_particle_graph(graph: NodeGraph, { layout, emitter_layout, global_layout, phase }?: {
     layout?: import("../layout/ParticleLayout.js").ParticleLayout;
+    emitter_layout?: import("../layout/ParticleLayout.js").ParticleLayout | null;
+    global_layout?: import("../layout/ParticleLayout.js").ParticleLayout | null;
     phase?: string;
 }): ParticleGraphDiagnostic[];
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"validate_particle_graph.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/validate_particle_graph.js"],"names":[],"mappings":"AA+DA;;;;;;;;GAQG;AACH;IAN0E,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAEnC,KAAK,GAAtB,MAAM;IAEJ,yBAAyB,CAoDrC;;;;;;;;mCAlES,MAAM;AA5ChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;GAQG;AACH;;;GAGG"}
+{"version":3,"file":"validate_particle_graph.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/validate_particle_graph.js"],"names":[],"mappings":"AA+DA;;;;;;;;;;;;;GAaG;AACH;IAX0E,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAGgB,cAAc,GAAlF,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI;IAEW,aAAa,GAAjF,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI;IAExC,KAAK,GAAtB,MAAM;IAEJ,yBAAyB,CAoDrC;;;;;;;;mCAvES,MAAM;AA5ChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;GAQG;AACH;;;GAGG"}

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

@@ -65,12 +65,17 @@ export const PARTICLE_GRAPH_PHASE = Object.freeze({
  * @param {NodeGraph} graph
  * @param {object} [context]
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
- *   attribute schema; without it, attribute references cannot be checked and are left alone
+ *   particle field schema; without it, particle field references cannot be checked and are left
+ *   alone
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [context.emitter_layout] the
+ *   effect's emitter field schema; without it, emitter field references are left alone
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [context.global_layout] the
+ *   global fields the effect imports; without it, global field references are left alone
  * @param {string} [context.phase] which {@link PARTICLE_GRAPH_PHASE} this graph is; without it the
  *   checks that only hold for one phase are skipped rather than guessed at
  * @returns {ParticleGraphDiagnostic[]}
  */
-export function validate_particle_graph(graph, { layout, phase } = {}) {
+export function validate_particle_graph(graph, { layout, emitter_layout = undefined, global_layout = undefined, phase } = {}) {
     /** @type {ParticleGraphDiagnostic[]} */
     const diagnostics = [];
 
@@ -103,13 +108,13 @@ export function validate_particle_graph(graph, { layout, phase } = {}) {
         }
 
         check_inputs(node, description, error);
-        check_parameters(node, description, layout, error);
+        check_parameters(node, description, layout, emitter_layout ?? undefined, global_layout ?? undefined, error);
     }
 
     if (sinks.length === 0) {
         error(
             -1,
-            "Nothing in this graph writes an attribute or kills a particle, so none of it runs. "
+            "Nothing in this graph writes a particle field or kills a particle, so none of it runs. "
             + "Compilation starts from the sinks."
         );
     }
@@ -117,7 +122,7 @@ export function validate_particle_graph(graph, { layout, phase } = {}) {
     report_duplicate_writes(sinks, layout, error);
     report_missing_kill(sinks, phase, warning);
     report_cycles(nodes, error);
-    report_conversions(graph, layout, diagnostics);
+    report_conversions(graph, layout, emitter_layout ?? undefined, global_layout ?? undefined, diagnostics);
 
     return report_unreachable(nodes, sinks, diagnostics);
 }
@@ -149,9 +154,11 @@ function check_inputs(node, description, error) {
  * @param {NodeInstance} node
  * @param {ParticleNodeDescription} description
  * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} layout
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} emitter_layout
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} global_layout
  * @param {function(number, string):void} error
  */
-function check_parameters(node, description, layout, error) {
+function check_parameters(node, description, layout, emitter_layout, global_layout, error) {
     if (is_particle_group_description(description)) {
         // A group's configuration is its wiring and its boundary blocks are its edge; neither
         // declares parameters, and what is inside a group was checked when the group was built.
@@ -176,12 +183,40 @@ function check_parameters(node, description, layout, error) {
         }
 
         switch (parameter.kind) {
-            case PARTICLE_PARAMETER_KIND.ATTRIBUTE:
+            case PARTICLE_PARAMETER_KIND.PARTICLE_FIELD:
                 if (layout !== undefined && !layout.has(value)) {
                     error(
                         node.id,
-                        `'${value}' is not an attribute of this effect. It has: `
-                        + `${Array.from(layout.attributes.keys()).join(", ") || "none"}.`
+                        `'${value}' is not a particle field of this effect. It has: `
+                        + `${Array.from(layout.fields.keys()).join(", ") || "none"}.`
+                    );
+                }
+                break;
+
+            case PARTICLE_PARAMETER_KIND.EMITTER_FIELD:
+                if (emitter_layout === undefined) {
+                    break;
+                }
+
+                if (!emitter_layout.has(value)) {
+                    error(
+                        node.id,
+                        `'${value}' is not an emitter field of this effect. It has: `
+                        + `${Array.from(emitter_layout.fields.keys()).join(", ") || "none"}.`
+                    );
+                }
+                break;
+
+            case PARTICLE_PARAMETER_KIND.GLOBAL_FIELD:
+                if (global_layout === undefined) {
+                    break;
+                }
+
+                if (!global_layout.has(value)) {
+                    error(
+                        node.id,
+                        `'${value}' is not a global field this effect imports. It imports: `
+                        + `${Array.from(global_layout.fields.keys()).join(", ") || "none"}.`
                     );
                 }
                 break;
@@ -262,16 +297,17 @@ function check_parameters(node, description, layout, error) {
  * them. What each check tests is what a sink *does* — store a value, end a life — and the library
  * says which does what by type, so a sink added to it that also stores or also kills belongs here.
  */
-const SET_ATTRIBUTE_NODE = "setAttribute";
+const SET_PARTICLE_FIELD_NODE = "setParticleField";
 const KILL_NODE = "kill";
 
 /**
- * A `setAttribute` node lowers to a store at its attribute's offset, and the program is
- * straight-line: two stores to one attribute both run, and which of them is last — which is to say
- * which value survives — is whatever order the compiler's traversal happened to take. That is not a
- * merge anyone asked for. Combining two values is a `select` or a `mix` in front of one write.
+ * A `setParticleField` node lowers to a store at its particle field's offset, and the program is
+ * straight-line: two stores to one particle field both run, and which of them is last — which is to
+ * say which value survives — is whatever order the compiler's traversal happened to take. That is
+ * not a merge anyone asked for. Combining two values is a `select` or a `mix` in front of one
+ * write.
  *
- * Reported against every node that writes the attribute, for the reason {@link report_cycles}
+ * Reported against every node that writes the particle field, for the reason {@link report_cycles}
  * reports against every node on a cycle: no one of them is the offender.
  *
  * Per graph, not per effect. Writing `age` in INIT and again in UPDATE is how a particle ages —
@@ -282,38 +318,38 @@ const KILL_NODE = "kill";
  * @param {function(number, string):void} error
  */
 function report_duplicate_writes(sinks, layout, error) {
-    /** @type {Map<*, NodeInstance[]>} attribute -> the nodes writing it */
+    /** @type {Map<*, NodeInstance[]>} particle field -> the nodes writing it */
     const writers = new Map();
 
     for (const node of sinks) {
-        if (node.description.name !== SET_ATTRIBUTE_NODE) {
+        if (node.description.name !== SET_PARTICLE_FIELD_NODE) {
             continue;
         }
 
-        const attribute = node.getParameterValue("name");
+        const particle_field = node.getParameterValue("name");
 
-        if (attribute === undefined) {
-            // the node names no attribute at all; check_parameters has already said so
+        if (particle_field === undefined) {
+            // the node names no particle field at all; check_parameters has already said so
             continue;
         }
 
-        if (layout !== undefined && !layout.has(attribute)) {
-            // The attribute does not exist, so neither store is one the compiler will ever emit and
-            // there is no race to report. What is wrong with these nodes is the name they carry, and
-            // check_parameters has already said that about each of them.
+        if (layout !== undefined && !layout.has(particle_field)) {
+            // The particle field does not exist, so neither store is one the compiler will ever
+            // emit and there is no race to report. What is wrong with these nodes is the name they
+            // carry, and check_parameters has already said that about each of them.
             continue;
         }
 
-        const written = writers.get(attribute);
+        const written = writers.get(particle_field);
 
         if (written === undefined) {
-            writers.set(attribute, [node]);
+            writers.set(particle_field, [node]);
         } else {
             written.push(node);
         }
     }
 
-    for (const [attribute, written] of writers) {
+    for (const [particle_field, written] of writers) {
         if (written.length < 2) {
             continue;
         }
@@ -321,9 +357,9 @@ function report_duplicate_writes(sinks, layout, error) {
         for (const node of written) {
             error(
                 node.id,
-                `${written.length} nodes write '${attribute}' in this phase, and nothing orders them. `
+                `${written.length} nodes write '${particle_field}' in this phase, and nothing orders them. `
                 + "Every store runs, so the value that survives is whichever one the compiler reaches "
-                + "last. Combine them with a 'select' or a 'mix' and write the attribute once."
+                + "last. Combine them with a 'select' or a 'mix' and write the particle field once."
             );
         }
     }
@@ -362,7 +398,7 @@ function report_missing_kill(sinks, phase, warning) {
 /**
  * A value wired into a port that reads it as a different shape is converted on the way in — a
  * wider vector keeps its leading lanes, a narrower one reads zero past its content — and each such
- * conversion is worth a word, because a `vec4` literal feeding a three-component attribute is
+ * conversion is worth a word, because a `vec4` literal feeding a three-component particle field is
  * either a slip or a literal that ought to be a `vec3`. A scalar meeting a vector broadcasts, which
  * is what a scalar is for, and says nothing.
  *
@@ -372,10 +408,12 @@ function report_missing_kill(sinks, phase, warning) {
  *
  * @param {NodeGraph} graph
  * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} layout
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} emitter_layout
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} global_layout
  * @param {ParticleGraphDiagnostic[]} diagnostics
  */
-function report_conversions(graph, layout, diagnostics) {
-    diagnostics.push(...infer_particle_graph_types(graph, { layout }).diagnostics);
+function report_conversions(graph, layout, emitter_layout, global_layout, diagnostics) {
+    diagnostics.push(...infer_particle_graph_types(graph, { layout, emitter_layout, global_layout }).diagnostics);
 }
 
 /**

package/src/shade/renderer/particles/graph_particles.d.ts

@@ -5,8 +5,8 @@
  *
  * {@link graph_particles_simulate} is everything that moves particles:
  *
- *   reset counters -> spawn commands -> emitter tick -> scan -> spawn args -> emit -> simulate
- *   -> bucket -> bounds -> build indirect
+ *   reset counters -> [field bind] -> spawn commands -> emitter tick -> scan -> spawn args -> emit
+ *   -> simulate -> bucket -> bounds -> build indirect
  *
  * and it leaves the frame's alive list, the pool and the indirect draw args as graph handles for
  * the draw. That draw is not here and is not recorded by `execute` either: the AVBOIT transparency
@@ -60,7 +60,7 @@
  *
  * A buffer is imported only if its contents cross the frame boundary: the pool, the free list, the
  * counters, the alive list, `sim_list` (written here, read by next frame's simulate),
- * `dispatch_args` (the same), the program blob and the two CPU-uploaded queues. Everything else is
+ * `dispatch_args` (the same), the program buffer and the two CPU-uploaded queues. Everything else is
  * produced and consumed inside one graph, so the pass that first writes it declares it with a
  * {@link BufferResourceDescriptor} in place of a handle and the graph allocates it just in time and
  * releases it after its last reader — into the pool every other feature draws from. That is the
@@ -113,9 +113,11 @@
  * @param {number} params.frame.warmup_capacity slots the warm-up's transient pool needs
  * @param {import("./warmup/warmup_schedule.js").WarmupSchedule} params.frame.warmup_schedule how
  *   many ticks the warm-up runs and how long each is
+ * @param {{group_count: number}} [params.field_bindings] the transform binding table's dispatch:
+ *   zero workgroups while nothing is bound, and the bind pass is not recorded then
  * @returns {ParticleSimulationHandles}
  */
-export function graph_particles_simulate({ graph, camera, scene_database, wind, gpu, emitters, capacity, bucket_count, wide_registers, frame, }: {
+export function graph_particles_simulate({ graph, camera, scene_database, wind, gpu, emitters, capacity, bucket_count, wide_registers, frame, field_bindings, }: {
     graph: import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
     camera: number;
     scene_database: number;
@@ -139,6 +141,9 @@ export function graph_particles_simulate({ graph, camera, scene_database, wind,
         warmup_capacity: number;
         warmup_schedule: import("./warmup/warmup_schedule.js").WarmupSchedule;
     };
+    field_bindings?: {
+        group_count: number;
+    };
 }): ParticleSimulationHandles;
 export type ParticleSimulationHandles = {
     /**

package/src/shade/renderer/particles/graph_particles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_particles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/graph_particles.js"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IAjCkG,KAAK,EAA5F,OAAO,2DAA2D,EAAE,UAAU;IAC/D,MAAM,EAArB,MAAM;IACS,cAAc,EAA7B,MAAM;IACiD,IAAI,EAA3D,OAAO,yBAAyB,EAAE,YAAY;IAE/B,GAAG,EAAlB,MAAM;IAGS,QAAQ;QACC,QAAQ,EAAhC,MAAM;QAEkB,WAAW,EAAnC,MAAM;;IACS,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IAEU,cAAc,EAA9B,OAAO;IAGQ,KAAK;QACC,EAAE,EAAvB,MAAM;QACe,IAAI,EAAzB,MAAM;QACe,KAAK,EAA1B,MAAM;QACiB,QAAQ,GAA/B,OAAO;QACc,WAAW,EAAhC,MAAM;QACe,mBAAmB,EAAxC,MAAM;QACe,YAAY,EAAjC,MAAM;QAGe,eAAe,EAApC,MAAM;QAC6D,eAAe,EAAlF,OAAO,6BAA6B,EAAE,cAAc;;IAElD,yBAAyB,CA4UrC;;;;;UAtXa,MAAM;;;;WACN,MAAM;;;;eACN,MAAM;;;;;sBACN,MAAM"}
+{"version":3,"file":"graph_particles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/graph_particles.js"],"names":[],"mappings":"AAiDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH;IAnCkG,KAAK,EAA5F,OAAO,2DAA2D,EAAE,UAAU;IAC/D,MAAM,EAArB,MAAM;IACS,cAAc,EAA7B,MAAM;IACiD,IAAI,EAA3D,OAAO,yBAAyB,EAAE,YAAY;IAE/B,GAAG,EAAlB,MAAM;IAGS,QAAQ;QACC,QAAQ,EAAhC,MAAM;QAEkB,WAAW,EAAnC,MAAM;;IACS,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IAEU,cAAc,EAA9B,OAAO;IAGQ,KAAK;QACC,EAAE,EAAvB,MAAM;QACe,IAAI,EAAzB,MAAM;QACe,KAAK,EAA1B,MAAM;QACiB,QAAQ,GAA/B,OAAO;QACc,WAAW,EAAhC,MAAM;QACe,mBAAmB,EAAxC,MAAM;QACe,YAAY,EAAjC,MAAM;QAGe,eAAe,EAApC,MAAM;QAC6D,eAAe,EAAlF,OAAO,6BAA6B,EAAE,cAAc;;IAErB,cAAc,GAA7C;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC;IAEnB,yBAAyB,CA0VrC;;;;;UAtYa,MAAM;;;;WACN,MAAM;;;;eACN,MAAM;;;;;sBACN,MAAM"}

package/src/shade/renderer/particles/graph_particles.js

@@ -25,6 +25,7 @@ import {
     shader_particle_emit_wide,
 } from "./shaders/shader_particle_emit_wide.js";
 import { shader_particle_emitter_tick } from "./shaders/shader_particle_emitter_tick.js";
+import { shader_particle_field_bind } from "./shaders/shader_particle_field_bind.js";
 import {
     shader_particle_build_indirect,
     shader_particle_reset_counters,
@@ -40,6 +41,12 @@ import {
 } from "./shaders/shader_particle_spawn_commands.js";
 import { graph_particle_warmup } from "./warmup/graph_particle_warmup.js";
 
+/**
+ * What {@link graph_particles_simulate} is told when nothing is bound.
+ * @type {{group_count: number}}
+ */
+const NO_FIELD_BINDINGS = Object.freeze({ group_count: 0 });
+
 /**
  * The simulation half of the particle system's frame, recorded into the frame graph.
  * {@link GPUParticleSystem#execute} is what calls it, with the buffers it owns; nothing else needs
@@ -47,8 +54,8 @@ import { graph_particle_warmup } from "./warmup/graph_particle_warmup.js";
  *
  * {@link graph_particles_simulate} is everything that moves particles:
  *
- *   reset counters -> spawn commands -> emitter tick -> scan -> spawn args -> emit -> simulate
- *   -> bucket -> bounds -> build indirect
+ *   reset counters -> [field bind] -> spawn commands -> emitter tick -> scan -> spawn args -> emit
+ *   -> simulate -> bucket -> bounds -> build indirect
  *
  * and it leaves the frame's alive list, the pool and the indirect draw args as graph handles for
  * the draw. That draw is not here and is not recorded by `execute` either: the AVBOIT transparency
@@ -102,7 +109,7 @@ import { graph_particle_warmup } from "./warmup/graph_particle_warmup.js";
  *
  * A buffer is imported only if its contents cross the frame boundary: the pool, the free list, the
  * counters, the alive list, `sim_list` (written here, read by next frame's simulate),
- * `dispatch_args` (the same), the program blob and the two CPU-uploaded queues. Everything else is
+ * `dispatch_args` (the same), the program buffer and the two CPU-uploaded queues. Everything else is
  * produced and consumed inside one graph, so the pass that first writes it declares it with a
  * {@link BufferResourceDescriptor} in place of a handle and the graph allocates it just in time and
  * releases it after its last reader — into the pool every other feature draws from. That is the
@@ -157,6 +164,8 @@ import { graph_particle_warmup } from "./warmup/graph_particle_warmup.js";
  * @param {number} params.frame.warmup_capacity slots the warm-up's transient pool needs
  * @param {import("./warmup/warmup_schedule.js").WarmupSchedule} params.frame.warmup_schedule how
  *   many ticks the warm-up runs and how long each is
+ * @param {{group_count: number}} [params.field_bindings] the transform binding table's dispatch:
+ *   zero workgroups while nothing is bound, and the bind pass is not recorded then
  * @returns {ParticleSimulationHandles}
  */
 export function graph_particles_simulate({
@@ -170,6 +179,7 @@ export function graph_particles_simulate({
                                              bucket_count,
                                              wide_registers = false,
                                              frame,
+                                             field_bindings = NO_FIELD_BINDINGS,
                                          }) {
     assert.defined(graph, "graph");
     assert.isNonNegativeInteger(camera, "camera");
@@ -177,7 +187,9 @@ export function graph_particles_simulate({
     assert.defined(wind, "wind");
     assert.isPositiveInteger(capacity, "capacity");
 
-    const gr_program = graph_import_buffer(graph, gpu.program, "particles/program");
+    // Renamed by the bind pass when it writes the field section, so it is threaded like every other
+    // buffer more than one pass touches.
+    let gr_program = graph_import_buffer(graph, gpu.program, "particles/program");
     let gr_sim_list = graph_import_buffer(graph, gpu.sim_list, "particles/sim_list");
     let gr_dispatch = graph_import_buffer(graph, gpu.dispatch_args, "particles/dispatch_args");
     // The draw args are the one indirect buffer that does NOT cross the frame boundary: build-
@@ -239,6 +251,17 @@ export function graph_particles_simulate({
         group_count: [1, 1, 1],
     }).counters;
 
+    // 1b. Transform bindings — each bound row's composed `global` into its field, so every VM
+    //     pass after this reads this frame's transforms. Recorded only while something is bound.
+    if (field_bindings.group_count > 0) {
+        gr_program = graph_compute_pass({
+            graph,
+            shader: shader_particle_field_bind,
+            bindings: { scene_database, emitter_database, program: gr_program },
+            group_count: [field_bindings.group_count, 1, 1],
+        }).program;
+    }
+
     // 2. Spawn commands — the CPU's bursts, added to the emitters' pending spawns. The one dispatch
     //    the host sizes, because the host wrote the list.
     if (frame.spawn_command_count > 0) {

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

@@ -16,8 +16,8 @@ export class InstructionStream {
      *
      * A source is what its slot's role in the ISA says: for a register-role slot, a register operand
      * word — a slot index, or `vm_register(slot, pattern)` to read it through a swizzle — or a
-     * literal from `vm_immediate(value)`; for any other role, the raw value (an attribute offset, a
-     * component count, a builtin id, a pool index). The kinds word 0 carries follow
+     * literal from `vm_immediate(value)`; for any other role, the raw value (a particle field
+     * offset, a component count, a builtin id, a pool index). The kinds word 0 carries follow
      * from that, and register operands are stored in their canonical spelling.
      *
      * `width` is the lane count the operation spans. Left out, it is the opcode's natural width —
@@ -75,7 +75,7 @@ export class InstructionStream {
      */
     loadConst(dst: number, constant_index: number, width?: number): InstructionStream;
     /**
-     * Lanes past `component_count` read as zero, which is how a narrow attribute widens into a
+     * Lanes past `component_count` read as zero, which is how a narrow particle field widens into a
      * wider operation without a second instruction.
      *
      * @param {number} dst
@@ -84,7 +84,7 @@ export class InstructionStream {
      * @param {number} [width] defaults to the component count
      * @returns {InstructionStream}
      */
-    loadAttr(dst: number, word_offset: number, component_count: number, width?: number): InstructionStream;
+    loadParticleField(dst: number, word_offset: number, component_count: number, width?: number): InstructionStream;
     /**
      * The width is the component count and cannot differ from it: a store writes exactly the lanes
      * the value holds.
@@ -94,13 +94,14 @@ export class InstructionStream {
      * @param {number} component_count
      * @returns {InstructionStream}
      */
-    storeAttr(source: number | {
+    storeParticleField(source: number | {
         kind: number;
         word: number;
     }, word_offset: number, component_count: number): InstructionStream;
     /**
      * @param {number} dst
-     * @param {number} builtin_id
+     * @param {number} builtin_id a `VM_BUILTIN`, or a field id from `vm_builtin_emitter_field` or
+     *   `vm_builtin_global_field`
      * @param {number} [width]
      * @returns {InstructionStream}
      */

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

@@ -1 +1 @@
-{"version":3,"file":"InstructionStream.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/InstructionStream.js"],"names":[],"mappings":"AAkCA;;;;;;GAMG;AACH;IACI,yCAAyC;IACzC,cADW,MAAM,EAAE,EAAE,CACH;IAClB,iEAAiE;IACjE,gBADW,MAAM,CACE;IAsBnB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SARW,MAAM,QACN,MAAM,OACN,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,OACnC,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,OACnC,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,UACnC,MAAM,GACJ,iBAAiB,CA6D7B;IAED;;;;;;OAMG;IACH,iBAHW,UAAU,MAAM,CAAC,GACf,iBAAiB,CAS7B;IAID;;;;;OAKG;IACH,SALW,MAAM,OACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;;;OAQG;IACH,eALW,MAAM,OACN,MAAM,SACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;OAKG;IACH,eALW,MAAM,kBACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;;;;OASG;IACH,cANW,MAAM,eACN,MAAM,mBACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAK7B;IAED;;;;;;;;OAQG;IACH,kBALW,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,eACnC,MAAM,mBACN,MAAM,GACJ,iBAAiB,CAK7B;IAED;;;;;OAKG;IACH,iBALW,MAAM,cACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;OAGG;IACH,gBAHW,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GACjC,iBAAiB,CAI7B;IAED;;;;;;;;OAQG;IACH,YAJW,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;;;OAQG;IACH,gBALW,MAAM,YACN,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,UACnC,MAAM,GACJ,iBAAiB,CAI7B;IAED;;OAEG;IACH,QAFa,iBAAiB,CAI7B;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,WAFa,WAAW,CAWvB;;CACJ"}
+{"version":3,"file":"InstructionStream.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/InstructionStream.js"],"names":[],"mappings":"AAkCA;;;;;;GAMG;AACH;IACI,yCAAyC;IACzC,cADW,MAAM,EAAE,EAAE,CACH;IAClB,iEAAiE;IACjE,gBADW,MAAM,CACE;IAsBnB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SARW,MAAM,QACN,MAAM,OACN,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,OACnC,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,OACnC,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,UACnC,MAAM,GACJ,iBAAiB,CA6D7B;IAED;;;;;;OAMG;IACH,iBAHW,UAAU,MAAM,CAAC,GACf,iBAAiB,CAS7B;IAID;;;;;OAKG;IACH,SALW,MAAM,OACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;;;OAQG;IACH,eALW,MAAM,OACN,MAAM,SACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;OAKG;IACH,eALW,MAAM,kBACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;;;;OASG;IACH,uBANW,MAAM,eACN,MAAM,mBACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAK7B;IAED;;;;;;;;OAQG;IACH,2BALW,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,eACnC,MAAM,mBACN,MAAM,GACJ,iBAAiB,CAK7B;IAED;;;;;;OAMG;IACH,iBANW,MAAM,cACN,MAAM,UAEN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;OAGG;IACH,gBAHW,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GACjC,iBAAiB,CAI7B;IAED;;;;;;;;OAQG;IACH,YAJW,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;;;OAQG;IACH,gBALW,MAAM,YACN,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,UACnC,MAAM,GACJ,iBAAiB,CAI7B;IAED;;OAEG;IACH,QAFa,iBAAiB,CAI7B;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,WAFa,WAAW,CAWvB;;CACJ"}