@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -7,9 +7,9 @@
  */
 export const PARTICLE_EMITTER_PAGE_SIZE: number;
 /**
- * How big an emitter database's buffer starts out. The page address table takes 32 KB (two tables'
- * worth of `GPU_DATABASE_PAGE_LIMIT` u32 slots), so this leaves room for one page of each table —
- * around a hundred and forty emitters — before the database grows itself.
+ * How big an emitter database's buffer starts out. The page address table takes 48 KB (three
+ * tables' worth of `GPU_DATABASE_PAGE_LIMIT` u32 slots), so this leaves room for one page of each
+ * table — around a hundred and forty emitters — before the database grows itself.
  *
  * @type {number}
  */
@@ -18,21 +18,26 @@ export const PARTICLE_DATABASE_INITIAL_SIZE: number;
 export const PARTICLE_EMITTER_TABLE: "emitters";
 /** Name of the GPU-owned emitter state table within {@link PARTICLE_DATABASE_SPEC}. */
 export const PARTICLE_EMITTER_STATE_TABLE: "emitter_state";
+/** Name of the transform binding table within {@link PARTICLE_DATABASE_SPEC}. */
+export const PARTICLE_FIELD_BINDING_TABLE: "field_bindings";
 /**
- * Schema of the particle system's GPU database. Two tables, one row per emitter in each, at the
- * same row index:
+ * Schema of the particle system's GPU database. Two tables with one row per emitter in each, at the
+ * same row index, and a third of field-to-transform bindings:
  *
  * - `emitters` — CPU-authored and low-churn, exactly the shape `GPUDatabase` is for. Adding or
  *   removing one emitter queues that one record for upload; the rest of the table is not touched,
  *   and the pass shaders address rows by a stable id that survives its neighbours coming and going.
  * - `emitter_state` — GPU-owned ({@link ./PARTICLE_EMITTER_STATE.js}): claimed with a zero record
  *   when the emitter's row is, then written only by the tick and spawn-command passes.
+ * - `field_bindings` — CPU-authored ({@link ./PARTICLE_FIELD_BINDING.js}): one row per field bound
+ *   to a transform, at rows of its own rather than at an emitter's.
  *
- * One buffer for both is what keeps every pass that reads an emitter at one binding for the pair.
+ * One buffer for all three is what keeps every pass that reads an emitter at one binding for the
+ * record and its state.
  *
- * Programs and their constant pools are NOT here: they are variable-length and shared between
- * emitters, so they live in the packed {@link ../runtime/ProgramArena.js} buffer, referenced by the
- * offsets each emitter record carries.
+ * Programs, their constant pools and the field values are NOT here: programs are variable-length
+ * and shared between emitters, so they live in the packed {@link ../runtime/ProgramHeap.js} buffer
+ * with the field section after them, referenced by the offsets each emitter record carries.
  *
  * @type {GPUDatabaseDefinition}
  */
@@ -52,5 +57,11 @@ export const PARTICLE_EMITTER_DESCRIPTOR: GPUTypedTableDescriptor;
  * @type {GPUTypedTableDescriptor}
  */
 export const PARTICLE_EMITTER_STATE_DESCRIPTOR: GPUTypedTableDescriptor;
+/**
+ * Descriptor for the transform binding table — the bind pass walks its pages, one thread a row.
+ *
+ * @type {GPUTypedTableDescriptor}
+ */
+export const PARTICLE_FIELD_BINDING_DESCRIPTOR: GPUTypedTableDescriptor;
 import { GPUDatabaseDefinition } from "../../buffer/table/GPUDatabaseDefinition.js";
 //# sourceMappingURL=PARTICLE_DATABASE_SPEC.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_DATABASE_SPEC.js"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,yCAFU,MAAM,CAEwC;AAExD;;;;;;GAMG;AACH,6CAFU,MAAM,CAE4C;AAE5D,uEAAuE;AACvE,gDAAiD;AAEjD,uFAAuF;AACvF,2DAA4D;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,qCAFU,qBAAqB,CAKA;AAc/B;;;;;;GAMG;AACH,kEAA8F;AAE9F;;;;;GAKG;AACH,wEAA0G;sCA/EpE,6CAA6C"}
