@woosh/meep-engine 3.57.0 → 3.59.0

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

@@ -3,9 +3,10 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 
 /**
  * One emitter's GPU record: which compiled program it runs and where that program's code and
- * constants sit in the {@link ../runtime/ProgramArena.js} buffers, plus the instance parameters the
- * tick / emit / simulate / render passes read — the scene node it hangs off, spawn rate,
- * feature flags, render-attribute bindings, atlas region and flipbook grid.
+ * constants and the emitter's block of emitter fields sit in the {@link ../runtime/ProgramHeap.js}
+ * buffer, plus the instance parameters the tick / emit / simulate / render passes read — the scene
+ * node it hangs off, spawn rate, feature flags, render-channel bindings, atlas region and flipbook
+ * grid.
  *
  * There is no transform here. An emitter is a scene node, and its world matrix is the `global` of
  * its row in the scene database's `transforms` table, composed on the GPU by the hierarchy pass
@@ -20,8 +21,8 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
  * It lives in a `GPUDatabase` table (see {@link ./PARTICLE_DATABASE_SPEC.js}), so the layout below
  * is the *only* description of it that exists: the JS writer is
  * {@link ../../shader/type/serde/write_gpu_typed_buffer.js} and the WGSL reader is generated from
- * this same struct by the table descriptor. Nothing hand-packs an emitter word by word any more,
- * and there is no second copy of the offsets to keep in step.
+ * this same struct by the table descriptor. Nothing hand-packs an emitter word by word, and there is
+ * no second copy of the offsets to keep in step.
  *
  * `.pack()` reorders the fields to close the padding a declaration-order layout would leave; WGSL
  * field names are what shaders address, never offsets, so the reordering is invisible to them.
@@ -37,7 +38,7 @@ export const PARTICLE_EMITTER_STRUCT = WebGPUStruct.from({
     update_offset: u32,
     /** UPDATE instruction count */
     update_count: u32,
-    /** base into the shared constant pool, in vec4 units */
+    /** base into the shared constant pool, in words */
     constant_offset: u32,
     /** base RNG seed */
     seed: u32,
