@woosh/meep-engine 3.58.0 → 3.59.0

package/src/shade/renderer/particles/runtime/ParticleEmitter.d.ts

@@ -1,5 +1,5 @@
 /**
- * Render channels an emitter can bind to one of its effect's per-particle attributes. The names
+ * Render channels an emitter can bind to one of its effect's particle fields. The names
  * match the `render_*` fields of {@link ../data/PARTICLE_EMITTER_STRUCT.js}.
  *
  * @type {string[]}
@@ -9,9 +9,9 @@ export const EMITTER_RENDER_CHANNELS: string[];
  * How many record words the render pass reads for each channel.
  *
  * A channel is read at a fixed width — `chunk_particle_billboard_vertex.js` takes four words for
- * colour and three for position, whatever the attribute behind the offset happens to be. Binding one
- * to a narrower attribute is therefore not a smaller read but a read into whatever the layout put
- * next, and nothing downstream objects: the particles simply come out wrong.
+ * colour and three for position, whatever the particle field behind the offset happens to be.
+ * Binding one to a narrower particle field is therefore not a smaller read but a read into whatever
+ * the layout put next, and nothing downstream objects: the particles simply come out wrong.
  *
  * Binding is deliberately not made to enforce this — the offsets are the record's, and an author who
  * knows what is packed where may mean it — but an editor has this table so it can say so.
@@ -38,10 +38,12 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS: {
  * row in the emitter table is retired, and its particles with it within a frame, because they
  * carry that row's generation. There is no transform of its own to keep in step with anything.
  *
- * The rest is a description of an effect and nothing else: the attribute {@link layout} and the
- * compiled {@link program}, the {@link texture} to draw with, spawn rate, pre-warm duration, blend /
- * projection / feature flags, render-attribute bindings and flipbook grid. Every one of those is the author's,
- * means the same thing with no device present, and is what a saved effect is made of.
+ * The rest is a description of an effect and nothing else: the particle field {@link layout} and
+ * the compiled {@link program}, the {@link emitter_layout} and this emitter's
+ * {@link emitter_fields} values, the {@link texture} to draw with, spawn rate, pre-warm duration,
+ * blend / projection / feature flags, render-channel bindings and flipbook grid. Every one of those
+ * is the author's, means the same thing with no device present, and is what a saved effect is made
+ * of.
  *
  * There are no bounds among them, and there is nowhere here they could go. An emitter's particles
  * are simulated in world space by arbitrary bytecode: they go where the program sends them, at
@@ -53,8 +55,9 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS: {
  * emitter opts into culling at all: `EMITTER_FLAG.CULL` in {@link flags}.
  *
  * **Nothing here is the GPU's.** Which table row the emitter was given, which tenancy of it, where
- * its program was placed in the program heap, which `transforms` row it was registered at, where
- * its texture was packed into the atlas — all of that is
+ * its program and its emitter fields were placed in the program heap, which transforms are bound to
+ * those fields, which `transforms` row it was registered at, where its texture was packed into the
+ * atlas — all of that is
  * {@link ./GPUParticleEmitterContext.js GPUParticleEmitterContext}, held by the
  * {@link ./EmitterRegistry.js} that registered the emitter and reachable through
  * {@link ./EmitterRegistry.js#context}. An emitter no registry holds has none, which is also how
@@ -71,21 +74,27 @@ export class ParticleEmitter {
      * Build an emitter from a plain description. Every parameter is optional except the compiled
      * effect — an emitter with no program has nothing to run.
      *
-     * `layout` and `program` are the two halves of what {@link ./create_particle_effect.js} returns,
-     * so an effect goes in by spreading it: `ParticleEmitter.from({ ...effect, spawn_rate: 100 })`.
+     * `layout`, `program`, `emitter_layout` and `emitter_fields` are what
+     * {@link ./create_particle_effect.js} returns, so an effect goes in by spreading it:
+     * `ParticleEmitter.from({ ...effect, spawn_rate: 100 })`.
      *
      * @param {object} config
-     * @param {import("../layout/ParticleLayout.js").ParticleLayout} config.layout per-particle
-     *        attribute schema
+     * @param {import("../layout/ParticleLayout.js").ParticleLayout} config.layout particle field
+     *        schema
      * @param {import("../isa/ParticleProgram.js").ParticleProgram} config.program compiled INIT /
      *        UPDATE bytecode
-     * @param {ArrayLike<number>} [config.position] local translation, `[x, y, z]`
+     * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [config.emitter_layout] the
+     *        emitter field schema the program was compiled against
+     * @param {ArrayLike<number>} [config.emitter_fields] this emitter's values for them, as f32 bit
+     *        patterns laid out by `emitter_layout`
+     * @param {undefined} [config.position] must be absent: an emitter is placed by the `transforms`
+     *        row it is registered at, so place its entity instead
      * @param {string|null} [config.texture] image URL to draw with
      * @param {number} [config.seed]
      * @param {number} [config.spawn_rate] particles/second
      * @param {number} [config.prewarm] seconds of emission to run forward before the first frame
      * @param {object} [config.flags] passed to {@link make_emitter_flags}
-     * @param {Object<string,string>} [config.render] render channel -> attribute name
+     * @param {Object<string,string>} [config.render] render channel -> particle field name
      * @param {ArrayLike<number>} [config.flipbook] [cols, rows]
      * @param {string} [config.name]
      * @returns {ParticleEmitter}
@@ -93,7 +102,9 @@ export class ParticleEmitter {
     static from(config: {
         layout: import("../layout/ParticleLayout.js").ParticleLayout;
         program: import("../isa/ParticleProgram.js").ParticleProgram;
-        position?: ArrayLike<number>;
+        emitter_layout?: import("../layout/ParticleLayout.js").ParticleLayout | null;
+        emitter_fields?: ArrayLike<number>;
+        position?: undefined;
         texture?: string | null;
         seed?: number;
         spawn_rate?: number;
@@ -122,12 +133,30 @@ export class ParticleEmitter {
      */
     set needsUpdate(value: boolean);
     /**
-     * The per-particle attribute schema: which named attributes a particle of this emitter has, how
-     * wide each is, and what word of the record it sits at.
+     * The particle field schema: which named particle fields a particle of this emitter has,
+     * how wide each is, and what word of the record it sits at.
      *
      * @type {import("../layout/ParticleLayout.js").ParticleLayout}
      */
     layout: import("../layout/ParticleLayout.js").ParticleLayout;
