@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -16,9 +16,9 @@ import { ParticleEffect } from "./ParticleEffect.js";
  * 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
@@ -43,6 +43,16 @@ import { ParticleEffect } from "./ParticleEffect.js";
  * 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
@@ -55,7 +65,7 @@ import { ParticleEffect } from "./ParticleEffect.js";
 export class ParticleEffectSerializationAdapter extends BinaryClassSerializationAdapter {
 
     klass = ParticleEffect;
-    version = 2;
+    version = 3;
 
     /**
      * @param {BinaryBuffer} buffer
@@ -94,6 +104,15 @@ export class ParticleEffectSerializationAdapter extends BinaryClassSerialization
 
         write_layout(buffer, value.layout);
         write_program(buffer, value.program);
+
+        // the emitter fields: whether the effect declares a layout, the layout, this entity's values
+        buffer.writeUint8(value.emitter_layout === null ? 0 : 1);
+
+        if (value.emitter_layout !== null) {
+            write_layout(buffer, value.emitter_layout);
+        }
+
+        write_words(buffer, value.emitter_fields);
     }
 
     /**
@@ -122,12 +141,17 @@ export class ParticleEffectSerializationAdapter extends BinaryClassSerialization
         if (buffer.readUint8() !== 1) {
             value.layout = null;
             value.program = null;
+            value.emitter_layout = null;
+            value.emitter_fields = new Uint32Array(0);
 
             return;
         }
 
         value.layout = read_layout(buffer);
         value.program = read_program(buffer);
+
+        value.emitter_layout = buffer.readUint8() === 1 ? read_layout(buffer, true) : null;
+        value.emitter_fields = read_words(buffer);
     }
 }
 
@@ -136,39 +160,40 @@ export class ParticleEffectSerializationAdapter extends BinaryClassSerialization
  * @param {ParticleLayout} layout
  */
 function write_layout(buffer, layout) {
-    buffer.writeUintVar(layout.attributes.size);
+    buffer.writeUintVar(layout.fields.size);
 
     // Insertion order, which is the order the offsets were assigned in and therefore the order they
     // have to be rebuilt in. A Map iterates in insertion order by specification, so this is not an
     // assumption about the implementation.
-    for (const attribute of layout.attributes.values()) {
-        buffer.writeUTF8String(attribute.name);
-        buffer.writeUint8(attribute.components);
+    for (const particle_field of layout.fields.values()) {
+        buffer.writeUTF8String(particle_field.name);
+        buffer.writeUint8(particle_field.components);
 
         // The semantic tag, and `null` where there is none. An effect saved with a tag this build
         // has never heard of has to load as the plain vector it is rather than fail, which is why
         // the tag is a string here as it is on the layout.
-        buffer.writeUTF8String(attribute.type ?? null);
+        buffer.writeUTF8String(particle_field.type ?? null);
     }
 }
 
 /**
  * @param {BinaryBuffer} buffer
+ * @param {boolean} [emitter] whether this is an emitter field layout, packed from word zero
  * @returns {ParticleLayout}
  */
-function read_layout(buffer) {
+function read_layout(buffer, emitter = false) {
     const count = buffer.readUintVar();
-    const attributes = [];
+    const particle_fields = [];
 
     for (let i = 0; i < count; i++) {
         const name = buffer.readUTF8String();
         const components = buffer.readUint8();
         const type = buffer.readUTF8String();
 
-        attributes.push(type === null ? { name, components } : { name, components, type });
+        particle_fields.push(type === null ? { name, components } : { name, components, type });
     }
 
-    return new ParticleLayout(attributes);
+    return emitter ? ParticleLayout.emitter(particle_fields) : new ParticleLayout(particle_fields);
 }
 
 /**
@@ -182,6 +207,16 @@ function write_program(buffer, program) {
     write_words(buffer, program.update);
     // bits rather than floats — see the class note
     write_words(buffer, program.constant_words);
+
+    // the global fields the program imports, in import order — see the class note
+    const imports = program.global_imports;
+
+    buffer.writeUintVar(imports.length);
+
+    for (let i = 0; i < imports.length; i++) {
+        buffer.writeUTF8String(imports[i].name);
+        buffer.writeUint8(imports[i].components);
+    }
 }
 
 /**
@@ -195,7 +230,18 @@ function read_program(buffer) {
     const update = read_words(buffer);
     const constant_words = read_words(buffer);
 
+    const import_count = buffer.readUintVar();
+    const global_imports = [];
+
+    for (let i = 0; i < import_count; i++) {
+        const name = buffer.readUTF8String();
+        const components = buffer.readUint8();
+
+        global_imports.push({ name, components });
+    }
+
     return new ParticleProgram({
+        global_imports,
         init,
         update,
         // the same bytes read as floats: `read_words` allocates its own buffer, so this view owns it

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

@@ -5,9 +5,9 @@
  * The two versions lay out the same bytes. What changed is what the fourth render binding means: a
  * record word holding a roll angle in v1, the first of four holding a quaternion in v2. A v1 binding
  * cannot be carried over — read as a quaternion it would take the angle and whatever three
- * attributes follow it — and the saved bytecode writes an angle, which no rewriting of a binding
- * turns into a quaternion. So the binding is dropped and the effect loads unturned; recompiling its
- * graph with an orientation is the author's move.
+ * particle fields follow it — and the saved bytecode writes an angle, which no rewriting of a
+ * binding turns into a quaternion. So the binding is dropped and the effect loads unturned;
+ * recompiling its graph with an orientation is the author's move.
  *
  * A frozen reader of v1, field by field, rather than a call into the current adapter: the adapter
  * will move on, and this has to keep reading what v1 wrote.

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

@@ -1,4 +1,4 @@
-import { EMITTER_ATTRIBUTE_ABSENT } from "../../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
+import { PARTICLE_FIELD_ABSENT } from "../../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
 import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
 
 /**
@@ -8,9 +8,9 @@ import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgr
  * The two versions lay out the same bytes. What changed is what the fourth render binding means: a
  * record word holding a roll angle in v1, the first of four holding a quaternion in v2. A v1 binding
  * cannot be carried over — read as a quaternion it would take the angle and whatever three
- * attributes follow it — and the saved bytecode writes an angle, which no rewriting of a binding
- * turns into a quaternion. So the binding is dropped and the effect loads unturned; recompiling its
- * graph with an orientation is the author's move.
+ * particle fields follow it — and the saved bytecode writes an angle, which no rewriting of a
+ * binding turns into a quaternion. So the binding is dropped and the effect loads unturned;
+ * recompiling its graph with an orientation is the author's move.
  *
  * A frozen reader of v1, field by field, rather than a call into the current adapter: the adapter
  * will move on, and this has to keep reading what v1 wrote.
@@ -43,7 +43,7 @@ export class ParticleEffectSerializationUpgrader_1_2 extends BinaryClassUpgrader
         target.writeUint32(source.readUint32()); // color
 
         source.readUint32(); // the roll's binding, which has no orientation to become
-        target.writeUint32(EMITTER_ATTRIBUTE_ABSENT);
+        target.writeUint32(PARTICLE_FIELD_ABSENT);
 
         target.writeUint32(source.readUint32()); // frame
         target.writeUint32(source.readUint32()); // velocity
@@ -56,12 +56,12 @@ export class ParticleEffectSerializationUpgrader_1_2 extends BinaryClassUpgrader
             return;
         }
 
-        // the layout: attribute count, then name, component count and semantic tag of each
-        const attribute_count = source.readUintVar();
+        // the layout: particle field count, then name, component count and semantic tag of each
+        const particle_field_count = source.readUintVar();
 
-        target.writeUintVar(attribute_count);
+        target.writeUintVar(particle_field_count);
 
-        for (let i = 0; i < attribute_count; i++) {
+        for (let i = 0; i < particle_field_count; i++) {
             target.writeUTF8String(source.readUTF8String());
             target.writeUint8(source.readUint8());
             target.writeUTF8String(source.readUTF8String());

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

@@ -0,0 +1,15 @@
+/**
+ * Version 3 appends the global fields the program imports to the program, and after it the emitter
+ * fields the effect declares, with this entity's values. A version-2 effect has neither, so both
+ * are written empty; everything else is carried across word for word. A component with no effect
+ * ends at its presence byte, as in version 2.
+ */
+export class ParticleEffectSerializationUpgrader_2_3 extends BinaryClassUpgrader {
+    /**
+     * @param {BinaryBuffer} source
+     * @param {BinaryBuffer} target
+     */
+    upgrade(source: BinaryBuffer, target: BinaryBuffer): void;
+}
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+//# sourceMappingURL=ParticleEffectSerializationUpgrader_2_3.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleEffectSerializationUpgrader_2_3.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/particles/ParticleEffectSerializationUpgrader_2_3.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IAII;;;OAGG;IACH,0DA8CC;CACJ;oCA/DmC,oDAAoD"}

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

@@ -0,0 +1,78 @@
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+
+/**
+ * Version 3 appends the global fields the program imports to the program, and after it the emitter
+ * fields the effect declares, with this entity's values. A version-2 effect has neither, so both
+ * are written empty; everything else is carried across word for word. A component with no effect
+ * ends at its presence byte, as in version 2.
+ */
+export class ParticleEffectSerializationUpgrader_2_3 extends BinaryClassUpgrader {
+    __startVersion = 2;
+    __targetVersion = 3;
+
+    /**
+     * @param {BinaryBuffer} source
+     * @param {BinaryBuffer} target
+     */
+    upgrade(source, target) {
+        target.writeUTF8String(source.readUTF8String()); // texture
+
+        target.writeUintVar(source.readUintVar()); // seed
+        target.writeFloat32(source.readFloat32()); // spawn rate
+        target.writeFloat32(source.readFloat32()); // pre-warm
+        target.writeUint8(source.readUint8()); // emitting
+        target.writeUint32(source.readUint32()); // flags
+
+        target.writeFloat32(source.readFloat32()); // flipbook columns
+        target.writeFloat32(source.readFloat32()); // flipbook rows
+
+        for (let channel = 0; channel < 6; channel++) {
+            target.writeUint32(source.readUint32()); // position, size, color, orientation, frame, velocity
+        }
+
+        const present = source.readUint8();
+
+        target.writeUint8(present);
+
+        if (present !== 1) {
+            return;
+        }
+
+        // the layout: particle field count, then name, component count and semantic tag of each
+        const particle_field_count = source.readUintVar();
+
+        target.writeUintVar(particle_field_count);
+
+        for (let i = 0; i < particle_field_count; i++) {
+            target.writeUTF8String(source.readUTF8String());
+            target.writeUint8(source.readUint8());
+            target.writeUTF8String(source.readUTF8String());
+        }
+
+        // the program: register count, then INIT, UPDATE and the constant pool as word arrays
+        target.writeUint8(source.readUint8());
+
+        copy_words(source, target);
+        copy_words(source, target);
+        copy_words(source, target);
+
+        target.writeUintVar(0); // the program's global imports
+
+        target.writeUint8(0); // no emitter field layout
+        target.writeUintVar(0); // the emitter field values
+    }
+}
+
+/**
+ * @param {BinaryBuffer} source
+ * @param {BinaryBuffer} target
+ */
+function copy_words(source, target) {
+    const length = source.readUintVar();
+    const words = new Uint32Array(length);
+
+    source.readUint32Array(words, 0, length);
+
+    target.writeUintVar(length);
+    target.writeUint32Array(words, 0, length);
+}

package/src/engine/graphics/ecs/trail3d/Trail3D.d.ts

@@ -56,6 +56,8 @@ declare class Trail3D {
     /**
      * RGB tints the tube; alpha is the trail's base opacity, which the
      * age-driven fade scales down to zero.
+     *
+     * Linear color space.
      * @readonly
      * @type {Color}
      */

package/src/engine/graphics/ecs/trail3d/Trail3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Trail3D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/Trail3D.js"],"names":[],"mappings":";AAgCA;;;;;GAKG;AACH;IA4PI,oCAMC;IAhQD;;;OAGG;IACH,QAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,gBAFU,MAAM,CAEyB;IAEzC;;;OAGG;IACH,WAFU,cAAc,GAAC,MAAM,CAEC;IAEhC;;;;OAIG;IACH,eAFU,MAAM,CAEuB;IAEvC;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;;OAKG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;;;;OAOG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,MAFU,KAAK,GAAC,IAAI,CAER;IAEZ;;;;;;;OAOG;IACH,MAFU,OAAK,IAAI,CAEP;IAEZ;;;OAGG;IACH,UAFU,iBAAiB,CAEQ;IAEnC;;;OAGG;IACH,cAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,cAAsB;IAEtB,gBAgBC;IAMD,0BAEC;IAND,yBAEC;IAUD,2BAEC;IAND,0BAEC;IA0BD;;OAEG;IACH,gCAQC;IA/BD;;;;;;;;;;;;;;;OAeG;IACH,+BAEC;IAeD;;;OAGG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GAAC,YAAY,SACnB,OAAO,QAQjB;IAED;;;OAGG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,OAAO,CAInB;IAED;;;;;;OAMG;IACH,qBAFW,MAAM,QAShB;IAED;;OAEG;IACH,cAmBC;IAUD;;;;;;;;;;;;;;;;aAwBC;IAED;;;;;;;;;;;;;;;;;;;;MAaC;IAED;;OAEG;IACH,cAFW,OAAO,WAcjB;IAkDD;;;;;;OAMG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CAiEnB;;CAEJ;;;;;+BAnd8B,+BAA+B;sBANxC,iCAAiC;oBACnC,kCAAkC;sBAQhC,2BAA2B;kCACf,uCAAuC;0BAX/C,yCAAyC;6BAYtC,mBAAmB"}
+{"version":3,"file":"Trail3D.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/Trail3D.js"],"names":[],"mappings":";AAgCA;;;;;GAKG;AACH;IA8PI,oCAMC;IAlQD;;;OAGG;IACH,QAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,gBAFU,MAAM,CAEyB;IAEzC;;;OAGG;IACH,WAFU,cAAc,GAAC,MAAM,CAEC;IAEhC;;;;OAIG;IACH,eAFU,MAAM,CAEuB;IAEvC;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;;;;OAOG;IACH,gBAFU,KAAK,CAEe;IAE9B;;;;;;;OAOG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;OAGG;IACH,MAFU,KAAK,GAAC,IAAI,CAER;IAEZ;;;;;;;OAOG;IACH,MAFU,OAAK,IAAI,CAEP;IAEZ;;;OAGG;IACH,UAFU,iBAAiB,CAEQ;IAEnC;;;OAGG;IACH,cAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,cAAsB;IAEtB,gBAgBC;IAMD,0BAEC;IAND,yBAEC;IAUD,2BAEC;IAND,0BAEC;IA0BD;;OAEG;IACH,gCAQC;IA/BD;;;;;;;;;;;;;;;OAeG;IACH,+BAEC;IAeD;;;OAGG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GAAC,YAAY,GACjB,IAAI,CAIhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GAAC,YAAY,SACnB,OAAO,QAQjB;IAED;;;OAGG;IACH,cAHW,MAAM,GAAC,YAAY,GACjB,OAAO,CAInB;IAED;;;;;;OAMG;IACH,qBAFW,MAAM,QAShB;IAED;;OAEG;IACH,cAmBC;IAUD;;;;;;;;;;;;;;;;aAwBC;IAED;;;;;;;;;;;;;;;;;;;;MAaC;IAED;;OAEG;IACH,cAFW,OAAO,WAcjB;IAkDD;;;;;;OAMG;IACH,cANW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,GACJ,OAAO,CAiEnB;;CAEJ;;;;;+BArd8B,+BAA+B;sBANxC,iCAAiC;oBACnC,kCAAkC;sBAQhC,2BAA2B;kCACf,uCAAuC;0BAX/C,yCAAyC;6BAYtC,mBAAmB"}

package/src/engine/graphics/ecs/trail3d/Trail3D.js

@@ -96,6 +96,8 @@ class Trail3D {
     /**
      * RGB tints the tube; alpha is the trail's base opacity, which the
      * age-driven fade scales down to zero.
+     *
+     * Linear color space.
      * @readonly
      * @type {Color}
      */

package/src/engine/graphics/ecs/trail3d/seed_trail_stroke.js

@@ -79,7 +79,7 @@ export function seed_trail_stroke(trail, from, to, age_from, age_to) {
         // the stroke is straight, so every ring shares one frame and no transport is needed
         tube.setKnotFrame(i, frame[0], frame[1], frame[2], frame[3], frame[4], frame[5]);
 
-        tube.setKnotColor(i, color.x * 255, color.y * 255, color.z * 255);
+        tube.setKnotColor(i, color.x, color.y, color.z);
         tube.setKnotThickness(i, trail.width);
         tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_UV_V, f);
         tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_AGE, age);

package/src/engine/graphics/ecs/trail3d/seed_trail_tube.js

@@ -62,7 +62,7 @@ export function seed_trail_tube(trail, transform) {
     for (let i = 0; i < segment_count; i++) {
         const f = i / (segment_count - 1);
 
-        tube.setKnotColor(i, color.x * 255, color.y * 255, color.z * 255);
+        tube.setKnotColor(i, color.x, color.y, color.z);
         tube.setKnotPosition(i, position_x, position_y, position_z);
         tube.setKnotThickness(i, trail.width);
         tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_UV_V, f);

package/src/engine/graphics/trail/tube/TubeX.d.ts

@@ -135,10 +135,12 @@ export class TubeX {
      */
     setKnotFrame(knot_index: number, nx: number, ny: number, nz: number, bx: number, by: number, bz: number): void;
     /**
+     * Linear colour, stored at half precision. Not limited to 0..1: values above 1 are HDR.
+     *
      * @param {number} knot_index
-     * @param {number} r 0..255
-     * @param {number} g 0..255
-     * @param {number} b 0..255
+     * @param {number} r
+     * @param {number} g
+     * @param {number} b
      */
     setKnotColor(knot_index: number, r: number, g: number, b: number): void;
     /**

package/src/engine/graphics/trail/tube/TubeX.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TubeX.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/TubeX.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAoEI;;;;;OAKG;IACH,2BAEC;IAED;;;;;OAKG;IACH,2BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,YAFa,MAAM,CAIlB;IAED;;OAEG;IACH,qBAFa,MAAM,CAIlB;IAED,uBAEC;IAED,uBAEC;IAiGD;;;OAGG;IACH,wBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,QAShB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,QAShB;IAED;;;;OAIG;IACH,wBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,QAShB;IAED;;;;;;;OAOG;IACH,oCAJW,MAAM,mBACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,qCANW,MAAM,mBACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAehB;IAED;;;;;OAKG;IACH,oCAJW,MAAM,mBACN,MAAM,SACN,MAAM,QAYhB;IAED;;;;;;OAMG;IACH,0CALW,MAAM,mBACN,MAAM,SACN,MAAM,GACJ,MAAM,CAgBlB;IAED;;;;;OAKG;IACH,4BALW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAMhB;IAED;;;;;;;;;;OAUG;IACH,yBARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAKhB;IAED;;;;;OAKG;IACH,yBALW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAMhB;IAED;;;OAGG;IACH,yBAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;OAGG;IACH,6BAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;OAGG;IACH,gBAHW,MAAM,WACN,MAAM,QAuChB;IAED;;;OAGG;IACH,2BAFW,QAAM,UAAU,MAAM,CAAC,QA4BjC;IAED;;;;;OAKG;IACH,eAsBC;;CACJ;;;;8BAzjB6B,oDAAoD;AAgBlF;;;;GAIG;AACH,uCAFU,MAAM,CAEkB"}
+{"version":3,"file":"TubeX.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/TubeX.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAoEI;;;;;OAKG;IACH,2BAEC;IAED;;;;;OAKG;IACH,2BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,YAFa,MAAM,CAIlB;IAED;;OAEG;IACH,qBAFa,MAAM,CAIlB;IAED,uBAEC;IAED,uBAEC;IAiGD;;;OAGG;IACH,wBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,QAShB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,QAShB;IAED;;;;OAIG;IACH,wBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,QAShB;IAED;;;;;;;OAOG;IACH,oCAJW,MAAM,mBACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,qCANW,MAAM,mBACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAehB;IAED;;;;;OAKG;IACH,oCAJW,MAAM,mBACN,MAAM,SACN,MAAM,QAYhB;IAED;;;;;;OAMG;IACH,0CALW,MAAM,mBACN,MAAM,SACN,MAAM,GACJ,MAAM,CAgBlB;IAED;;;;;OAKG;IACH,4BALW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAMhB;IAED;;;;;;;;;;OAUG;IACH,yBARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAKhB;IAED;;;;;;;OAOG;IACH,yBALW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAMhB;IAED;;;OAGG;IACH,yBAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;OAGG;IACH,6BAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;OAGG;IACH,gBAHW,MAAM,WACN,MAAM,QAuChB;IAED;;;OAGG;IACH,2BAFW,QAAM,UAAU,MAAM,CAAC,QA4BjC;IAED;;;;;OAKG;IACH,eAsBC;;CACJ;;;;8BA3jB6B,oDAAoD;AAgBlF;;;;GAIG;AACH,uCAFU,MAAM,CAEkB"}

package/src/engine/graphics/trail/tube/TubeX.js

@@ -437,10 +437,12 @@ export class TubeX {
     }
 
     /**
+     * Linear colour, stored at half precision. Not limited to 0..1: values above 1 are HDR.
+     *
      * @param {number} knot_index
-     * @param {number} r 0..255
-     * @param {number} g 0..255
-     * @param {number} b 0..255
+     * @param {number} r
+     * @param {number} g
+     * @param {number} b
      */
     setKnotColor(knot_index, r, g, b) {
         assert.isNonNegativeInteger(knot_index, 'knot_index');

package/src/engine/graphics/trail/tube/tube_attributes_spec.d.ts

@@ -8,9 +8,10 @@
  * (its angular position around the ring), so the heavy per-frame work is just
  * writing the knot centre + frame to the ring's `radial+1` rows.
  *
- * Layout is floats-first then a uint8 colour triple, padded to a 4-byte multiple
+ * Layout is floats-first then a float16 colour triple, padded to a 4-byte multiple
  * so the interleaved Float32 view (stride = bytesPerRecord >> 2) stays aligned —
- * the same trick {@link ribbon_attributes_spec} relies on.
+ * the same trick {@link ribbon_attributes_spec} relies on. The colour is linear and
+ * not limited to 0..1, so a trail can be brighter than white.
  */
 export const tube_attributes_spec: RowFirstTableSpec;
 export const TUBE_ATTRIBUTE_ADDRESS_AGE: 0;

package/src/engine/graphics/trail/tube/tube_attributes_spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tube_attributes_spec.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/tube_attributes_spec.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,qDAuC4B;AAG5B,2CAA4C;AAC5C,gDAAiD;AACjD,8CAA+C;AAC/C,gDAAiD;AACjD,4CAA6C;AAC7C,6CAA8C;AAC9C,8CAA+C;AAC/C,kDAAmD;AACnD,8CAA+C;kCAlEb,wDAAwD"}
+{"version":3,"file":"tube_attributes_spec.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/tube_attributes_spec.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,qDAuC4B;AAG5B,2CAA4C;AAC5C,gDAAiD;AACjD,8CAA+C;AAC/C,gDAAiD;AACjD,4CAA6C;AAC7C,6CAA8C;AAC9C,8CAA+C;AAC/C,kDAAmD;AACnD,8CAA+C;kCAnEb,wDAAwD"}

package/src/engine/graphics/trail/tube/tube_attributes_spec.js

@@ -12,9 +12,10 @@ import { RowFirstTableSpec } from "../../../../core/collection/table/RowFirstTab
  * (its angular position around the ring), so the heavy per-frame work is just
  * writing the knot centre + frame to the ring's `radial+1` rows.
  *
- * Layout is floats-first then a uint8 colour triple, padded to a 4-byte multiple
+ * Layout is floats-first then a float16 colour triple, padded to a 4-byte multiple
  * so the interleaved Float32 view (stride = bytesPerRecord >> 2) stays aligned —
- * the same trick {@link ribbon_attributes_spec} relies on.
+ * the same trick {@link ribbon_attributes_spec} relies on. The colour is linear and
+ * not limited to 0..1, so a trail can be brighter than white.
  */
 export const tube_attributes_spec = new RowFirstTableSpec([
     // age (CPU-side bookkeeping for the simulator; NOT a GPU attribute)
@@ -47,13 +48,13 @@ export const tube_attributes_spec = new RowFirstTableSpec([
     // thickness (tube diameter; radius = thickness * 0.5)
     BinaryDataType.Float32,
 
-    // color
-    BinaryDataType.Uint8,
-    BinaryDataType.Uint8,
-    BinaryDataType.Uint8,
+    // color (linear, unbounded)
+    BinaryDataType.Float16,
+    BinaryDataType.Float16,
+    BinaryDataType.Float16,
 
-    // padding -> bytesPerRecord = 60 (divisible by 4, keeps the Float32 view aligned)
-    BinaryDataType.Uint8,
+    // padding -> bytesPerRecord = 64 (divisible by 4, keeps the Float32 view aligned)
+    BinaryDataType.Uint16,
 
 ], EndianType.LittleEndian);
 

package/src/engine/graphics3/GPUParticleEmitterSystem.d.ts

@@ -8,11 +8,12 @@
  *
  * `spawn_rate` comes from {@link ParticleEffect#effective_spawn_rate}, so an effect switched off
  * with `emitting = false` reaches the GPU as a rate of zero and keeps its authored rate to come back
- * to. Layout and program are shared by reference, never copied — two entities of one effect belong
- * on one program id in the heap.
+ * to. Layout, program and emitter layout are shared by reference, never copied — two entities of one
+ * effect belong on one program id in the heap. Transform bindings are not copied here; the system
+ * applies them on its own pass.
  *
  * Every field is compared by name, and that is load-bearing rather than style. Through a shared
- * `assign(target, field, value)` the one `target[field]` access saw all thirteen names, went
+ * `assign(target, field, value)` the one `target[field]` access saw every name, went
  * megamorphic, and read numbers back boxed, while the call boxed the value it was handed: 228 B and
  * ~120 ns per emitter per call, against nothing and ~9 ns written out like this
  * (`GPUParticleEmitterSystem.allocation.spec.js`). This runs for every live emitter twice a frame.
@@ -34,6 +35,13 @@ export function apply_particle_effect(emitter: ParticleEmitter, effect: Particle
  * @property {function():void} on_transform_changed
  * @property {string|null} url last observed {@link ParticleEffect#texture}
  * @property {import("../graphics/texture/atlas/ManagedTextureAtlas.js").ManagedAtlasReference|null} texture shared image reference, or null for an untextured effect
+ * @property {Map<string, {entity: number, channel: number, live: boolean, on_removed: function|null, layout: import("../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout|null}>} bound
+ * the transform bindings asked of the emitter, by field: `live` ones hold their entity's row in
+ * {@link context}; the others were refused or lost their entity, and wait for the request or the
+ * registry's {@link ../../shade/renderer/particles/runtime/EmitterRegistry.js EmitterRegistry#binding_layout}
+ * (`layout`, the one they were made under) to change
+ * @property {import("../../shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null} refused_program
+ * a program the particle system refused, not offered again until the effect's program changes
  */
 /**
  * Draws the game's GPU particle effects: one emitter per entity carrying
@@ -90,7 +98,7 @@ export function apply_particle_effect(emitter: ParticleEmitter, effect: Particle
  * It does not simulate anything and does not record a particle pass. `GPUParticleSystem` does both,
  * inside the renderer, driven from the emitter table these rows are in — see
  * `shade/renderer/particles/DESIGN.md`. This system's whole contribution is membership, placement,
- * the fields, and the sprite sheet.
+ * the component's fields, the global fields, the transform bindings, and the sprite sheet.
  */
 export class GPUParticleEmitterSystem extends System<any> {
     /**
@@ -146,6 +154,42 @@ export class GPUParticleEmitterSystem extends System<any> {
      * @param {number} count
      */
     burst(entity: number, count: number): void;
+    /**
+     * Set one of the scene's global fields — a member every effect may read by name, such as a gust
+     * strength — declaring it at this width if nothing has yet. The value is copied and reaches the
+     * particle system on the next frame, and again after a device restart; setting the same value
+     * again costs a comparison.
+     *
+     * Fewer values than the field is declared with set its leading components. More are refused
+     * with a warning on that frame. While the field is bound ({@link bind_global_field}) the binding
+     * overwrites it every frame, and this value is what it reads once unbound.
+     *
+     * @param {string} name
+     * @param {ArrayLike<number>} values one per component, 1..4
+     */
+    set_global_field(name: string, values: ArrayLike<number>): void;
+    /**
+     * Write an entity's composed transform into a global field every frame, on the GPU — the
+     * player's position, a light's direction. Applied on the next frame, declaring the field at the
+     * channel's width if nothing has yet. Binding a bound name replaces its binding.
+     *
+     * Refused with a warning when the entity has no Transform64 or the field is declared at another
+     * width than the channel writes; a refused binding is not retried until the request changes.
+     * The binding holds until {@link unbind_global_field}, the entity's removal, or
+     * {@link shutdown}. It is runtime state and is not saved.
+     *
+     * @param {string} name
+     * @param {number} entity an entity with a Transform64
+     * @param {number} channel a {@link ../../shade/renderer/particles/data/PARTICLE_FIELD_BINDING.js PARTICLE_FIELD_BINDING_CHANNEL}
+     */
+    bind_global_field(name: string, entity: number, channel: number): void;
+    /**
+     * Stop writing a transform into a global field, from the next frame. It reads the value last
+     * set with {@link set_global_field} again, or zero.
+     *
+     * @param {string} name
+     */
+    unbind_global_field(name: string): void;
     /** @returns {Promise<void>} */
     shutdown(): Promise<void>;
     /**
@@ -213,6 +257,23 @@ export type ParticleEmitterEntry = {
      * shared image reference, or null for an untextured effect
      */
     texture: import("../graphics/texture/atlas/ManagedTextureAtlas.js").ManagedAtlasReference | null;
+    /**
+     * the transform bindings asked of the emitter, by field: `live` ones hold their entity's row in
+     * {@link context }; the others were refused or lost their entity, and wait for the request or the
+     * registry's {@link  ../../shade/renderer/particles/runtime/EmitterRegistry.js EmitterRegistry#binding_layout}
+     * (`layout`, the one they were made under) to change
+     */
+    bound: Map<string, {
+        entity: number;
+        channel: number;
+        live: boolean;
+        on_removed: Function | null;
+        layout: import("../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout | null;
+    }>;
+    /**
+     * a program the particle system refused, not offered again until the effect's program changes
+     */
+    refused_program: import("../../shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram | null;
 };
 import { ParticleEmitter } from "../../shade/renderer/particles/runtime/ParticleEmitter.js";
 import { ParticleEffect } from "../graphics/ecs/particles/ParticleEffect.js";

package/src/engine/graphics3/GPUParticleEmitterSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUParticleEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GPUParticleEmitterSystem.js"],"names":[],"mappings":"AAywBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,+CAJW,eAAe,UACf,cAAc,GACZ,OAAO,CAiFnB;AAn1BD;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH;IAoDI;;;;;OAKG;IACH,sBALW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,gEAoB7D;IAzED,6DAA6C;IAE7C;;;OAGG;IACH,OAFU,WAAW,CAEmC;IAqExD;;;;;;OAMG;IACH,iEAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;;;;OAUG;IACH,mBAJW,MAAM,GACJ,eAAe,GAAC,IAAI,CAWhC;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,SACN,MAAM,QA4BhB;IA6BD,+BAA+B;IAC/B,YADc,QAAQ,IAAI,CAAC,CAsB1B;IAED;;;;OAIG;IACH,aAJW,cAAc,aACd,WAAW,UACX,MAAM,QAqChB;IAED;;;;OAIG;IACH,eAJW,cAAc,aACd,WAAW,UACX,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,4BAHW,MAAM,GACJ,IAAI,CAgBhB;IAoCD;;;;;;;;;;;;OAYG;IACH,eAHW,OAAO,gDAAgD,EAAE,YAAY,GACnE,IAAI,CAqChB;;CAsTJ;;YAzuBa,MAAM;;;;YACN,cAAc;;;;eACd,WAAW;;;;aACX,eAAe,GAAC,IAAI;;;;;aACpB,OAAO,+CAA+C,EAAE,eAAe,GAAC,IAAI;gCAGjE,IAAI;;;;SACf,MAAM,GAAC,IAAI;;;;aACX,OAAO,kDAAkD,EAAE,qBAAqB,GAAC,IAAI;;gCAnCnE,2DAA2D;+BAS5D,6CAA6C;uBAPrD,kBAAkB;4BAEb,iCAAiC;4BAOjC,0CAA0C"}
+{"version":3,"file":"GPUParticleEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GPUParticleEmitterSystem.js"],"names":[],"mappings":"AAopCA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,+CAJW,eAAe,UACf,cAAc,GACZ,OAAO,CAyGnB;AAtvCD;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH;IAgFI;;;;;OAKG;IACH,sBALW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,gEAoB7D;IArGD,6DAA6C;IAE7C;;;OAGG;IACH,OAFU,WAAW,CAEmC;IAiGxD;;;;;;OAMG;IACH,iEAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;;;;OAUG;IACH,mBAJW,MAAM,GACJ,eAAe,GAAC,IAAI,CAWhC;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,SACN,MAAM,QA4BhB;IAED;;;;;;;;;;;;OAYG;IACH,uBAHW,MAAM,UACN,UAAU,MAAM,CAAC,QA8B3B;IAED;;;;;;;;;;;;;OAaG;IACH,wBAJW,MAAM,UACN,MAAM,WACN,MAAM,QAOhB;IAED;;;;;OAKG;IACH,0BAFW,MAAM,QAIhB;IAyQD,+BAA+B;IAC/B,YADc,QAAQ,IAAI,CAAC,CA0C1B;IAED;;;;OAIG;IACH,aAJW,cAAc,aACd,WAAW,UACX,MAAM,QAuChB;IAED;;;;OAIG;IACH,eAJW,cAAc,aACd,WAAW,UACX,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,4BAHW,MAAM,GACJ,IAAI,CAgBhB;IAoCD;;;;;;;;;;;;OAYG;IACH,eAHW,OAAO,gDAAgD,EAAE,YAAY,GACnE,IAAI,CA4ChB;;CA0UJ;;YAnnCa,MAAM;;;;YACN,cAAc;;;;eACd,WAAW;;;;aACX,eAAe,GAAC,IAAI;;;;;aACpB,OAAO,+CAA+C,EAAE,eAAe,GAAC,IAAI;gCAGjE,IAAI;;;;SACf,MAAM,GAAC,IAAI;;;;aACX,OAAO,kDAAkD,EAAE,qBAAqB,GAAC,IAAI;;;;;;;WACrF,IAAI,MAAM,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,WAAS,IAAI,CAAC;QAAC,MAAM,EAAE,OAAO,yDAAyD,EAAE,cAAc,GAAC,IAAI,CAAA;KAAC,CAAC;;;;qBAKvL,OAAO,uDAAuD,EAAE,eAAe,GAAC,IAAI;;gCA1ClE,2DAA2D;+BAU5D,6CAA6C;uBARrD,kBAAkB;4BAEb,iCAAiC;4BAQjC,0CAA0C"}