+{"version":3,"file":"PARTICLE_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_DATABASE_SPEC.js"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,yCAFU,MAAM,CAEwC;AAExD;;;;;;GAMG;AACH,6CAFU,MAAM,CAE4C;AAE5D,uEAAuE;AACvE,gDAAiD;AAEjD,uFAAuF;AACvF,2DAA4D;AAE5D,iFAAiF;AACjF,4DAA6D;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qCAFU,qBAAqB,CAMA;AAc/B;;;;;;GAMG;AACH,kEAA8F;AAE9F;;;;;GAKG;AACH,wEAA0G;AAa1G;;;;GAIG;AACH,wEAA0G;sCAzGpE,6CAA6C"}

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

@@ -3,6 +3,7 @@ import { GPUDatabaseDefinition } from "../../buffer/table/GPUDatabaseDefinition.
 import { SCENE_DATABASE_SPEC } from "../../scene/SCENE_DATABASE_SPEC.js";
 import { PARTICLE_EMITTER_STATE_STRUCT } from "./PARTICLE_EMITTER_STATE.js";
 import { PARTICLE_EMITTER_STRUCT } from "./PARTICLE_EMITTER_STRUCT.js";
+import { PARTICLE_FIELD_BINDING_STRUCT } from "./PARTICLE_FIELD_BINDING.js";
 
 /**
  * Emitters are counted in tens, not thousands, so the engine-wide default page (128 KB) would
@@ -14,13 +15,13 @@ import { PARTICLE_EMITTER_STRUCT } from "./PARTICLE_EMITTER_STRUCT.js";
 export const PARTICLE_EMITTER_PAGE_SIZE = 16 * KILOBYTE;
 
 /**
- * How big an emitter database's buffer starts out. The page address table takes 32 KB (two tables'
- * worth of `GPU_DATABASE_PAGE_LIMIT` u32 slots), so this leaves room for one page of each table —
- * around a hundred and forty emitters — before the database grows itself.
+ * How big an emitter database's buffer starts out. The page address table takes 48 KB (three
+ * tables' worth of `GPU_DATABASE_PAGE_LIMIT` u32 slots), so this leaves room for one page of each
+ * table — around a hundred and forty emitters — before the database grows itself.
  *
  * @type {number}
  */
-export const PARTICLE_DATABASE_INITIAL_SIZE = 64 * KILOBYTE;
+export const PARTICLE_DATABASE_INITIAL_SIZE = 96 * KILOBYTE;
 
 /** Name of the emitter table within {@link PARTICLE_DATABASE_SPEC}. */
 export const PARTICLE_EMITTER_TABLE = "emitters";
@@ -28,27 +29,34 @@ export const PARTICLE_EMITTER_TABLE = "emitters";
 /** Name of the GPU-owned emitter state table within {@link PARTICLE_DATABASE_SPEC}. */
 export const PARTICLE_EMITTER_STATE_TABLE = "emitter_state";
 
+/** Name of the transform binding table within {@link PARTICLE_DATABASE_SPEC}. */
+export const PARTICLE_FIELD_BINDING_TABLE = "field_bindings";
+
 /**
- * Schema of the particle system's GPU database. Two tables, one row per emitter in each, at the
- * same row index:
+ * Schema of the particle system's GPU database. Two tables with one row per emitter in each, at the
+ * same row index, and a third of field-to-transform bindings:
  *
  * - `emitters` — CPU-authored and low-churn, exactly the shape `GPUDatabase` is for. Adding or
  *   removing one emitter queues that one record for upload; the rest of the table is not touched,
  *   and the pass shaders address rows by a stable id that survives its neighbours coming and going.
  * - `emitter_state` — GPU-owned ({@link ./PARTICLE_EMITTER_STATE.js}): claimed with a zero record
  *   when the emitter's row is, then written only by the tick and spawn-command passes.
+ * - `field_bindings` — CPU-authored ({@link ./PARTICLE_FIELD_BINDING.js}): one row per field bound
+ *   to a transform, at rows of its own rather than at an emitter's.
  *
- * One buffer for both is what keeps every pass that reads an emitter at one binding for the pair.
+ * One buffer for all three is what keeps every pass that reads an emitter at one binding for the
+ * record and its state.
  *
- * Programs and their constant pools are NOT here: they are variable-length and shared between
- * emitters, so they live in the packed {@link ../runtime/ProgramArena.js} buffer, referenced by the
- * offsets each emitter record carries.
+ * Programs, their constant pools and the field values are NOT here: programs are variable-length
+ * and shared between emitters, so they live in the packed {@link ../runtime/ProgramHeap.js} buffer
+ * with the field section after them, referenced by the offsets each emitter record carries.
  *
  * @type {GPUDatabaseDefinition}
  */
 export const PARTICLE_DATABASE_SPEC = GPUDatabaseDefinition.from({
     [PARTICLE_EMITTER_TABLE]: PARTICLE_EMITTER_STRUCT,
     [PARTICLE_EMITTER_STATE_TABLE]: PARTICLE_EMITTER_STATE_STRUCT,
+    [PARTICLE_FIELD_BINDING_TABLE]: PARTICLE_FIELD_BINDING_STRUCT,
 }, PARTICLE_EMITTER_PAGE_SIZE);
 
 // The transforms row of the emitter's entity, where the passes read its world matrix. Until the
@@ -79,3 +87,21 @@ export const PARTICLE_EMITTER_DESCRIPTOR = PARTICLE_DATABASE_SPEC.get(PARTICLE_E
  * @type {GPUTypedTableDescriptor}
  */
 export const PARTICLE_EMITTER_STATE_DESCRIPTOR = PARTICLE_DATABASE_SPEC.get(PARTICLE_EMITTER_STATE_TABLE);
+
+// The row a binding reads, as for the emitter record's `node`: held through the scene's rows by
+// whoever bound it, never by this database.
+PARTICLE_DATABASE_SPEC.add_link({
+    table: PARTICLE_FIELD_BINDING_TABLE,
+    field: 'source',
+    target_database: SCENE_DATABASE_SPEC,
+    target_table: 'transforms',
+    nullable: false,
+    owning: false,
+});
+
+/**
+ * Descriptor for the transform binding table — the bind pass walks its pages, one thread a row.
+ *
+ * @type {GPUTypedTableDescriptor}
+ */
+export const PARTICLE_FIELD_BINDING_DESCRIPTOR = PARTICLE_DATABASE_SPEC.get(PARTICLE_FIELD_BINDING_TABLE);

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

@@ -21,9 +21,10 @@ export function emitter_flags_blend(flags: number): number;
 export function emitter_flags_projection(flags: number): number;
 /**
  * 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
@@ -38,8 +39,8 @@ export function emitter_flags_projection(flags: number): number;
  * 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.
@@ -47,8 +48,8 @@ export function emitter_flags_projection(flags: number): number;
  * @type {WebGPUStruct}
  */
 export const PARTICLE_EMITTER_STRUCT: WebGPUStruct;
-/** Sentinel for an absent render-attribute binding. */
-export const EMITTER_ATTRIBUTE_ABSENT: 4294967295;
+/** Sentinel for a render channel bound to no particle field. */
+export const PARTICLE_FIELD_ABSENT: 4294967295;
 /**
  * Emitter flag bits. Blend mode occupies bits [4,6), projection mode bits [6,9).
  *

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

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_EMITTER_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js"],"names":[],"mappings":"AA2IA;;;;;;;;;GASG;AACH;IAP6B,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;IACW,IAAI,GAAtB,OAAO;IACU,KAAK,GAAtB,MAAM;IACW,UAAU,GAA3B,MAAM;IACJ,MAAM,CAUlB;AAED,6DAA6D;AAC7D,2CADY,MAAM,GAAkB,MAAM,CAGzC;AAED,kEAAkE;AAClE,gDADY,MAAM,GAAkB,MAAM,CAGzC;AApKD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sCAFU,YAAY,CAmEO;AAE7B,uDAAuD;AACvD,kDAAmD;AAEnD;;;;;;GAMG;AACH;;;;GAIG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH;;;;GAIG;AACH;;;;;;GAMG;AAmCH,uEAAuE;AACvE;;;;;GAEG;6BA3K0B,mCAAmC"}
+{"version":3,"file":"PARTICLE_EMITTER_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js"],"names":[],"mappings":"AAoJA;;;;;;;;;GASG;AACH;IAP6B,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;IACW,IAAI,GAAtB,OAAO;IACU,KAAK,GAAtB,MAAM;IACW,UAAU,GAA3B,MAAM;IACJ,MAAM,CAUlB;AAED,6DAA6D;AAC7D,2CADY,MAAM,GAAkB,MAAM,CAGzC;AAED,kEAAkE;AAClE,gDADY,MAAM,GAAkB,MAAM,CAGzC;AA7KD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,sCAFU,YAAY,CA2EO;AAE7B,gEAAgE;AAChE,+CAAgD;AAEhD;;;;;;GAMG;AACH;;;;GAIG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH;;;;GAIG;AACH;;;;;;GAMG;AAmCH,uEAAuE;AACvE;;;;;GAEG;6BApL0B,mCAAmC"}

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() {