+    /**
+     * The emitter field schema the effect declares: which named fields each of its emitters
+     * carries, laid out from word zero ({@link ../layout/ParticleLayout.js ParticleLayout.emitter}).
+     * `null` for an effect that declares none. Part of the effect, like {@link layout} — the program
+     * is compiled against it.
+     *
+     * @type {import("../layout/ParticleLayout.js").ParticleLayout|null}
+     */
+    emitter_layout: import("../layout/ParticleLayout.js").ParticleLayout | null;
+    /**
+     * This emitter's values for its emitter fields, as f32 bit patterns laid out by
+     * {@link emitter_layout}. The instance's own data: two emitters of one effect share the program
+     * and differ here, and a registry gives each of them a block of its own. Words the array is
+     * too short to give read zero.
+     *
+     * @type {Uint32Array}
+     */
+    emitter_fields: Uint32Array;
     /**
      * The compiled INIT/UPDATE bytecode run for every particle of this emitter.
      * Replace the immutable program to edit it; do not mutate its bytecode in place.
@@ -196,7 +225,7 @@ export class ParticleEmitter {
      * @type {Float32Array}
      */
     flipbook: Float32Array;
-    /** @type {number} record word offset of world position, or {@link EMITTER_ATTRIBUTE_ABSENT} */
+    /** @type {number} record word offset of world position, or {@link PARTICLE_FIELD_ABSENT} */
     render_position: number;
     /** @type {number} record word offset of size */
     render_size: number;