@@ -60,21 +61,21 @@ export const PARTICLE_EMITTER_STRUCT = WebGPUStruct.from({
      */
     generation: u32,
 
-    /** attribute word offset of world position (or {@link EMITTER_ATTRIBUTE_ABSENT}) */
+    /** particle field word offset of world position (or {@link PARTICLE_FIELD_ABSENT}) */
     render_position: u32,
-    /** attribute word offset of size */
+    /** particle field word offset of size */
     render_size: u32,
-    /** attribute word offset of rgba colour */
+    /** particle field word offset of rgba colour */
     render_color: u32,
     /**
-     * attribute word offset of the orientation: a quaternion (x, y, z, w) turning the sprite inside
-     * its projection mode's frame — in the world under FACING_WORLD, relative to the view under
-     * BILLBOARD, where a turn about +Z is a roll
+     * particle field word offset of the orientation: a quaternion (x, y, z, w) turning the sprite
+     * inside its projection mode's frame — in the world under FACING_WORLD, relative to the view
+     * under BILLBOARD, where a turn about +Z is a roll
      */
     render_orientation: u32,
-    /** attribute word offset of flipbook frame index */
+    /** particle field word offset of flipbook frame index */
     render_frame: u32,
-    /** attribute word offset of velocity (STRETCHED projection) */
+    /** particle field word offset of velocity (STRETCHED projection) */
     render_velocity: u32,
 
     /** uv offset .xy + uv scale .zw */
@@ -93,10 +94,18 @@ export const PARTICLE_EMITTER_STRUCT = WebGPUStruct.from({
      * climbing with churn.
      */
     program_id: u32,
+
+    /**
+     * First word of this emitter's block of emitter fields, counted from the start of the packed
+     * program buffer's field section — see {@link ../runtime/ProgramHeap.js}. The block is this
+     * emitter's alone, where the program is shared. `0` for an emitter whose effect declares no
+     * emitter fields, which reads nothing.
+     */
+    field_offset: u32,
 }, "ParticleEmitter").pack();
 
-/** Sentinel for an absent render-attribute binding. */
-export const EMITTER_ATTRIBUTE_ABSENT = 0xffffffff;
+/** Sentinel for a render channel bound to no particle field. */
+export const PARTICLE_FIELD_ABSENT = 0xffffffff;
 
 /**
  * Emitter flag bits. Blend mode occupies bits [4,6), projection mode bits [6,9).

package/src/shade/renderer/particles/data/PARTICLE_FIELD_BINDING.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What a transform binding writes into a field: which part of the bound row's composed `global`.
+ * Each is read the way the emitter's own builtin of the same name is, so a field bound to an
+ * entity reads as that entity's `EMITTER_POSITION` / `_DIRECTION` / `_UP` would.
+ *
+ * Wire format of the binding table, which only this system writes.
+ */
+export type PARTICLE_FIELD_BINDING_CHANNEL = number;
+/**
+ * What a transform binding writes into a field: which part of the bound row's composed `global`.
+ * Each is read the way the emitter's own builtin of the same name is, so a field bound to an
+ * entity reads as that entity's `EMITTER_POSITION` / `_DIRECTION` / `_UP` would.
+ *
+ * Wire format of the binding table, which only this system writes.
+ *
+ * @enum {number}
+ */
+export const PARTICLE_FIELD_BINDING_CHANNEL: Readonly<{
+    /** the origin, three words */
+    POSITION: 0;
+    /** normalised -Z, three words */
+    DIRECTION: 1;
+    /** normalised +Y, three words */
+    UP: 2;
+    /** the rotation as a quaternion (x, y, z, w), scale and any mirror removed, four words */
+    ORIENTATION: 3;
+}>;
+/**
+ * Words each {@link PARTICLE_FIELD_BINDING_CHANNEL} writes. A field is bound to a channel only at
+ * exactly this width.
+ *
+ * @type {Readonly<Object<number, number>>}
+ */
+export const PARTICLE_FIELD_BINDING_CHANNEL_COMPONENTS: Readonly<{
+    [x: number]: number;
+}>;
+/**
+ * One transform binding: a row of the scene's `transforms` table, written every frame into a field
+ * of the program heap's field section — a global field, or a word of an emitter's block.
+ *
+ * A row of the `field_bindings` table of the particle database ({@link ./PARTICLE_DATABASE_SPEC.js}),
+ * staged by the CPU, read by `shaders/shader_particle_field_bind.js`. The bound words are written
+ * from scratch every frame, so a CPU upload landing on one is overwritten before any VM pass reads
+ * it — the same argument that lets the scene's `transforms` table mix CPU fields with a GPU-written
+ * `global`.
+ *
+ * @type {WebGPUStruct}
+ */
+export const PARTICLE_FIELD_BINDING_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=PARTICLE_FIELD_BINDING.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PARTICLE_FIELD_BINDING.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_FIELD_BINDING.js"],"names":[],"mappings":";;;;;;;6CAUU,MAAM;AAPhB;;;;;;;;GAQG;AACH;IACI,8BAA8B;;IAE9B,iCAAiC;;IAEjC,iCAAiC;;IAEjC,0FAA0F;;GAE3F;AAEH;;;;;GAKG;AACH,wDAFU;QAAgB,MAAM,GAAE,MAAM;EAAE,CAOvC;AAEH;;;;;;;;;;;GAWG;AACH,4CAFU,YAAY,CASY;6BAtDL,mCAAmC"}

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

@@ -0,0 +1,56 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * What a transform binding writes into a field: which part of the bound row's composed `global`.
+ * Each is read the way the emitter's own builtin of the same name is, so a field bound to an
+ * entity reads as that entity's `EMITTER_POSITION` / `_DIRECTION` / `_UP` would.
+ *
+ * Wire format of the binding table, which only this system writes.
+ *
+ * @enum {number}
+ */
+export const PARTICLE_FIELD_BINDING_CHANNEL = Object.freeze({
+    /** the origin, three words */
+    POSITION: 0,
+    /** normalised -Z, three words */
+    DIRECTION: 1,
+    /** normalised +Y, three words */
+    UP: 2,
+    /** the rotation as a quaternion (x, y, z, w), scale and any mirror removed, four words */
+    ORIENTATION: 3,
+});
+
+/**
+ * Words each {@link PARTICLE_FIELD_BINDING_CHANNEL} writes. A field is bound to a channel only at
+ * exactly this width.
+ *
+ * @type {Readonly<Object<number, number>>}
+ */
+export const PARTICLE_FIELD_BINDING_CHANNEL_COMPONENTS = Object.freeze({
+    [PARTICLE_FIELD_BINDING_CHANNEL.POSITION]: 3,
+    [PARTICLE_FIELD_BINDING_CHANNEL.DIRECTION]: 3,
+    [PARTICLE_FIELD_BINDING_CHANNEL.UP]: 3,
+    [PARTICLE_FIELD_BINDING_CHANNEL.ORIENTATION]: 4,
+});
+
+/**
+ * One transform binding: a row of the scene's `transforms` table, written every frame into a field
+ * of the program heap's field section — a global field, or a word of an emitter's block.
+ *
+ * A row of the `field_bindings` table of the particle database ({@link ./PARTICLE_DATABASE_SPEC.js}),
+ * staged by the CPU, read by `shaders/shader_particle_field_bind.js`. The bound words are written
+ * from scratch every frame, so a CPU upload landing on one is overwritten before any VM pass reads
+ * it — the same argument that lets the scene's `transforms` table mix CPU fields with a GPU-written
+ * `global`.
+ *
+ * @type {WebGPUStruct}
+ */
+export const PARTICLE_FIELD_BINDING_STRUCT = WebGPUStruct.from({
+    /** row of the scene database's `transforms` table whose composed `global` is read */
+    source: u32,
+    /** first word written, counted from the field section's base */
+    word: u32,
+    /** see {@link PARTICLE_FIELD_BINDING_CHANNEL} */
+    channel: u32,
+}, "ParticleFieldBinding").pack();

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

@@ -1 +1 @@
-{"version":3,"file":"particle_emitter_record.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/particle_emitter_record.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,6CANW,MAAM,WACN,OAAO,+BAA+B,EAAE,eAAe,WACvD,OAAO,yCAAyC,EAAE,yBAAyB,GAEzE,MAAM,CAwClB;AAED;;;;;GAKG;AACH,yCAFa,MAAM,CA2BlB"}
+{"version":3,"file":"particle_emitter_record.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/particle_emitter_record.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,6CANW,MAAM,WACN,OAAO,+BAA+B,EAAE,eAAe,WACvD,OAAO,yCAAyC,EAAE,yBAAyB,GAEzE,MAAM,CAyClB;AAED;;;;;GAKG;AACH,yCAFa,MAAM,CA4BlB"}

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

@@ -43,6 +43,7 @@ export function write_emitter_record(record, emitter, context) {
     record.update_count = placement.update_count;
     record.constant_offset = placement.constant_offset;
     record.program_id = placement.program_id;
+    record.field_offset = context.field_block === null ? 0 : context.field_block.offset;
 
     // Two emitters running one program produce identical particles from identical seeds, and 0 is
     // what an emitter that was never given one has. The generation stands in: it is distinct for
@@ -83,6 +84,7 @@ export function create_emitter_record() {
         update_count: 0,
         constant_offset: 0,
         program_id: 0,
+        field_offset: 0,
 
         seed: 0,
         flags: 0,

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

@@ -9,7 +9,7 @@
  *
  * Every stock operation that takes no parameters of its own is a method here, taken from the library
  * rather than listed — a type added to it is callable the same day. The rest — `const`, `swizzle`,
- * `random`, `curveLiteral` and the attribute nodes — need a parameter and are reached through
+ * `random`, `curveLiteral` and the particle field nodes — need a parameter and are reached through
  * {@link #op}, or through the shorthands below where there is an obvious one.
  *
  * A number where a value is expected becomes a literal, so `g.mul(v, 0.5)` is what it looks like.

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

@@ -17,7 +17,7 @@ import {
  *
  * Every stock operation that takes no parameters of its own is a method here, taken from the library
  * rather than listed — a type added to it is callable the same day. The rest — `const`, `swizzle`,
- * `random`, `curveLiteral` and the attribute nodes — need a parameter and are reached through
+ * `random`, `curveLiteral` and the particle field nodes — need a parameter and are reached through
  * {@link #op}, or through the shorthands below where there is an obvious one.
  *
  * A number where a value is expected becomes a literal, so `g.mul(v, 0.5)` is what it looks like.

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

@@ -37,10 +37,13 @@ export class ParticleNodeDescription extends NodeDescription {
      * - `context.input_types` → port name -> the type each input is read as,
      * - `context.source_types` → port name -> the type of the value wired into each input,
      * - `context.parameters` → the {@link NodeInstance}'s parameters,
-     * - `context.layout` → the {@link ../layout/ParticleLayout.js} for attribute offsets,
-     * - `context.asm` → the {@link ../isa/ParticleAssembler.js} for interning constants.
+     * - `context.layout` → the {@link ../layout/ParticleLayout.js} for particle field offsets,
+     * - `context.emitter_layout` → the layout of the effect's emitter fields, if it has one,
+     * - `context.global_layout` → the global fields the effect declares, if any,
+     * - `context.asm` → the {@link ../isa/ParticleAssembler.js} for interning constants and
+     *   importing global fields.
      *
-     * @type {function(InstructionStream, {in: function(string):number, out: number|undefined, width: number, type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, parameters: object, layout: ParticleLayout, asm: ParticleAssembler}):void}
+     * @type {function(InstructionStream, {in: function(string):number, out: number|undefined, width: number, type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, parameters: object, layout: ParticleLayout, emitter_layout: ParticleLayout|undefined, global_layout: ParticleLayout|undefined, asm: ParticleAssembler}):void}
      */
     emit: (arg0: InstructionStream, arg1: {
         in: (arg0: string) => number;
@@ -55,6 +58,8 @@ export class ParticleNodeDescription extends NodeDescription {
         };
         parameters: object;
         layout: ParticleLayout;
+        emitter_layout: ParticleLayout | undefined;
+        global_layout: ParticleLayout | undefined;
         asm: ParticleAssembler;
     }) => void;
     /**
@@ -71,9 +76,9 @@ export class ParticleNodeDescription extends NodeDescription {
      * is as wide as the widest input, and every input is read at that width. A scalar meeting a
      * vector broadcasts; a vector meeting a wider one is extended with zeros. A source overrides
      * this to name its own type from its parameters; a reduction, to produce a scalar whatever it
-     * reads; a sink, to read what its attribute is.
+     * reads; a sink, to read what its particle field is.
      *
-     * @type {function({inputs: Object<string, ParticleValueType|null>, parameters: object, layout: ParticleLayout|undefined}):{output: ParticleValueType|null, inputs: Object<string, ParticleValueType|null>}}
+     * @type {function({inputs: Object<string, ParticleValueType|null>, parameters: object, layout: ParticleLayout|undefined, emitter_layout: ParticleLayout|undefined, global_layout: ParticleLayout|undefined}):{output: ParticleValueType|null, inputs: Object<string, ParticleValueType|null>}}
      */
     infer_types: (arg0: {
         inputs: {
@@ -81,6 +86,8 @@ export class ParticleNodeDescription extends NodeDescription {
         };
         parameters: object;
         layout: ParticleLayout | undefined;
+        emitter_layout: ParticleLayout | undefined;
+        global_layout: ParticleLayout | undefined;
     }) => {
         output: ParticleValueType | null;
         inputs: {
@@ -94,10 +101,10 @@ export class ParticleNodeDescription extends NodeDescription {
      * Most nodes are element-wise and run at as many lanes as are wanted of them, never more than
      * their type has: lanes nobody reads are not computed. The ones that override this are the
      * ones with a shape of their own — a reduction reads every lane of its input however few are
-     * wanted of its one-lane result, a sink is as wide as the attribute it writes, and a source
-     * that can fill lanes for free runs at the full demand.
+     * wanted of its one-lane result, a sink is as wide as the particle field it writes, and a
+     * source that can fill lanes for free runs at the full demand.
      *
-     * @type {function({type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, demand: number, parameters: object, layout: ParticleLayout}):number}
+     * @type {function({type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, demand: number, parameters: object, layout: ParticleLayout, emitter_layout: ParticleLayout|undefined, global_layout: ParticleLayout|undefined}):number}
      */
     operation_width: (arg0: {
         type: ParticleValueType | null;
@@ -110,6 +117,8 @@ export class ParticleNodeDescription extends NodeDescription {
         demand: number;
         parameters: object;
         layout: ParticleLayout;
+        emitter_layout: ParticleLayout | undefined;
+        global_layout: ParticleLayout | undefined;
     }) => number;
     /**
      * How many lanes the node reads of each input, given the width its own operation runs at.
@@ -119,7 +128,7 @@ export class ParticleNodeDescription extends NodeDescription {
      * the compiler's cue to widen it: a scalar is broadcast, a vector extended with zeros, once,
      * after the value is produced.
      *
-     * @type {function({operation_width: number, type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, parameters: object, layout: ParticleLayout}):Object<string, number>}
+     * @type {function({operation_width: number, type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, parameters: object, layout: ParticleLayout, emitter_layout: ParticleLayout|undefined, global_layout: ParticleLayout|undefined}):Object<string, number>}
      */
     input_widths: (arg0: {
         operation_width: number;
@@ -132,6 +141,8 @@ export class ParticleNodeDescription extends NodeDescription {
         };
         parameters: object;
         layout: ParticleLayout;
+        emitter_layout: ParticleLayout | undefined;
+        global_layout: ParticleLayout | undefined;
     }) => {
         [x: string]: number;
     };
@@ -165,8 +176,8 @@ export class ParticleNodeDescription extends NodeDescription {
     expand: (arg0: object) => import("./ParticleNodeGroup.js").ParticleNodeGroup | null;
     /**
      * A node with no output ports produces no value, so nothing can consume it; the only reason to
-     * emit it is its side effect (an attribute write, a kill). Such nodes are the roots the compiler
-     * traverses from.
+     * emit it is its side effect (a particle field write, a kill). Such nodes are the roots the
+     * compiler traverses from.
      * @returns {boolean}
      */
     get is_sink(): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleNodeDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeDescription.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AACH;IAEI;;;;;;;;;OASG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;;;;;;;;;;OAeG;IACH,sCAFsC;QAAC,EAAE,SAAW,MAAM,KAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAC;QAAC,WAAW;gBAAS,MAAM;UAAqB;QAAC,YAAY;gBAAS,MAAM;UAAqB;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,iBAAiB;QAAC,GAAG,oBAAmB;KAAC,KAAE,IAAI,CAEtS;IAEZ;;;;;;;;;;;;;;;;;OAiBG;IACH,oBAFmB;QAAC,MAAM;gBAAS,MAAM,GAAE,oBAAkB,IAAI;UAAE;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,iBAAe,SAAS,CAAA;KAAC,KAAE;QAAC,MAAM,EAAE,oBAAkB,IAAI,CAAC;QAAC,MAAM;gBAAS,MAAM,GAAE,oBAAkB,IAAI;UAAC;KAAC,CAYzM;IAEF;;;;;;;;;;;OAWG;IACH,wBAFmB;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAC;QAAC,WAAW;gBAAS,MAAM;UAAqB;QAAC,YAAY;gBAAS,MAAM;UAAqB;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,iBAAgB;KAAC,KAAE,MAAM,CAE5I;IAE1E;;;;;;;;;OASG;IACH,qBAFmB;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAC;QAAC,WAAW;gBAAS,MAAM;UAAqB;QAAC,YAAY;gBAAS,MAAM;UAAqB;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,iBAAgB;KAAC;YAAS,MAAM,GAAE,MAAM;MAEpN;IAE1B;;;;;OAKG;IACH,qBAFmB;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAA;KAAC,KAAE,MAAM,CAE1B;IAExD;;;;;;;;;;;;;;;;OAgBG;IACH,eAFmB,MAAM,KAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAEpE;IAEd;;;;;OAKG;IACH,uBAEC;IAGL;;;OAGG;IACH,oCAFU,OAAO,CAE0C;CAN1D;gCAhJ+B,2DAA2D"}
+{"version":3,"file":"ParticleNodeDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeDescription.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AACH;IAEI;;;;;;;;;OASG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;;;;;;;;;;;;;OAkBG;IACH,sCAFsC;QAAC,EAAE,SAAW,MAAM,KAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAC;QAAC,WAAW;gBAAS,MAAM;UAAqB;QAAC,YAAY;gBAAS,MAAM;UAAqB;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,iBAAiB;QAAC,cAAc,EAAE,iBAAe,SAAS,CAAC;QAAC,aAAa,EAAE,iBAAe,SAAS,CAAC;QAAC,GAAG,oBAAmB;KAAC,KAAE,IAAI,CAEzX;IAEZ;;;;;;;;;;;;;;;;;OAiBG;IACH,oBAFmB;QAAC,MAAM;gBAAS,MAAM,GAAE,oBAAkB,IAAI;UAAE;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,iBAAe,SAAS,CAAC;QAAC,cAAc,EAAE,iBAAe,SAAS,CAAC;QAAC,aAAa,EAAE,iBAAe,SAAS,CAAA;KAAC,KAAE;QAAC,MAAM,EAAE,oBAAkB,IAAI,CAAC;QAAC,MAAM;gBAAS,MAAM,GAAE,oBAAkB,IAAI;UAAC;KAAC,CAY5R;IAEF;;;;;;;;;;;OAWG;IACH,wBAFmB;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAC;QAAC,WAAW;gBAAS,MAAM;UAAqB;QAAC,YAAY;gBAAS,MAAM;UAAqB;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,iBAAiB;QAAC,cAAc,EAAE,iBAAe,SAAS,CAAC;QAAC,aAAa,EAAE,iBAAe,SAAS,CAAA;KAAC,KAAE,MAAM,CAE/N;IAE1E;;;;;;;;;OASG;IACH,qBAFmB;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAC;QAAC,WAAW;gBAAS,MAAM;UAAqB;QAAC,YAAY;gBAAS,MAAM;UAAqB;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,iBAAiB;QAAC,cAAc,EAAE,iBAAe,SAAS,CAAC;QAAC,aAAa,EAAE,iBAAe,SAAS,CAAA;KAAC;YAAS,MAAM,GAAE,MAAM;MAEvS;IAE1B;;;;;OAKG;IACH,qBAFmB;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAA;KAAC,KAAE,MAAM,CAE1B;IAExD;;;;;;;;;;;;;;;;OAgBG;IACH,eAFmB,MAAM,KAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAEpE;IAEd;;;;;OAKG;IACH,uBAEC;IAGL;;;OAGG;IACH,oCAFU,OAAO,CAE0C;CAN1D;gCAnJ+B,2DAA2D"}

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

@@ -44,10 +44,13 @@ export class ParticleNodeDescription extends NodeDescription {
      * - `context.input_types` → port name -> the type each input is read as,
      * - `context.source_types` → port name -> the type of the value wired into each input,
      * - `context.parameters` → the {@link NodeInstance}'s parameters,
-     * - `context.layout` → the {@link ../layout/ParticleLayout.js} for attribute offsets,
-     * - `context.asm` → the {@link ../isa/ParticleAssembler.js} for interning constants.
+     * - `context.layout` → the {@link ../layout/ParticleLayout.js} for particle field offsets,
+     * - `context.emitter_layout` → the layout of the effect's emitter fields, if it has one,
+     * - `context.global_layout` → the global fields the effect declares, if any,
+     * - `context.asm` → the {@link ../isa/ParticleAssembler.js} for interning constants and
+     *   importing global fields.
      *
-     * @type {function(InstructionStream, {in: function(string):number, out: number|undefined, width: number, type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, parameters: object, layout: ParticleLayout, asm: ParticleAssembler}):void}
+     * @type {function(InstructionStream, {in: function(string):number, out: number|undefined, width: number, type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, parameters: object, layout: ParticleLayout, emitter_layout: ParticleLayout|undefined, global_layout: ParticleLayout|undefined, asm: ParticleAssembler}):void}
      */
     emit = noop;
 
@@ -65,9 +68,9 @@ export class ParticleNodeDescription extends NodeDescription {
      * is as wide as the widest input, and every input is read at that width. A scalar meeting a
      * vector broadcasts; a vector meeting a wider one is extended with zeros. A source overrides
      * this to name its own type from its parameters; a reduction, to produce a scalar whatever it
-     * reads; a sink, to read what its attribute is.
+     * reads; a sink, to read what its particle field is.
      *
-     * @type {function({inputs: Object<string, ParticleValueType|null>, parameters: object, layout: ParticleLayout|undefined}):{output: ParticleValueType|null, inputs: Object<string, ParticleValueType|null>}}
+     * @type {function({inputs: Object<string, ParticleValueType|null>, parameters: object, layout: ParticleLayout|undefined, emitter_layout: ParticleLayout|undefined, global_layout: ParticleLayout|undefined}):{output: ParticleValueType|null, inputs: Object<string, ParticleValueType|null>}}
      */
     infer_types = ({ inputs }) => {
         const output = particle_widest_type(Object.values(inputs));
@@ -88,10 +91,10 @@ export class ParticleNodeDescription extends NodeDescription {
      * Most nodes are element-wise and run at as many lanes as are wanted of them, never more than
      * their type has: lanes nobody reads are not computed. The ones that override this are the
      * ones with a shape of their own — a reduction reads every lane of its input however few are
-     * wanted of its one-lane result, a sink is as wide as the attribute it writes, and a source
-     * that can fill lanes for free runs at the full demand.
+     * wanted of its one-lane result, a sink is as wide as the particle field it writes, and a
+     * source that can fill lanes for free runs at the full demand.
      *
-     * @type {function({type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, demand: number, parameters: object, layout: ParticleLayout}):number}
+     * @type {function({type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, demand: number, parameters: object, layout: ParticleLayout, emitter_layout: ParticleLayout|undefined, global_layout: ParticleLayout|undefined}):number}
      */
     operation_width = ({ type, demand }) => Math.min(type.components, demand);
 
@@ -103,7 +106,7 @@ export class ParticleNodeDescription extends NodeDescription {
      * the compiler's cue to widen it: a scalar is broadcast, a vector extended with zeros, once,
      * after the value is produced.
      *
-     * @type {function({operation_width: number, type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, parameters: object, layout: ParticleLayout}):Object<string, number>}
+     * @type {function({operation_width: number, type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, parameters: object, layout: ParticleLayout, emitter_layout: ParticleLayout|undefined, global_layout: ParticleLayout|undefined}):Object<string, number>}
      */
     input_widths = () => ({});
 
@@ -136,8 +139,8 @@ export class ParticleNodeDescription extends NodeDescription {
 
     /**
      * A node with no output ports produces no value, so nothing can consume it; the only reason to
-     * emit it is its side effect (an attribute write, a kill). Such nodes are the roots the compiler
-     * traverses from.
+     * emit it is its side effect (a particle field write, a kill). Such nodes are the roots the
+     * compiler traverses from.
      * @returns {boolean}
      */
     get is_sink() {

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

@@ -16,8 +16,8 @@ export function particle_node_descriptions(): ParticleNodeDescription[];
 export function get_particle_node_description(name: string): ParticleNodeDescription;
 /**
  * Standard particle-node library, expressed as {@link ParticleNodeDescription}s in a
- * {@link NodeRegistry}. Nodes are value-producing operations (constants, builtins, attribute reads,
- * math, curves, random) or sinks (attribute writes, kill).
+ * {@link NodeRegistry}. Nodes are value-producing operations (constants, builtins, particle field
+ * reads, math, curves, random) or sinks (particle field writes, kill).
  *
  * These lower to the same opcodes the JS reference + WGSL interpreter agree on, so any effect
  * authored here is executable and testable end-to-end on the CPU before it ever hits the GPU.
@@ -36,8 +36,8 @@ export function get_particle_node_description(name: string): ParticleNodeDescrip
  * A type may also say what a value *means* — {@link PARTICLE_TYPE_COLOR} is four lanes that are a
  * colour — and the rules below never ask. They compare `components` and take the widest, so a
  * colour is accepted wherever a `vec4` is, produces whatever a `vec4` would, and survives the
- * arithmetic in between. The two places a colour enters a graph are the `color` node and an
- * attribute the effect's layout has tagged as one.
+ * arithmetic in between. The two places a colour enters a graph are the `color` node and a field
+ * the effect's layout has tagged as one.
  */
 /**
  * The declared type of every port in the library: a value goes here.

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleNodeRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeRegistry.js"],"names":[],"mappings":"AA2rBA;;;;;;;GAOG;AACH,8CAFa,uBAAuB,EAAE,CAIrC;AAED;;;;;GAKG;AACH,oDAJW,MAAM,GACJ,uBAAuB,CAWnC;AAtrBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;GASG;AACH,kCAFU,QAAQ,CAE2C;AAE7D;;;GAGG;AACH,wCAFU,MAAM,CAE+B;AAE/C;;GAEG;AACH,qCAFU,YAAY,CAEmC;wCAhEjB,8BAA8B;yBAZ7C,oDAAoD;6BAFhD,wDAAwD"}
+{"version":3,"file":"ParticleNodeRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeRegistry.js"],"names":[],"mappings":"AA8tBA;;;;;;;GAOG;AACH,8CAFa,uBAAuB,EAAE,CAIrC;AAED;;;;;GAKG;AACH,oDAJW,MAAM,GACJ,uBAAuB,CAWnC;AAvtBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;GASG;AACH,kCAFU,QAAQ,CAE2C;AAE7D;;;GAGG;AACH,wCAFU,MAAM,CAE+B;AAE/C;;GAEG;AACH,qCAFU,YAAY,CAEmC;wCAhEjB,8BAA8B;yBAd7C,oDAAoD;6BAFhD,wDAAwD"}

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

@@ -6,6 +6,8 @@ import {
     VM_BUILTIN_COMPONENTS,
     VM_OP,
     VM_SWIZZLE_BROADCAST,
+    vm_builtin_emitter_field,
+    vm_builtin_global_field,
     vm_immediate,
     vm_register,
 } from "../isa/ParticleVMISA.js";
@@ -31,8 +33,8 @@ import {
 
 /**
  * Standard particle-node library, expressed as {@link ParticleNodeDescription}s in a
- * {@link NodeRegistry}. Nodes are value-producing operations (constants, builtins, attribute reads,
- * math, curves, random) or sinks (attribute writes, kill).
+ * {@link NodeRegistry}. Nodes are value-producing operations (constants, builtins, particle field
+ * reads, math, curves, random) or sinks (particle field writes, kill).
  *
  * These lower to the same opcodes the JS reference + WGSL interpreter agree on, so any effect
  * authored here is executable and testable end-to-end on the CPU before it ever hits the GPU.
@@ -51,8 +53,8 @@ import {
  * A type may also say what a value *means* — {@link PARTICLE_TYPE_COLOR} is four lanes that are a
  * colour — and the rules below never ask. They compare `components` and take the widest, so a
  * colour is accepted wherever a `vec4` is, produces whatever a `vec4` would, and survives the
- * arithmetic in between. The two places a colour enters a graph are the `color` node and an
- * attribute the effect's layout has tagged as one.
+ * arithmetic in between. The two places a colour enters a graph are the `color` node and a field
+ * the effect's layout has tagged as one.
  */
 
 /**
@@ -301,7 +303,7 @@ const REDUCTION = {
 
 /**
  * An op that has to see the whole vector to compute any lane of it: a `normalize` feeding a
- * one-component attribute still divides by the length of the whole vector rather than by the
+ * one-component particle field still divides by the length of the whole vector rather than by the
  * length of its first lane. Its type is its input's; only the width it runs at differs from the
  * element-wise default.
  */
@@ -368,32 +370,33 @@ function pattern_span(pattern) {
 }
 
 /**
- * The attribute a node names, as a type; `null` where there is no layout to look in or the name is
- * not in it — which the validator reports in its own words.
+ * The field a node names in `layout`, as a type; `null` where there is no layout to look in or the
+ * name is not in it — which the validator reports in its own words. The same rule types particle,
+ * emitter and global fields, each looked up in its own layout.
  *
- * An attribute the layout has tagged (`color`, say) is that type rather than the plain shape, which
- * is how a colour reaches a graph without a node saying so. The tag has to be the shape the
- * attribute actually is: three words tagged `color` is a mistake, and reading them as a four-lane
- * colour would be a second one, so the shape wins and the tag is ignored.
+ * A field the layout has tagged (`color`, say) is that type rather than the plain shape, which is
+ * how a colour reaches a graph without a node saying so. The tag has to be the shape the field
+ * actually is: three words tagged `color` is a mistake, and reading them as a four-lane colour would
+ * be a second one, so the shape wins and the tag is ignored.
  *
  * @param {object} parameters
- * @param {ParticleLayout|undefined} layout
+ * @param {ParticleLayout|undefined} layout the particle, emitter or global layout
  * @returns {ParticleValueType|null}
  */
-function attribute_type(parameters, layout) {
+function particle_field_type(parameters, layout) {
     if (layout === undefined || !layout.has(parameters.name)) {
         return null;
     }
 
-    const attribute = layout.get(parameters.name);
+    const particle_field = layout.get(parameters.name);
 
-    const semantic = particle_semantic_type(attribute.type);
+    const semantic = particle_semantic_type(particle_field.type);
 
-    if (semantic !== null && semantic.components === attribute.components) {
+    if (semantic !== null && semantic.components === particle_field.components) {
         return semantic;
     }
 
-    return particle_value_type(attribute.components);
+    return particle_value_type(particle_field.components);
 }
 
 /**
@@ -416,7 +419,7 @@ function scalar_operand(source_types) {
 
 // --- sources ---
 // A source has a type of its own, and it is as wide as that: a literal is as wide as it was
-// written, a builtin as wide as the host fills it, an attribute as wide as the layout says. A
+// written, a builtin as wide as the host fills it, a particle field as wide as the layout says. A
 // consumer wanting more lanes than that is a conversion the compiler makes after the value is
 // produced — except where a source can fill lanes for free, which it then does.
 source("const", parameters => particle_value_type_or_null(literal_of(parameters).length), emit_literal, {
@@ -427,23 +430,23 @@ source(
     parameters => particle_value_type_or_null(VM_BUILTIN_COMPONENTS[parameters.id]),
     (s, c) => s.loadBuiltin(c.out, c.parameters.id, c.width)
 );
-source("attribute", attribute_type, (s, c) => {
+source("particleField", particle_field_type, (s, c) => {
     const a = c.layout.get(c.parameters.name);
 
-    s.loadAttr(c.out, a.offset, a.components, c.width);
+    s.loadParticleField(c.out, a.offset, a.components, c.width);
 });
 // One uniform draw in `[0, 1)` per lane, as many lanes as the node says. Shaped distributions are
 // compositions over it rather than modes of it — see ./particle_graph_distributions.js.
 source("random", parameters => particle_value_type_or_null(parameters.components), (s, c) => s.random(c.out, c.width));
 
 // --- sinks ---
-// A store is exactly as wide as the attribute it writes, and that is how it reads its input.
-sink("setAttribute", ["value"], (s, c) => {
+// A store is exactly as wide as the particle field it writes, and that is how it reads its input.
+sink("setParticleField", ["value"], (s, c) => {
     const a = c.layout.get(c.parameters.name);
 
-    s.storeAttr(c.in("value"), a.offset, a.components);
+    s.storeParticleField(c.in("value"), a.offset, a.components);
 }, {
-    infer_types: ({ parameters, layout }) => ({ output: null, inputs: { value: attribute_type(parameters, layout) } }),
+    infer_types: ({ parameters, layout }) => ({ output: null, inputs: { value: particle_field_type(parameters, layout) } }),
     operation_width: ({ parameters, layout }) => layout.get(parameters.name).components,
 });
 sink("kill", ["condition"], (s, c) => s.kill(c.in("condition")), {
@@ -697,6 +700,38 @@ define("wind", ["position"], (s, c) => s.emit(VM_OP.SAMPLE_WIND, c.out, c.in("po
     operation_width: () => 3,
 });
 
+// --- emitter fields ---
+// One of the members the effect declares for every emitter, read from the emitter's own block: an
+// emitter field is to the emitter what a particle field is to the particle, and as wide as the
+// emitter layout says. A builtin is the same thing with the engine as the declarer, so it is read
+// through the same instruction.
+define("emitterField", [], (s, c) => {
+    const field = c.emitter_layout.get(c.parameters.name);
+
+    s.loadBuiltin(c.out, vm_builtin_emitter_field(field.offset), c.width);
+}, {
+    infer_types: ({ parameters, emitter_layout }) => ({
+        output: particle_field_type(parameters, emitter_layout),
+        inputs: {},
+    }),
+});
+
+// --- global fields ---
+// One of the system's static members, by name. The effect declares the globals it reads; the
+// program carries them as imports, in the order it first reads them, and is linked to the system's
+// layout when it is placed. So the id here is an import index, not an offset.
+define("globalField", [], (s, c) => {
+    const field = c.global_layout.get(c.parameters.name);
+    const index = c.asm.global_import(field.name, field.components);
+
+    s.loadBuiltin(c.out, vm_builtin_global_field(index), c.width);
+}, {
+    infer_types: ({ parameters, global_layout }) => ({
+        output: particle_field_type(parameters, global_layout),
+        inputs: {},
+    }),
+});
+
 /**
  * Every node type in the library, in declaration order.
  *

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

@@ -1,7 +1,7 @@
 /**
  * The semantic type of this name, or `null` for a name that is not one.
  *
- * How a tag written somewhere else — an attribute in a
+ * How a tag written somewhere else — a particle field in a
  * {@link ../layout/ParticleLayout.js ParticleLayout}, most of all — becomes a type. An unknown name
  * is not an error here: the caller knows the shape regardless, and falling back to it leaves an
  * effect that names a semantic this build has never heard of working as the plain vector it is.
@@ -93,8 +93,8 @@ export function particle_type_conversion(from: ParticleValueType, to: ParticleVa
  * and silently. A vector read narrower keeps its leading lanes; read wider, the missing lanes read
  * zero. Both of those are how the four-lane register file always behaved, so a graph written before
  * types compiles to the same lanes it did — but each is now a warning naming the lanes concerned,
- * because a `vec4` literal feeding a three-component attribute is either a mistake or a literal
- * that ought to be a `vec3`.
+ * because a `vec4` literal feeding a three-component particle field is either a mistake or a
+ * literal that ought to be a `vec3`.
  *
  * Types of the same width never convert, whatever they mean, so nothing is said about a colour
  * meeting a `vec4`. A view still draws the two in their own colours, which is worth seeing — it is