@woosh/meep-engine 3.58.0 → 3.60.0

package/src/engine/graphics/ecs/particles/ParticleEffect.d.ts

@@ -18,11 +18,12 @@
  *
  * ## It is a description, and only a description
  *
- * Everything on it means the same thing with no renderer present: the attribute {@link layout} and
- * the compiled {@link program} that make up an effect, the {@link texture} to draw with, the rate,
- * the pre-warm, the blend / projection / feature {@link flags}, the render-attribute bindings and
- * the flipbook grid. That is deliberate, and it is what makes the component the unit an editor
- * inspects, a prefab carries and a system diffs.
+ * Everything on it means the same thing with no renderer present: the particle field {@link layout}
+ * and the compiled {@link program} that make up an effect, the {@link texture} to draw with, the
+ * rate, the pre-warm, the blend / projection / feature {@link flags}, the render-channel
+ * bindings, the flipbook grid, the emitter fields and the transform {@link bindings}. That is
+ * deliberate, and it is what makes the component the unit an editor inspects, a prefab carries and
+ * a system diffs.
  *
  * What is **not** here: the emitter the system built, the emitter's row in the GPU emitter table,
  * the generation of that row, where the program was placed in the program heap, and where the
@@ -47,19 +48,21 @@
  * Assign to the fields. The system compares what it holds against what it last wrote to the scene
  * node, once per frame per entity, so there is no flag to set and no signal to fire — a component
  * whose fields have not moved costs a run of comparisons and no upload. That is a deliberate trade
- * against the observable-per-field shape the older components use: an effect has fifteen fields,
+ * against the observable-per-field shape the older components use: an effect has eighteen fields,
  * gameplay writes them in bursts, and a row is restaged whole either way.
  *
  * ## Saving one
  *
- * {@link ./ParticleEffectSerializationAdapter.js} writes all of it, the compiled program included.
+ * {@link ./ParticleEffectSerializationAdapter.js} writes all of it but the {@link bindings}, the
+ * compiled program included.
  * The VM's instruction set is a durable format by design — fixed-width opcodes and a constant pool —
  * so a level carries the bytecode the way it carries a mesh's indices, and a shipped build needs
  * neither the graph the effect was compiled from nor a compiler at runtime. Authoring belongs to an
  * editor.
  *