@@ -210,17 +239,17 @@ export class ParticleEmitter {
     render_velocity: number;
     get type(): string;
     /**
-     * Bind render channels to per-particle attributes of this emitter's effect, by attribute name.
+     * Bind render channels to particle fields of this emitter's effect, by particle field name.
      * Channels left out of `channels` keep whatever they had; a channel that was never bound stays
-     * at {@link EMITTER_ATTRIBUTE_ABSENT}, which the passes read as "this emitter has no such
-     * attribute" — the passes that draw substitute a default, and the bounds pass treats the
+     * at {@link PARTICLE_FIELD_ABSENT}, which the passes read as "this emitter has no such
+     * particle field" — the passes that draw substitute a default, and the bounds pass treats the
      * particle as being at the origin.
      *
      * The record stores word offsets rather than names because that is what those passes index a
      * particle record with; resolving here is the only place a name is involved.
      *
      * @param {Object<string,string>} channels channel name (see {@link EMITTER_RENDER_CHANNELS}) ->
-     *        attribute name in the effect's layout
+     *        particle field name in the effect's layout
      */
     bind_render(channels: {
         [x: string]: string;
@@ -248,9 +277,10 @@ export class ParticleEmitter {
     /**
      * Make this emitter a copy of `other`: same effect, same settings.
      *
-     * The layout and the compiled program are shared rather than duplicated — both are immutable
+     * The layouts and the compiled program are shared rather than duplicated — all are immutable
      * once compiled, and sharing them is what puts two emitters of one effect on one program id in
-     * the program heap, hence in one simulation bucket.
+     * the program heap, hence in one simulation bucket. The emitter field values are copied: they
+     * are this instance's.
      *
      * What is not copied is anything a registry gave the original: a copy is a second emitter, not
      * a second reference to the first one's table row.

package/src/shade/renderer/particles/runtime/ParticleEmitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ParticleEmitter.js"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,sCAFU,MAAM,EAAE,CAIf;AAEH;;;;;;;;;;;;GAYG;AACH;QAFiB,MAAM,GAAE,MAAM;EAS5B;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH;IAiSI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH;QAfwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;QAEQ,OAAO,EAAnE,OAAO,2BAA2B,EAAE,eAAe;QAExB,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACI,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACU,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACD,IAAI,GAApB,MAAM;QACJ,eAAe,CA+C3B;IApWD;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAUV;;OAEG;IACH,sBAEC;IAED;;;;OAIG;IACH,gCAIC;IAED;;;;;OAKG;IACH,QAFU,OAAO,6BAA6B,EAAE,cAAc,CAEvD;IAEP;;;;;OAKG;IACH,SAFU,OAAO,2BAA2B,EAAE,eAAe,CAErD;IAER;;;;;;;;;;;OAWG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,UAFU,YAAY,CAEc;IAEpC,+FAA+F;IAC/F,iBADW,MAAM,CAC0B;IAC3C,gDAAgD;IAChD,aADW,MAAM,CACsB;IACvC,uDAAuD;IACvD,cADW,MAAM,CACuB;IACxC,4IAA4I;IAC5I,oBADW,MAAM,CAC6B;IAC9C,gEAAgE;IAChE,cADW,MAAM,CACuB;IACxC,sFAAsF;IACtF,iBADW,MAAM,CAC0B;IAE3C,mBAEC;IAED;;;;;;;;;;;;OAYG;IACH;YAHkB,MAAM,GAAC,MAAM;aA2B9B;IAED;;;;;;;;;;OAUG;IACH,cAHW,eAAe,GACb,OAAO,CAsBnB;IAED;;;;;;OAMG;IACH,QAFa,MAAM,CAsBlB;IAED;;;;;;;;;;;OAWG;IACH,YAFW,eAAe,QA6BzB;IAED;;;;OAIG;IACH,SAFa,eAAe,CAQ3B;IAyEL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C"}
+{"version":3,"file":"ParticleEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ParticleEmitter.js"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,sCAFU,MAAM,EAAE,CAIf;AAEH;;;;;;;;;;;;GAYG;AACH;QAFiB,MAAM,GAAE,MAAM;EAS5B;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IAuUI;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH;QApBwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;QAEQ,OAAO,EAAnE,OAAO,2BAA2B,EAAE,eAAe;QAEgB,cAAc,GAAjF,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI;QAE9B,cAAc,GAAzC,UAAU,MAAM,CAAC;QAEE,QAAQ,GAA3B,SAAS;QAEY,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACU,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACD,IAAI,GAApB,MAAM;QACJ,eAAe,CAuD3B;IAxZD;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAUV;;OAEG;IACH,sBAEC;IAED;;;;OAIG;IACH,gCAIC;IAED;;;;;OAKG;IACH,QAFU,OAAO,6BAA6B,EAAE,cAAc,CAEvD;IAEP;;;;;;;OAOG;IACH,gBAFU,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI,CAE7C;IAEtB;;;;;;;OAOG;IACH,gBAFU,WAAW,CAEe;IAEpC;;;;;OAKG;IACH,SAFU,OAAO,2BAA2B,EAAE,eAAe,CAErD;IAER;;;;;;;;;;;OAWG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,UAFU,YAAY,CAEc;IAEpC,4FAA4F;IAC5F,iBADW,MAAM,CACuB;IACxC,gDAAgD;IAChD,aADW,MAAM,CACmB;IACpC,uDAAuD;IACvD,cADW,MAAM,CACoB;IACrC,4IAA4I;IAC5I,oBADW,MAAM,CAC0B;IAC3C,gEAAgE;IAChE,cADW,MAAM,CACoB;IACrC,sFAAsF;IACtF,iBADW,MAAM,CACuB;IAExC,mBAEC;IAED;;;;;;;;;;;;OAYG;IACH;YAHkB,MAAM,GAAC,MAAM;aA2B9B;IAED;;;;;;;;;;OAUG;IACH,cAHW,eAAe,GACb,OAAO,CA0BnB;IAED;;;;;;OAMG;IACH,QAFa,MAAM,CA2BlB;IAED;;;;;;;;;;;;OAYG;IACH,YAFW,eAAe,QAqCzB;IAED;;;;OAIG;IACH,SAFa,eAAe,CAQ3B;IAuFL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C"}

package/src/shade/renderer/particles/runtime/ParticleEmitter.js

@@ -1,14 +1,15 @@
 import { assert } from "../../../../core/assert.js";
 import { is_typed_array_equals } from "../../../../core/collection/array/typed/is_typed_array_equals.js";
 import { float32_array_hash } from "../../../../core/collection/array/typed/float32_array_hash.js";
+import { uint32_array_hash } from "../../../../core/collection/array/typed/uint32_array_hash.js";
 import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
 import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
 import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
-import { EMITTER_ATTRIBUTE_ABSENT, make_emitter_flags } from "../data/PARTICLE_EMITTER_STRUCT.js";
+import { PARTICLE_FIELD_ABSENT, make_emitter_flags } from "../data/PARTICLE_EMITTER_STRUCT.js";
 
 /**
- * Render channels an emitter can bind to one of its effect's per-particle attributes. The names
+ * Render channels an emitter can bind to one of its effect's particle fields. The names
  * match the `render_*` fields of {@link ../data/PARTICLE_EMITTER_STRUCT.js}.
  *
  * @type {string[]}
@@ -21,9 +22,9 @@ export const EMITTER_RENDER_CHANNELS = Object.freeze([
  * How many record words the render pass reads for each channel.
  *
  * A channel is read at a fixed width — `chunk_particle_billboard_vertex.js` takes four words for
- * colour and three for position, whatever the attribute behind the offset happens to be. Binding one
- * to a narrower attribute is therefore not a smaller read but a read into whatever the layout put
- * next, and nothing downstream objects: the particles simply come out wrong.
+ * colour and three for position, whatever the particle field behind the offset happens to be.
+ * Binding one to a narrower particle field is therefore not a smaller read but a read into whatever
+ * the layout put next, and nothing downstream objects: the particles simply come out wrong.
  *
  * Binding is deliberately not made to enforce this — the offsets are the record's, and an author who
  * knows what is packed where may mean it — but an editor has this table so it can say so.
@@ -56,10 +57,12 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS = Object.freeze({
  * row in the emitter table is retired, and its particles with it within a frame, because they
  * carry that row's generation. There is no transform of its own to keep in step with anything.
  *
- * The rest is a description of an effect and nothing else: the attribute {@link layout} and the
- * compiled {@link program}, the {@link texture} to draw with, spawn rate, pre-warm duration, blend /
- * projection / feature flags, render-attribute bindings and flipbook grid. Every one of those is the author's,
- * means the same thing with no device present, and is what a saved effect is made of.
+ * The rest is a description of an effect and nothing else: the particle field {@link layout} and
+ * the compiled {@link program}, the {@link emitter_layout} and this emitter's
+ * {@link emitter_fields} values, the {@link texture} to draw with, spawn rate, pre-warm duration,
+ * blend / projection / feature flags, render-channel bindings and flipbook grid. Every one of those
+ * is the author's, means the same thing with no device present, and is what a saved effect is made
+ * of.
  *
  * There are no bounds among them, and there is nowhere here they could go. An emitter's particles
  * are simulated in world space by arbitrary bytecode: they go where the program sends them, at
@@ -71,8 +74,9 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS = Object.freeze({
  * emitter opts into culling at all: `EMITTER_FLAG.CULL` in {@link flags}.
  *
  * **Nothing here is the GPU's.** Which table row the emitter was given, which tenancy of it, where
- * its program was placed in the program heap, which `transforms` row it was registered at, where
- * its texture was packed into the atlas — all of that is
+ * its program and its emitter fields were placed in the program heap, which transforms are bound to
+ * those fields, which `transforms` row it was registered at, where its texture was packed into the
+ * atlas — all of that is
  * {@link ./GPUParticleEmitterContext.js GPUParticleEmitterContext}, held by the
  * {@link ./EmitterRegistry.js} that registered the emitter and reachable through
  * {@link ./EmitterRegistry.js#context}. An emitter no registry holds has none, which is also how
@@ -119,13 +123,33 @@ export class ParticleEmitter {
     }
 
     /**
-     * The per-particle attribute schema: which named attributes a particle of this emitter has, how
-     * wide each is, and what word of the record it sits at.
+     * The particle field schema: which named particle fields a particle of this emitter has,
+     * how wide each is, and what word of the record it sits at.
      *
      * @type {import("../layout/ParticleLayout.js").ParticleLayout}
      */
     layout;
 
+    /**
+     * The emitter field schema the effect declares: which named fields each of its emitters
+     * carries, laid out from word zero ({@link ../layout/ParticleLayout.js ParticleLayout.emitter}).
+     * `null` for an effect that declares none. Part of the effect, like {@link layout} — the program
+     * is compiled against it.
+     *
+     * @type {import("../layout/ParticleLayout.js").ParticleLayout|null}
+     */
+    emitter_layout = null;
+
+    /**
+     * This emitter's values for its emitter fields, as f32 bit patterns laid out by
+     * {@link emitter_layout}. The instance's own data: two emitters of one effect share the program
+     * and differ here, and a registry gives each of them a block of its own. Words the array is
+     * too short to give read zero.
+     *
+     * @type {Uint32Array}
+     */
+    emitter_fields = new Uint32Array(0);
+
     /**
      * The compiled INIT/UPDATE bytecode run for every particle of this emitter.
      * Replace the immutable program to edit it; do not mutate its bytecode in place.
@@ -201,35 +225,35 @@ export class ParticleEmitter {
      */
     flipbook = new Float32Array([1, 1]);
 
-    /** @type {number} record word offset of world position, or {@link EMITTER_ATTRIBUTE_ABSENT} */
-    render_position = EMITTER_ATTRIBUTE_ABSENT;
+    /** @type {number} record word offset of world position, or {@link PARTICLE_FIELD_ABSENT} */
+    render_position = PARTICLE_FIELD_ABSENT;
     /** @type {number} record word offset of size */
-    render_size = EMITTER_ATTRIBUTE_ABSENT;
+    render_size = PARTICLE_FIELD_ABSENT;
     /** @type {number} record word offset of rgba colour */
-    render_color = EMITTER_ATTRIBUTE_ABSENT;
+    render_color = PARTICLE_FIELD_ABSENT;
     /** @type {number} record word offset of the orientation, a quaternion (x, y, z, w) turning the sprite inside its projection mode's frame */
-    render_orientation = EMITTER_ATTRIBUTE_ABSENT;
+    render_orientation = PARTICLE_FIELD_ABSENT;
     /** @type {number} record word offset of flipbook frame index */
-    render_frame = EMITTER_ATTRIBUTE_ABSENT;
+    render_frame = PARTICLE_FIELD_ABSENT;
     /** @type {number} record word offset of velocity, read by the STRETCHED projection */
-    render_velocity = EMITTER_ATTRIBUTE_ABSENT;
+    render_velocity = PARTICLE_FIELD_ABSENT;
 
     get type() {
         return "ParticleEmitter";
     }
 
     /**
-     * Bind render channels to per-particle attributes of this emitter's effect, by attribute name.
+     * Bind render channels to particle fields of this emitter's effect, by particle field name.
      * Channels left out of `channels` keep whatever they had; a channel that was never bound stays
-     * at {@link EMITTER_ATTRIBUTE_ABSENT}, which the passes read as "this emitter has no such
-     * attribute" — the passes that draw substitute a default, and the bounds pass treats the
+     * at {@link PARTICLE_FIELD_ABSENT}, which the passes read as "this emitter has no such
+     * particle field" — the passes that draw substitute a default, and the bounds pass treats the
      * particle as being at the origin.
      *
      * The record stores word offsets rather than names because that is what those passes index a
      * particle record with; resolving here is the only place a name is involved.
      *
      * @param {Object<string,string>} channels channel name (see {@link EMITTER_RENDER_CHANNELS}) ->
-     *        attribute name in the effect's layout
+     *        particle field name in the effect's layout
      */
     bind_render(channels) {
         assert.isObject(channels, 'channels');
@@ -286,6 +310,10 @@ export class ParticleEmitter {
             && this.render_frame === other.render_frame
             && this.render_velocity === other.render_velocity
             && is_typed_array_equals(this.flipbook, other.flipbook)
+            && is_typed_array_equals(this.emitter_fields, other.emitter_fields)
+            && (this.emitter_layout === other.emitter_layout
+                || (this.emitter_layout !== null && other.emitter_layout !== null
+                    && this.emitter_layout.equals(other.emitter_layout)))
             && this.layout.equals(other.layout)
             && this.program.equals(other.program);
     }
@@ -312,8 +340,13 @@ export class ParticleEmitter {
             hash_mix3(this.seed, computeHashFloat(this.spawn_rate), computeHashFloat(this.prewarm))
         );
 
+        const fields = hash_mix2(
+            this.emitter_layout === null ? 0 : this.emitter_layout.hash(),
+            uint32_array_hash(this.emitter_fields, 0, this.emitter_fields.length)
+        );
+
         return hash_mix3(
-            hash_mix2(bindings, flipbook),
+            hash_mix3(bindings, flipbook, fields),
             appearance,
             hash_mix2(this.layout.hash(), this.program.hash())
         );
@@ -322,9 +355,10 @@ export class ParticleEmitter {
     /**
      * Make this emitter a copy of `other`: same effect, same settings.
      *
-     * The layout and the compiled program are shared rather than duplicated — both are immutable
+     * The layouts and the compiled program are shared rather than duplicated — all are immutable
      * once compiled, and sharing them is what puts two emitters of one effect on one program id in
-     * the program heap, hence in one simulation bucket.
+     * the program heap, hence in one simulation bucket. The emitter field values are copied: they
+     * are this instance's.
      *
      * What is not copied is anything a registry gave the original: a copy is a second emitter, not
      * a second reference to the first one's table row.
@@ -352,6 +386,14 @@ export class ParticleEmitter {
         this.render_frame = other.render_frame;
         this.render_velocity = other.render_velocity;
 
+        this.emitter_layout = other.emitter_layout;
+
+        if (this.emitter_fields.length !== other.emitter_fields.length) {
+            this.emitter_fields = new Uint32Array(other.emitter_fields.length);
+        }
+
+        this.emitter_fields.set(other.emitter_fields);
+
         // That is every field `write_emitter_record` stages, so the row this emitter may already
         // own is now wrong. The registry restages only what `is_stale` reports, and two emitters of
         // one effect share the compiled program object — so the `set_program` escape hatch does not
@@ -377,21 +419,27 @@ export class ParticleEmitter {
      * Build an emitter from a plain description. Every parameter is optional except the compiled
      * effect — an emitter with no program has nothing to run.
      *
-     * `layout` and `program` are the two halves of what {@link ./create_particle_effect.js} returns,
-     * so an effect goes in by spreading it: `ParticleEmitter.from({ ...effect, spawn_rate: 100 })`.
+     * `layout`, `program`, `emitter_layout` and `emitter_fields` are what
+     * {@link ./create_particle_effect.js} returns, so an effect goes in by spreading it:
+     * `ParticleEmitter.from({ ...effect, spawn_rate: 100 })`.
      *
      * @param {object} config
-     * @param {import("../layout/ParticleLayout.js").ParticleLayout} config.layout per-particle
-     *        attribute schema
+     * @param {import("../layout/ParticleLayout.js").ParticleLayout} config.layout particle field
+     *        schema
      * @param {import("../isa/ParticleProgram.js").ParticleProgram} config.program compiled INIT /
      *        UPDATE bytecode
-     * @param {ArrayLike<number>} [config.position] local translation, `[x, y, z]`
+     * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [config.emitter_layout] the
+     *        emitter field schema the program was compiled against
+     * @param {ArrayLike<number>} [config.emitter_fields] this emitter's values for them, as f32 bit
+     *        patterns laid out by `emitter_layout`
+     * @param {undefined} [config.position] must be absent: an emitter is placed by the `transforms`
+     *        row it is registered at, so place its entity instead
      * @param {string|null} [config.texture] image URL to draw with
      * @param {number} [config.seed]
      * @param {number} [config.spawn_rate] particles/second
      * @param {number} [config.prewarm] seconds of emission to run forward before the first frame
      * @param {object} [config.flags] passed to {@link make_emitter_flags}
-     * @param {Object<string,string>} [config.render] render channel -> attribute name
+     * @param {Object<string,string>} [config.render] render channel -> particle field name
      * @param {ArrayLike<number>} [config.flipbook] [cols, rows]
      * @param {string} [config.name]
      * @returns {ParticleEmitter}
@@ -406,6 +454,14 @@ export class ParticleEmitter {
         emitter.layout = config.layout;
         emitter.program = config.program;
 
+        if (config.emitter_layout !== undefined) {
+            emitter.emitter_layout = config.emitter_layout;
+        }
+
+        if (config.emitter_fields !== undefined) {
+            emitter.emitter_fields = Uint32Array.from(config.emitter_fields);
+        }
+
         if (config.name !== undefined) {
             emitter.name = config.name;
         }

package/src/shade/renderer/particles/runtime/ParticleGlobalFields.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The system's global fields: the static members every effect may read, by name.
+ *
+ * The layout is the union of what is loaded. A program names the globals it imports, and placing it
+ * declares any name the system does not have yet, zero-filled; game code may declare names up front
+ * and set their values whenever it likes. The layout is append-only — a field once declared keeps
+ * its offset — so linking a program never has to be redone because another one was placed.
+ *
+ * The words live at the top of the program heap's field section (see {@link ./ProgramHeap.js}), in
+ * the {@link PARTICLE_GLOBAL_FIELD_WORDS} reserved there, so a global field is addressed from zero.
+ * A global field nobody has set reads 0: missing data is zero, never a stand-in.
+ */
+export class ParticleGlobalFields {
+    /**
+     * @param {function(number, number):void} write_word `(index, bits)`: writes word `index` of the
+     *   global region and marks it for upload
+     */
+    constructor(write_word: (arg0: number, arg1: number) => void);
+    /**
+     * Words the declared fields take.
+     * @returns {number}
+     */
+    get word_count(): number;
+    /**
+     * @param {string} name
+     * @returns {boolean}
+     */
+    has(name: string): boolean;
+    /**
+     * @param {string} name
+     * @returns {{name: string, offset: number, components: number}|undefined}
+     */
+    get(name: string): {
+        name: string;
+        offset: number;
+        components: number;
+    } | undefined;
+    /**
+     * Whether a program importing these could be placed: every name either declared at least that
+     * wide, or new and fitting in what is left of the reservation — all of them together, as placing
+     * the program would declare them. Changes nothing, so a program that cannot be placed is
+     * refused before anything is claimed for it.
+     *
+     * @param {ReadonlyArray<{name: string, components: number}>} imports
+     * @throws exactly what {@link declare} would throw for the first import that cannot be declared
+     */
+    check(imports: ReadonlyArray<{
+        name: string;
+        components: number;
+    }>): void;
+    /**
+     * Declare a global field, or find the one already declared under that name.
+     *
+     * A name is one field however many programs import it, so a second declaration must not want
+     * more of it than the first gave it: reading three words of a one-word field would read the next
+     * field's words, which is somebody else's data and never the right answer.
+     *
+     * @param {string} name
+     * @param {number} components 1..4
+     * @returns {number} the field's word offset
+     * @throws if `components` is not 1..4, the name is declared narrower, or the reserved words are
+     *   spent
+     */
+    declare(name: string, components: number): number;
+    /**
+     * Set a global field's value, declaring it at that width if nothing has yet. Fewer values than
+     * the field has components set the leading ones.
+     *
+     * @param {string} name
+     * @param {ArrayLike<number>} values one per component
+     * @throws what {@link ParticleGlobalFields#declare} throws for `values.length` components
+     */
+    set(name: string, values: ArrayLike<number>): void;
+    /**
+     * Visit every declared field, in declaration order.
+     * @param {function({name: string, offset: number, components: number}):void} visitor
+     */
+    forEach(visitor: (arg0: {
+        name: string;
+        offset: number;
+        components: number;
+    }) => void): void;
+    #private;
+}
+//# sourceMappingURL=ParticleGlobalFields.d.ts.map

package/src/shade/renderer/particles/runtime/ParticleGlobalFields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleGlobalFields.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ParticleGlobalFields.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;GAWG;AACH;IAkBI;;;OAGG;IACH,+BAHoB,MAAM,QAAE,MAAM,KAAE,IAAI,EAKvC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAIxE;IAED;;;;;;;;OAQG;IACH,eAHW,cAAc;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,QAqC3D;IAED;;;;;;;;;;;;OAYG;IACH,cANW,MAAM,cACN,MAAM,GACJ,MAAM,CA2BlB;IAED;;;;;;;OAOG;IACH,UAJW,MAAM,UACN,UAAU,MAAM,CAAC,QAa3B;IAED;;;OAGG;IACH,wBAFoB;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,KAAE,IAAI,QAM3E;;CACJ"}