- * Two things are consequently wire format: the opcode numbers, and the **order** of the attributes
- * in {@link layout}, because the offsets in the render bindings are assigned from that order.
+ * Two things are consequently wire format: the opcode numbers, and the **order** of the fields in
+ * {@link layout} and {@link emitter_layout}, because the offsets the render bindings and the
+ * emitter field values are stored at are assigned from that order.
  */
 export class ParticleEffect {
     /**
@@ -77,8 +80,10 @@ export class ParticleEffect {
      * @param {boolean} [config.emitting]
      * @param {number} [config.prewarm] seconds of emission to run forward before the first frame
      * @param {object} [config.flags] passed to `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] `[columns, rows]`
+     * @param {import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout|null} [config.emitter_layout]
+     * @param {ArrayLike<number>} [config.emitter_fields] f32 bit patterns laid out by `emitter_layout`
      * @returns {ParticleEffect}
      */
     static from(config?: {
@@ -94,9 +99,11 @@ export class ParticleEffect {
             [x: string]: string;
         };
         flipbook?: ArrayLike<number>;
+        emitter_layout?: import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout | null;
+        emitter_fields?: ArrayLike<number>;
     }): ParticleEffect;
     /**
-     * The per-particle attribute schema: which named attributes a particle of this effect has, how
+     * The particle field schema: which named particle fields a particle of this effect has, how
      * wide each is, and what word of the record it sits at.
      *
      * `null` until an effect is assigned. An entity whose component has none is linked and idle
@@ -182,7 +189,7 @@ export class ParticleEffect {
      * @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;
@@ -194,6 +201,56 @@ export class ParticleEffect {
     render_frame: number;
     /** @type {number} record word offset of velocity, read by the STRETCHED projection */
     render_velocity: number;
+    /**
+     * The emitter fields the effect declares — the members every emitter of it carries for itself,
+     * laid out from word zero. `null` for an effect that declares none. Part of the effect, as
+     * {@link layout} is: the program was compiled against it.
+     *
+     * @type {import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout|null}
+     */
+    emitter_layout: import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout | null;
+    /**
+     * This entity's values for those fields, as f32 bit patterns laid out by {@link emitter_layout}.
+     * The instance's own data: gameplay writes it ({@link set_emitter_field}), the program it runs
+     * is shared with every other entity of the effect. Words past the end of a shorter array read
+     * zero. Static: nothing on the GPU writes them, except a transform {@link bindings binding}.
+     *
+     * @type {Uint32Array}
+     */
+    emitter_fields: Uint32Array;
+    /**
+     * Transform bindings: emitter fields this entity's emitter has written every frame, on the GPU,
+     * from another entity's composed transform — a beam's far end, a homing target, a joint.
+     * `channel` is a {@link ../../../../shade/renderer/particles/data/PARTICLE_FIELD_BINDING.js PARTICLE_FIELD_BINDING_CHANNEL}
+     * and must write exactly as many words as the field has.
+     *
+     * The system reads this array every frame, so editing it in place is enough. A binding naming
+     * an entity with no Transform64, or a field the effect does not have at the channel's width, is
+     * refused with a warning and not retried until the entry or the {@link emitter_layout}
+     * changes. Where two entries name one field, the first holds. A binding ends when its entry is
+     * removed or its entity is.
+     *
+     * Runtime data, and not saved: a binding names an entity, and nothing in this engine's saves
+     * carries an entity reference across a load (no component holding one is serialized). A level
+     * binds them again when it is built, as it parents its attachments.
+     *
+     * @type {Array<{field: string, entity: number, channel: number}>}
+     */
+    bindings: Array<{
+        field: string;
+        entity: number;
+        channel: number;
+    }>;
+    /**
+     * Set one emitter field, by name, to `values` — as many numbers as the field has components.
+     * The system finds the change by comparison, as it finds every other edit to this component.
+     *
+     * @param {string} name a field of {@link emitter_layout}
+     * @param {ArrayLike<number>} values
+     * @returns {ParticleEffect} this
+     * @throws if {@link emitter_layout} has no such field
+     */
+    set_emitter_field(name: string, values: ArrayLike<number>): ParticleEffect;
     /**
      * The rate the emitter actually runs at: {@link spawn_rate} while {@link emitting}, and zero
      * otherwise. What the system writes to the GPU record.
@@ -202,11 +259,11 @@ export class ParticleEffect {
      */
     get effective_spawn_rate(): number;
     /**
-     * Bind render channels to per-particle attributes of this effect, by attribute name.
+     * Bind render channels to particle fields of this 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 effect 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 effect has no such
+     * particle field" — the passes that draw substitute a default, and the bounds pass treats the
      * particle as being at the origin.
      *
      * Word offsets are stored rather than names because that is what those passes index a particle
@@ -214,7 +271,7 @@ export class ParticleEffect {
      * needs {@link layout} to have been set first.
      *
      * @param {Object<string,string>} channels channel name (see `EMITTER_RENDER_CHANNELS`) ->
-     *        attribute name in this effect's layout
+     *        particle field name in this effect's layout
      * @returns {ParticleEffect} this
      */
     bind_render(channels: {
@@ -232,7 +289,7 @@ export class ParticleEffect {
      */
     equals(other: ParticleEffect): boolean;
     /**
-     * Hash over everything {@link equals} compares, in the same terms.
+     * Hash over everything {@link equals} compares but the {@link bindings}, in the same terms.
      *
      * @returns {number} int32
      */

package/src/engine/graphics/ecs/particles/ParticleEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleEffect.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/particles/ParticleEffect.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH;IAoRI;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAZ2G,MAAM,GAAtG,OAAO,+DAA+D,EAAE,cAAc;QACS,OAAO,GAAtG,OAAO,6DAA6D,EAAE,eAAe;QAChE,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACW,QAAQ,GAAzB,OAAO;QACS,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACf,cAAc,CA8C1B;IAjVD;;;;;;;;;OASG;IACH,QAFU,OAAO,+DAA+D,EAAE,cAAc,GAAC,IAAI,CAEvF;IAEd;;;;;OAKG;IACH,SAFU,OAAO,6DAA6D,EAAE,eAAe,GAAC,IAAI,CAErF;IAEf;;;;;;;;;OASG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;OAUG;IACH,UAFU,OAAO,CAED;IAEhB;;;;;;;;;;;;;OAaG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;OAKG;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;;;;;OAKG;IACH,mCAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH;YAJkB,MAAM,GAAC,MAAM;QAElB,cAAc,CAuC1B;IAED;;;;;;;;;OASG;IACH,cAHW,cAAc,GACZ,OAAO,CAsBnB;IAED;;;;OAIG;IACH,QAFa,MAAM,CAuBlB;IAED;;;;;;;;;OASG;IACH,YAHW,cAAc,GACZ,cAAc,CAuB1B;IAED;;OAEG;IACH,SAFa,cAAc,CAI1B;IAgFL;;;;;OAKG;IACH,2BAFU,OAAO,CAEwB;CApBxC;;kBAUS,MAAM"}
+{"version":3,"file":"ParticleEffect.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/particles/ParticleEffect.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH;IAkXI;;;;;;;;;;;;;;;;;;;;OAoBG;IACH;QAd2G,MAAM,GAAtG,OAAO,+DAA+D,EAAE,cAAc;QACS,OAAO,GAAtG,OAAO,6DAA6D,EAAE,eAAe;QAChE,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACW,QAAQ,GAAzB,OAAO;QACS,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACoF,cAAc,GAAnH,OAAO,+DAA+D,EAAE,cAAc,GAAC,IAAI;QAChE,cAAc,GAAzC,UAAU,MAAM,CAAC;QACf,cAAc,CAsD1B;IAzbD;;;;;;;;;OASG;IACH,QAFU,OAAO,+DAA+D,EAAE,cAAc,GAAC,IAAI,CAEvF;IAEd;;;;;OAKG;IACH,SAFU,OAAO,6DAA6D,EAAE,eAAe,GAAC,IAAI,CAErF;IAEf;;;;;;;;;OASG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;OAUG;IACH,UAFU,OAAO,CAED;IAEhB;;;;;;;;;;;;;OAaG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;OAKG;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;;;;;;OAMG;IACH,gBAFU,OAAO,+DAA+D,EAAE,cAAc,GAAC,IAAI,CAE/E;IAEtB;;;;;;;OAOG;IACH,gBAFU,WAAW,CAEe;IAEpC;;;;;;;;;;;;;;;;;OAiBG;IACH,UAFU,MAAM;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC,CAEnD;IAEd;;;;;;;;OAQG;IACH,wBALW,MAAM,UACN,UAAU,MAAM,CAAC,GACf,cAAc,CA2B1B;IAED;;;;;OAKG;IACH,mCAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH;YAJkB,MAAM,GAAC,MAAM;QAElB,cAAc,CAuC1B;IAED;;;;;;;;;OASG;IACH,cAHW,cAAc,GACZ,OAAO,CAyBnB;IAED;;;;OAIG;IACH,QAFa,MAAM,CA4BlB;IAED;;;;;;;;;OASG;IACH,YAHW,cAAc,GACZ,cAAc,CAmC1B;IAED;;OAEG;IACH,SAFa,cAAc,CAI1B;IAiHL;;;;;OAKG;IACH,2BAFU,OAAO,CAEwB;CA3CxC;;kBAiCS,MAAM"}

package/src/engine/graphics/ecs/particles/ParticleEffect.js

@@ -1,6 +1,7 @@
 import { assert } from "../../../../core/assert.js";
 import { float32_array_hash } from "../../../../core/collection/array/typed/float32_array_hash.js";
 import { is_typed_array_equals } from "../../../../core/collection/array/typed/is_typed_array_equals.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 { objectsEqual } from "../../../../core/function/objectsEqual.js";
@@ -8,7 +9,7 @@ import { optional_hash } from "../../../../core/model/object/optional_hash.js";
 import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import {
-    EMITTER_ATTRIBUTE_ABSENT,
+    PARTICLE_FIELD_ABSENT,
     make_emitter_flags
 } from "../../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
 import { EMITTER_RENDER_CHANNELS } from "../../../../shade/renderer/particles/runtime/ParticleEmitter.js";
@@ -33,11 +34,12 @@ import { EMITTER_RENDER_CHANNELS } from "../../../../shade/renderer/particles/ru
  *
  * ## It is a description, and only a description
  *
- * Everything on it means the same thing with no renderer present: the attribute {@link layout} and
- * the compiled {@link program} that make up an effect, the {@link texture} to draw with, the rate,
- * the pre-warm, the blend / projection / feature {@link flags}, the render-attribute bindings and
- * the flipbook grid. That is deliberate, and it is what makes the component the unit an editor
- * inspects, a prefab carries and a system diffs.
+ * Everything on it means the same thing with no renderer present: the particle field {@link layout}
+ * and the compiled {@link program} that make up an effect, the {@link texture} to draw with, the
+ * rate, the pre-warm, the blend / projection / feature {@link flags}, the render-channel
+ * bindings, the flipbook grid, the emitter fields and the transform {@link bindings}. That is
+ * deliberate, and it is what makes the component the unit an editor inspects, a prefab carries and
+ * a system diffs.
  *
  * What is **not** here: the emitter the system built, the emitter's row in the GPU emitter table,
  * the generation of that row, where the program was placed in the program heap, and where the
@@ -62,24 +64,26 @@ import { EMITTER_RENDER_CHANNELS } from "../../../../shade/renderer/particles/ru
  * Assign to the fields. The system compares what it holds against what it last wrote to the scene
  * node, once per frame per entity, so there is no flag to set and no signal to fire — a component
  * whose fields have not moved costs a run of comparisons and no upload. That is a deliberate trade
- * against the observable-per-field shape the older components use: an effect has fifteen fields,
+ * against the observable-per-field shape the older components use: an effect has eighteen fields,
  * gameplay writes them in bursts, and a row is restaged whole either way.
  *
  * ## Saving one
  *
- * {@link ./ParticleEffectSerializationAdapter.js} writes all of it, the compiled program included.
+ * {@link ./ParticleEffectSerializationAdapter.js} writes all of it but the {@link bindings}, the
+ * compiled program included.
  * The VM's instruction set is a durable format by design — fixed-width opcodes and a constant pool —
  * so a level carries the bytecode the way it carries a mesh's indices, and a shipped build needs
  * neither the graph the effect was compiled from nor a compiler at runtime. Authoring belongs to an
  * editor.
  *
- * Two things are consequently wire format: the opcode numbers, and the **order** of the attributes
- * in {@link layout}, because the offsets in the render bindings are assigned from that order.
+ * Two things are consequently wire format: the opcode numbers, and the **order** of the fields in
+ * {@link layout} and {@link emitter_layout}, because the offsets the render bindings and the
+ * emitter field values are stored at are assigned from that order.
  */
 export class ParticleEffect {
 
     /**
-     * The per-particle attribute schema: which named attributes a particle of this effect has, how
+     * The particle field schema: which named particle fields a particle of this effect has, how
      * wide each is, and what word of the record it sits at.
      *
      * `null` until an effect is assigned. An entity whose component has none is linked and idle
@@ -174,18 +178,92 @@ export class ParticleEffect {
      */
     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;
+
+    /**
+     * The emitter fields the effect declares — the members every emitter of it carries for itself,
+     * laid out from word zero. `null` for an effect that declares none. Part of the effect, as
+     * {@link layout} is: the program was compiled against it.
+     *
+     * @type {import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout|null}
+     */
+    emitter_layout = null;
+
+    /**
+     * This entity's values for those fields, as f32 bit patterns laid out by {@link emitter_layout}.
+     * The instance's own data: gameplay writes it ({@link set_emitter_field}), the program it runs
+     * is shared with every other entity of the effect. Words past the end of a shorter array read
+     * zero. Static: nothing on the GPU writes them, except a transform {@link bindings binding}.
+     *
+     * @type {Uint32Array}
+     */
+    emitter_fields = new Uint32Array(0);
+
+    /**
+     * Transform bindings: emitter fields this entity's emitter has written every frame, on the GPU,
+     * from another entity's composed transform — a beam's far end, a homing target, a joint.
+     * `channel` is a {@link ../../../../shade/renderer/particles/data/PARTICLE_FIELD_BINDING.js PARTICLE_FIELD_BINDING_CHANNEL}
+     * and must write exactly as many words as the field has.
+     *
+     * The system reads this array every frame, so editing it in place is enough. A binding naming
+     * an entity with no Transform64, or a field the effect does not have at the channel's width, is
+     * refused with a warning and not retried until the entry or the {@link emitter_layout}
+     * changes. Where two entries name one field, the first holds. A binding ends when its entry is
+     * removed or its entity is.
+     *
+     * Runtime data, and not saved: a binding names an entity, and nothing in this engine's saves
+     * carries an entity reference across a load (no component holding one is serialized). A level
+     * binds them again when it is built, as it parents its attachments.
+     *
+     * @type {Array<{field: string, entity: number, channel: number}>}
+     */
+    bindings = [];
+
+    /**
+     * Set one emitter field, by name, to `values` — as many numbers as the field has components.
+     * The system finds the change by comparison, as it finds every other edit to this component.
+     *
+     * @param {string} name a field of {@link emitter_layout}
+     * @param {ArrayLike<number>} values
+     * @returns {ParticleEffect} this
+     * @throws if {@link emitter_layout} has no such field
+     */
+    set_emitter_field(name, values) {
+        assert.notEqual(this.emitter_layout, null, 'emitter_layout must be set before an emitter field is');
+
+        const field = this.emitter_layout.get(name);
+
+        assert.equal(values.length, field.components, 'values.length');
+
+        const word_count = this.emitter_layout.word_count;
+
+        if (this.emitter_fields.length < word_count) {
+            const grown = new Uint32Array(word_count);
+
+            grown.set(this.emitter_fields);
+            this.emitter_fields = grown;
+        }
+
+        const words = this.emitter_fields;
+
+        for (let i = 0; i < field.components; i++) {
+            FIELD_WORD_F32[0] = values[i];
+            words[field.offset + i] = FIELD_WORD[0];
+        }
+
+        return this;
+    }
 
     /**
      * The rate the emitter actually runs at: {@link spawn_rate} while {@link emitting}, and zero
@@ -198,11 +276,11 @@ export class ParticleEffect {
     }
 
     /**
-     * Bind render channels to per-particle attributes of this effect, by attribute name.
+     * Bind render channels to particle fields of this 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 effect 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 effect has no such
+     * particle field" — the passes that draw substitute a default, and the bounds pass treats the
      * particle as being at the origin.
      *
      * Word offsets are stored rather than names because that is what those passes index a particle
@@ -210,7 +288,7 @@ export class ParticleEffect {
      * needs {@link layout} to have been set first.
      *
      * @param {Object<string,string>} channels channel name (see `EMITTER_RENDER_CHANNELS`) ->
-     *        attribute name in this effect's layout
+     *        particle field name in this effect's layout
      * @returns {ParticleEffect} this
      */
     bind_render(channels) {
@@ -280,12 +358,15 @@ export class ParticleEffect {
             && 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)
+            && bindings_equal(this.bindings, other.bindings)
+            && objectsEqual(this.emitter_layout, other.emitter_layout)
             && objectsEqual(this.layout, other.layout)
             && objectsEqual(this.program, other.program);
     }
 
     /**
-     * Hash over everything {@link equals} compares, in the same terms.
+     * Hash over everything {@link equals} compares but the {@link bindings}, in the same terms.
      *
      * @returns {number} int32
      */
@@ -302,8 +383,13 @@ export class ParticleEffect {
             this.emitting ? 1 : 0
         );
 
+        const fields = hash_mix2(
+            optional_hash(this.emitter_layout),
+            uint32_array_hash(this.emitter_fields, 0, this.emitter_fields.length)
+        );
+
         return hash_mix3(
-            hash_mix2(bindings, float32_array_hash(this.flipbook, 0, this.flipbook.length)),
+            hash_mix3(bindings, float32_array_hash(this.flipbook, 0, this.flipbook.length), fields),
             appearance,
             hash_mix2(
                 optional_hash(this.layout),
@@ -342,6 +428,18 @@ export class ParticleEffect {
         this.render_frame = other.render_frame;
         this.render_velocity = other.render_velocity;
 
+        // shared, as the layout and the program are: immutable once compiled
+        this.emitter_layout = other.emitter_layout;
+
+        // the values are not — they are the instance's, and gameplay writes them in place
+        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);
+
+        this.bindings = other.bindings.map(binding => ({ ...binding }));
+
         return this;
     }
 
@@ -367,8 +465,10 @@ export class ParticleEffect {
      * @param {boolean} [config.emitting]
      * @param {number} [config.prewarm] seconds of emission to run forward before the first frame
      * @param {object} [config.flags] passed to `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] `[columns, rows]`
+     * @param {import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout|null} [config.emitter_layout]
+     * @param {ArrayLike<number>} [config.emitter_fields] f32 bit patterns laid out by `emitter_layout`
      * @returns {ParticleEffect}
      */
     static from(config = {}) {
@@ -414,10 +514,41 @@ export class ParticleEffect {
             effect.bind_render(config.render);
         }
 
+        if (config.emitter_layout !== undefined) {
+            effect.emitter_layout = config.emitter_layout;
+        }
+
+        if (config.emitter_fields !== undefined) {
+            effect.emitter_fields = Uint32Array.from(config.emitter_fields);
+        }
+
         return effect;
     }
 }
 
+/**
+ * @param {Array<{field: string, entity: number, channel: number}>} a
+ * @param {Array<{field: string, entity: number, channel: number}>} b
+ * @returns {boolean}
+ */
+function bindings_equal(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+
+    for (let i = 0; i < a.length; i++) {
+        if (a[i].field !== b[i].field || a[i].entity !== b[i].entity || a[i].channel !== b[i].channel) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+// One word reinterpreted: an emitter field is stored as f32 bit patterns.
+const FIELD_WORD = new Uint32Array(1);
+const FIELD_WORD_F32 = new Float32Array(FIELD_WORD.buffer);
+
 /**
  * The name this component is written under, and looked up by when a save is read. A serialization
  * registry infers nothing from a class — see

package/src/engine/graphics/ecs/particles/ParticleEffectSerializationAdapter.d.ts

@@ -11,9 +11,9 @@
  * and cannot be renumbered without a version bump and an upgrader:
  *
  * - **opcodes**, whose numbers are `../../../../shade/renderer/particles/isa/ParticleVMISA.js`, and
- * - **attribute order in the layout**, because a layout assigns word offsets sequentially from the
- *   order it is built in, and the render bindings below are those offsets. Offsets are therefore not
- *   written: they are recomputed on load from the same order, and a change to how
+ * - **particle field order in the layout**, because a layout assigns word offsets sequentially from
+ *   the order it is built in, and the render bindings below are those offsets. Offsets are
+ *   therefore not written: they are recomputed on load from the same order, and a change to how
  *   {@link ParticleLayout} packs would silently repoint every binding in every save.
  *
  * ## The constant pool is written as bits
@@ -38,6 +38,16 @@
  * saved bytecode writes an angle, and nothing short of recompiling its graph turns that into a
  * program that writes a quaternion. A v1 effect that spun loads without its spin.
  *
+ * ## Version 3
+ *
+ * After the program come the global fields it imports, by name and width in import order — what
+ * its global reads index until it is placed and linked — and after that the emitter field layout,
+ * written like the particle field layout and with the same obligation on its order, and this
+ * entity's emitter field values as bits. A v2 save is read through
+ * {@link ./ParticleEffectSerializationUpgrader_2_3.js} as importing and declaring none.
+ *
+ * {@link ParticleEffect#bindings} are not written: they name entities.
+ *
  * ## Nothing device-shaped is written
  *
  * There is nothing here that a device assigned: no table row, no generation, no program-heap

package/src/engine/graphics/ecs/particles/ParticleEffectSerializationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleEffectSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/particles/ParticleEffectSerializationAdapter.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;;IAEI,6BAAuB;IAGvB;;;OAGG;IACH,uCAFW,cAAc,QAmCxB;IAED;;;OAGG;IACH,yCAFW,cAAc,QA8BxB;CACJ;gDAjI+C,gEAAgE;+BACjF,qBAAqB"}
+{"version":3,"file":"ParticleEffectSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/particles/ParticleEffectSerializationAdapter.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH;;IAEI,6BAAuB;IAGvB;;;OAGG;IACH,uCAFW,cAAc,QA4CxB;IAED;;;OAGG;IACH,yCAFW,cAAc,QAmCxB;CACJ;gDAzJ+C,gEAAgE;+BACjF,qBAAqB"}