@woosh/meep-engine 3.46.0 → 3.49.0

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

@@ -30,6 +30,14 @@
  * the program is already compared by makes the reload exact by construction rather than by an
  * engine's discretion, and it means there is one representation of the pool rather than two.
  *
+ * ## Version 2
+ *
+ * The fourth render binding is the `orientation` channel, a quaternion; in version 1 the same word
+ * was the `rotation` channel, a roll angle. A v1 save is read through
+ * {@link ./ParticleEffectSerializationUpgrader_1_2.js}, which leaves the orientation unbound: the
+ * 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.
+ *
  * ## 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;;IAEI,6BAAuB;IAGvB;;;OAGG;IACH,uCAFW,cAAc,QAmCxB;IAED;;;OAGG;IACH,yCAFW,cAAc,QA8BxB;CACJ;gDAzH+C,gEAAgE;+BACjF,qBAAqB"}
+{"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"}

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

@@ -35,6 +35,14 @@ import { ParticleEffect } from "./ParticleEffect.js";
  * the program is already compared by makes the reload exact by construction rather than by an
  * engine's discretion, and it means there is one representation of the pool rather than two.
  *
+ * ## Version 2
+ *
+ * The fourth render binding is the `orientation` channel, a quaternion; in version 1 the same word
+ * was the `rotation` channel, a roll angle. A v1 save is read through
+ * {@link ./ParticleEffectSerializationUpgrader_1_2.js}, which leaves the orientation unbound: the
+ * 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.
+ *
  * ## Nothing device-shaped is written
  *
  * There is nothing here that a device assigned: no table row, no generation, no program-heap
@@ -47,7 +55,7 @@ import { ParticleEffect } from "./ParticleEffect.js";
 export class ParticleEffectSerializationAdapter extends BinaryClassSerializationAdapter {
 
     klass = ParticleEffect;
-    version = 1;
+    version = 2;
 
     /**
      * @param {BinaryBuffer} buffer
@@ -68,7 +76,7 @@ export class ParticleEffectSerializationAdapter extends BinaryClassSerialization
         buffer.writeUint32(value.render_position);
         buffer.writeUint32(value.render_size);
         buffer.writeUint32(value.render_color);
-        buffer.writeUint32(value.render_rotation);
+        buffer.writeUint32(value.render_orientation);
         buffer.writeUint32(value.render_frame);
         buffer.writeUint32(value.render_velocity);
 
@@ -107,7 +115,7 @@ export class ParticleEffectSerializationAdapter extends BinaryClassSerialization
         value.render_position = buffer.readUint32();
         value.render_size = buffer.readUint32();
         value.render_color = buffer.readUint32();
-        value.render_rotation = buffer.readUint32();
+        value.render_orientation = buffer.readUint32();
         value.render_frame = buffer.readUint32();
         value.render_velocity = buffer.readUint32();
 

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

@@ -0,0 +1,26 @@
+/**
+ * {@link ./ParticleEffect.js ParticleEffect} version 1 to version 2: the roll channel gave way to the
+ * orientation channel.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ParticleEffectSerializationUpgrader_1_2 extends BinaryClassUpgrader {
+    /**
+     * @param {BinaryBuffer} source
+     * @param {BinaryBuffer} target
+     */
+    upgrade(source: BinaryBuffer, target: BinaryBuffer): void;
+}
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+//# sourceMappingURL=ParticleEffectSerializationUpgrader_1_2.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleEffectSerializationUpgrader_1_2.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/particles/ParticleEffectSerializationUpgrader_1_2.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH;IAII;;;OAGG;IACH,0DA+CC;CACJ;oCA3EmC,oDAAoD"}

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

@@ -0,0 +1,91 @@
+import { EMITTER_ATTRIBUTE_ABSENT } from "../../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+
+/**
+ * {@link ./ParticleEffect.js ParticleEffect} version 1 to version 2: the roll channel gave way to the
+ * orientation channel.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ParticleEffectSerializationUpgrader_1_2 extends BinaryClassUpgrader {
+    __startVersion = 1;
+    __targetVersion = 2;
+
+    /**
+     * @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
+
+        target.writeUint32(source.readUint32()); // position
+        target.writeUint32(source.readUint32()); // size
+        target.writeUint32(source.readUint32()); // color
+
+        source.readUint32(); // the roll's binding, which has no orientation to become
+        target.writeUint32(EMITTER_ATTRIBUTE_ABSENT);
+
+        target.writeUint32(source.readUint32()); // frame
+        target.writeUint32(source.readUint32()); // velocity
+
+        const present = source.readUint8();
+
+        target.writeUint8(present);
+
+        if (present !== 1) {
+            return;
+        }
+
+        // the layout: attribute count, then name, component count and semantic tag of each
+        const attribute_count = source.readUintVar();
+
+        target.writeUintVar(attribute_count);
+
+        for (let i = 0; i < attribute_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);
+    }
+}
+
+/**
+ * @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/graphics3/GPUParticleEmitterSystem.d.ts

@@ -11,6 +11,12 @@
  * to. Layout and program are shared by reference, never copied — two entities of one effect belong
  * on one program id in the heap.
  *
+ * 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
+ * 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.
+ *
  * @param {ParticleEmitter} emitter
  * @param {ParticleEffect} effect
  * @returns {boolean} whether the emitter differs from what it held before

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":"AAszBA;;;;;;;;;;;;;;;;GAgBG;AACH,+CAJW,eAAe,UACf,cAAc,GACZ,OAAO,CA4BnB;AAv0BD;;;;GAIG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH;IAoDI;;;;;OAKG;IACH,sBALW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,gEAgB7D;IArED,6DAA6C;IAE7C;;;OAGG;IACH,OAFU,YAAY,CAEO;IAiE7B;;;;;;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,CAyB1B;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;;CAiWJ;;;;;gBAxxBa,MAAM;;;;WACN,OAAO,yCAAyC,EAAE,UAAU,GAAC,IAAI;;;YAKjE,MAAM;;;;YACN,cAAc;;;;eACd,WAAW;;;;aACX,eAAe,GAAC,IAAI;;;;;aACpB,OAAO,+CAA+C,EAAE,eAAe,GAAC,IAAI;gCAGjE,IAAI;;;;SACf,MAAM,GAAC,IAAI;;;;aACX,oBAAoB,GAAC,IAAI;;gCAvCP,2DAA2D;+BAS5D,6CAA6C;uBAPrD,kBAAkB;4BAEb,iCAAiC;6BAMhC,2CAA2C"}
+{"version":3,"file":"GPUParticleEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GPUParticleEmitterSystem.js"],"names":[],"mappings":"AAszBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,+CAJW,eAAe,UACf,cAAc,GACZ,OAAO,CAiFnB;AAl4BD;;;;GAIG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH;IAoDI;;;;;OAKG;IACH,sBALW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,gEAgB7D;IArED,6DAA6C;IAE7C;;;OAGG;IACH,OAFU,YAAY,CAEO;IAiE7B;;;;;;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,CAyB1B;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;;CAiWJ;;;;;gBAxxBa,MAAM;;;;WACN,OAAO,yCAAyC,EAAE,UAAU,GAAC,IAAI;;;YAKjE,MAAM;;;;YACN,cAAc;;;;eACd,WAAW;;;;aACX,eAAe,GAAC,IAAI;;;;;aACpB,OAAO,+CAA+C,EAAE,eAAe,GAAC,IAAI;gCAGjE,IAAI;;;;SACf,MAAM,GAAC,IAAI;;;;aACX,oBAAoB,GAAC,IAAI;;gCAvCP,2DAA2D;+BAS5D,6CAA6C;uBAPrD,kBAAkB;4BAEb,iCAAiC;6BAMhC,2CAA2C"}

package/src/engine/graphics3/GPUParticleEmitterSystem.js

@@ -833,6 +833,12 @@ export class GPUParticleEmitterSystem extends System {
  * to. Layout and program are shared by reference, never copied — two entities of one effect belong
  * on one program id in the heap.
  *
+ * 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
+ * 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.
+ *
  * @param {ParticleEmitter} emitter
  * @param {ParticleEffect} effect
  * @returns {boolean} whether the emitter differs from what it held before
@@ -840,45 +846,82 @@ export class GPUParticleEmitterSystem extends System {
 export function apply_particle_effect(emitter, effect) {
     let changed = false;
 
-    changed = assign(emitter, "layout", effect.layout) || changed;
-    changed = assign(emitter, "program", effect.program) || changed;
-    changed = assign(emitter, "texture", effect.texture) || changed;
-    changed = assign(emitter, "seed", effect.seed) || changed;
-    changed = assign(emitter, "spawn_rate", effect.effective_spawn_rate) || changed;
-    changed = assign(emitter, "prewarm", effect.prewarm) || changed;
-    changed = assign(emitter, "flags", effect.flags) || changed;
-    changed = assign(emitter, "render_position", effect.render_position) || changed;
-    changed = assign(emitter, "render_size", effect.render_size) || changed;
-    changed = assign(emitter, "render_color", effect.render_color) || changed;
-    changed = assign(emitter, "render_rotation", effect.render_rotation) || changed;
-    changed = assign(emitter, "render_frame", effect.render_frame) || changed;
-    changed = assign(emitter, "render_velocity", effect.render_velocity) || changed;
+    if (emitter.layout !== effect.layout) {
+        emitter.layout = effect.layout;
+        changed = true;
+    }
 
-    const flipbook = emitter.flipbook;
+    if (emitter.program !== effect.program) {
+        emitter.program = effect.program;
+        changed = true;
+    }
 
-    if (flipbook[0] !== effect.flipbook[0] || flipbook[1] !== effect.flipbook[1]) {
-        flipbook.set(effect.flipbook);
+    if (emitter.texture !== effect.texture) {
+        emitter.texture = effect.texture;
+        changed = true;
+    }
 
+    if (emitter.seed !== effect.seed) {
+        emitter.seed = effect.seed;
         changed = true;
     }
 
-    return changed;
-}
+    const spawn_rate = effect.effective_spawn_rate;
 
-/**
- * @param {object} target
- * @param {string} field
- * @param {*} value
- * @returns {boolean} whether the field held something else
- */
-function assign(target, field, value) {
-    if (target[field] === value) {
-        return false;
+    if (emitter.spawn_rate !== spawn_rate) {
+        emitter.spawn_rate = spawn_rate;
+        changed = true;
+    }
+
+    if (emitter.prewarm !== effect.prewarm) {
+        emitter.prewarm = effect.prewarm;
+        changed = true;
     }
 
-    target[field] = value;
+    if (emitter.flags !== effect.flags) {
+        emitter.flags = effect.flags;
+        changed = true;
+    }
+
+    if (emitter.render_position !== effect.render_position) {
+        emitter.render_position = effect.render_position;
+        changed = true;
+    }
 
-    return true;
+    if (emitter.render_size !== effect.render_size) {
+        emitter.render_size = effect.render_size;
+        changed = true;
+    }
+
+    if (emitter.render_color !== effect.render_color) {
+        emitter.render_color = effect.render_color;
+        changed = true;
+    }
+
+    if (emitter.render_orientation !== effect.render_orientation) {
+        emitter.render_orientation = effect.render_orientation;
+        changed = true;
+    }
+
+    if (emitter.render_frame !== effect.render_frame) {
+        emitter.render_frame = effect.render_frame;
+        changed = true;
+    }
+
+    if (emitter.render_velocity !== effect.render_velocity) {
+        emitter.render_velocity = effect.render_velocity;
+        changed = true;
+    }
+
+    const flipbook = emitter.flipbook;
+
+    if (flipbook[0] !== effect.flipbook[0] || flipbook[1] !== effect.flipbook[1]) {
+        flipbook.set(effect.flipbook);
+
+        changed = true;
+    }
+
+    return changed;
 }
 
 class GPUParticleAtlasExtension extends RenderExtension {

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

@@ -1 +1 @@
-{"version":3,"file":"GraphicsEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GraphicsEngine.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH;IACI;;;;;OAKG;IACH,gCAEC;IAUD;;;;OAIG;IACH,yBAEC;IAmEG;;;;;;OAMG;IACH,QAFU,kBAAkB,CAEsB;IAElD;QACI;;;;;;;;WAQG;mBADO,MAAM;QAIhB;;;;;WAKG;oBADO,MAAM;QAIhB;;;;WAIG;qBADO,MAAM;QAIhB;;;;;;;WAOG;;QAGH;;;;;WAKG;;MAEN;IAID;;;;;OAKG;IACH,4BAFU,OAAO,CAEyB;IAE1C;;;;;;OAMG;IACH,UAFU,SAAS,CAEY;IAG/B;;OAEG;IACH,YAFU,iBAAiB,GAAC,IAAI,CAEV;IAEtB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;OAEG;IACH,YAFU,MAAM,CAEG;IAoBvB;;;;;;;;;;;;OAYG;IACH,mDAEC;IAED;;;;;;;;OAQG;IACH,iBAFW,KAAK,QAoBf;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFW,YAAY,QAStB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,yBAHW,eAAe,GACb,eAAe,CAa3B;IAED;;;;;;;;;;OAUG;IACH,uBAHW,UAAU,GACR,MAAM,CAclB;IAED;;;;;;OAMG;IACH,4BAHW,eAAe,GACb,OAAO,CAgBnB;IAED;;;;;;;;;;;;;OAaG;IACH,kCAHW,iBAAiB,GACf,iBAAiB,CAqB7B;IAED;;;;;;OAMG;IACH,8BAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,qCAHW,iBAAiB,GACf,OAAO,CAgBnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,qBALW,KAAK,GACH,eAAe,GAAC,IAAI,CAehC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,yBARW,KAAK,UACL,MAAM,SACN,MAAM,UACN,MAAM,GACJ,QAAQ,SAAS,CAAC,CAwD9B;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;;;;;;;OAUG;IACH,SAFa,QAAQ,IAAI,CAAC,CAuDzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAFW,iBAAiB,QAc3B;IAED;;;;;OAKG;IACH,aAiBC;IASD;;;;;;;;OAQG;IACH,8BAHW,OAAO,GAAC,OAAO,UACf,OAAO,GAAC,OAAO,QAQzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,yBALW,MAAM,KACN,MAAM,UACN,OAAO,aACP,OAAO,QAIjB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mBAyBC;IAED;;;;;;;;;OASG;IACH,4BAPW,MAAM,GAKJ,OAAO,CAoDnB;;CACJ;sBAt4BY,OAAO,4BAA4B,EAAE,OAAO;yBAC5C,OAAO,8CAA8C,EAAE,UAAU;8BACjE,OAAO,mDAAmD,EAAE,eAAe;gCAC3E,OAAO,mEAAmE,EAAE,iBAAiB;8BAC7F,OAAO,+CAA+C,EAAE,eAAe;2BACvE,OAAO,8CAA8C,EAAE,YAAY;qBACnE,OAAO,kCAAkC,EAAE,MAAM;yBAfrC,kCAAkC;mCAMxB,yBAAyB;mBAZzC,oCAAoC;wBAC/B,4BAA4B;sBAQ9B,kCAAkC;yCAJf,kDAAkD;sBAErE,qCAAqC;0BACjC,0CAA0C"}
+{"version":3,"file":"GraphicsEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GraphicsEngine.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH;IACI;;;;;OAKG;IACH,gCAEC;IAUD;;;;OAIG;IACH,yBAEC;IAmEG;;;;;;OAMG;IACH,QAFU,kBAAkB,CAEsB;IAElD;QACI;;;;;;;;WAQG;mBADO,MAAM;QAIhB;;;;;WAKG;oBADO,MAAM;QAIhB;;;;WAIG;qBADO,MAAM;QAIhB;;;;;;;WAOG;;QAGH;;;;;WAKG;;MAEN;IAID;;;;;OAKG;IACH,4BAFU,OAAO,CAEyB;IAE1C;;;;;;OAMG;IACH,UAFU,SAAS,CAEY;IAG/B;;OAEG;IACH,YAFU,iBAAiB,GAAC,IAAI,CAEV;IAEtB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;OAEG;IACH,YAFU,MAAM,CAEG;IAoBvB;;;;;;;;;;;;OAYG;IACH,mDAEC;IAED;;;;;;;;OAQG;IACH,iBAFW,KAAK,QAoBf;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFW,YAAY,QAStB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,yBAHW,eAAe,GACb,eAAe,CAa3B;IAED;;;;;;;;;;OAUG;IACH,uBAHW,UAAU,GACR,MAAM,CAclB;IAED;;;;;;OAMG;IACH,4BAHW,eAAe,GACb,OAAO,CAgBnB;IAED;;;;;;;;;;;;;OAaG;IACH,kCAHW,iBAAiB,GACf,iBAAiB,CAqB7B;IAED;;;;;;OAMG;IACH,8BAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,qCAHW,iBAAiB,GACf,OAAO,CAgBnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,qBALW,KAAK,GACH,eAAe,GAAC,IAAI,CAehC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,yBARW,KAAK,UACL,MAAM,SACN,MAAM,UACN,MAAM,GACJ,QAAQ,SAAS,CAAC,CAwD9B;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;;;;;;;OAUG;IACH,SAFa,QAAQ,IAAI,CAAC,CAuDzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAFW,iBAAiB,QAc3B;IAED;;;;;OAKG;IACH,aAiBC;IASD;;;;;;;;OAQG;IACH,8BAHW,OAAO,GAAC,OAAO,UACf,OAAO,GAAC,OAAO,QAQzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,yBALW,MAAM,KACN,MAAM,UACN,OAAO,aACP,OAAO,QAIjB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mBAyBC;IAED;;;;;;;;;OASG;IACH,4BAPW,MAAM,GAKJ,OAAO,CA2DnB;;CACJ;sBA74BY,OAAO,4BAA4B,EAAE,OAAO;yBAC5C,OAAO,8CAA8C,EAAE,UAAU;8BACjE,OAAO,mDAAmD,EAAE,eAAe;gCAC3E,OAAO,mEAAmE,EAAE,iBAAiB;8BAC7F,OAAO,+CAA+C,EAAE,eAAe;2BACvE,OAAO,8CAA8C,EAAE,YAAY;qBACnE,OAAO,kCAAkC,EAAE,MAAM;yBAfrC,kCAAkC;mCAMxB,yBAAyB;mBAZzC,oCAAoC;wBAC/B,4BAA4B;sBAQ9B,kCAAkC;yCAJf,kDAAkD;sBAErE,qCAAqC;0BACjC,0CAA0C"}

package/src/engine/graphics3/GraphicsEngine.js

@@ -910,7 +910,14 @@ export class GraphicsEngine {
         const submitted = renderer.render(this.#camera, this.#scene, time_delta_seconds);
 
         this.frameIndex++;
-        this.needDraw = false;
+
+        if (submitted) {
+            // A frame the renderer held back — its pipelines still compiling, or no device — showed
+            // nothing new, so `needDraw` stays set and the next frame tries again, as it does for an
+            // empty viewport above. On-demand rendering would otherwise wait for a change that may
+            // never come.
+            this.needDraw = false;
+        }
 
         this.on.postRender.dispatch();
 

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

@@ -1,3 +1,28 @@
+/**
+ * Uniform: the noise is off, and not evaluated.
+ * @type {number}
+ */
+export const DEFAULT_NOISE_STRENGTH: number;
+/**
+ * Metres per repeat of the tile.
+ * @type {number}
+ */
+export const DEFAULT_NOISE_SCALE: number;
+/**
+ * Tile units the warp may displace by.
+ * @type {number}
+ */
+export const DEFAULT_NOISE_WARP: number;
+/**
+ * All of the scene's wind.
+ * @type {number}
+ */
+export const DEFAULT_NOISE_WIND_FACTOR: number;
+/**
+ * The engine's tile.
+ * @type {number}
+ */
+export const DEFAULT_NOISE_TEXTURE: number;
 /**
  * A box of fog, smoke, dust or cloud that an entity carries around.
  *
@@ -53,6 +78,46 @@ export class ParticipatingMedia {
      * @type {number}
      */
     fade_distance: number;
+    /**
+     * Noise on the density, [0, 1]: how far the medium goes from uniform toward the tile's value.
+     * 0 is a uniform medium and costs nothing; 1 is the tile as it is.
+     *
+     * The tile is a slot of the scene's noise atlas ({@link noise_texture}), sampled in world space
+     * and repeating every {@link noise_scale} metres, scrolled by the scene's wind and the medium's
+     * own {@link noise_velocity}, and warped by a second, slower tap of the same tile so the field
+     * changes shape as it moves. See `VOLUMETRIC_NOISE_PLAN_2026_10_15.md`.
+     *
+     * @type {number}
+     */
+    noise_strength: number;
+    /**
+     * World size of one repeat of the tile, in metres. The engine's tile holds four base features
+     * an edge, so 32 puts them 8 m apart.
+     * @type {number}
+     */
+    noise_scale: number;
+    /**
+     * How far the warp tap may displace the lookup, in tile units. 0 is one tap and a field that
+     * only slides.
+     * @type {number}
+     */
+    noise_warp: number;
+    /**
+     * The medium's own motion for the noise, metres a second along the world axes, added to the
+     * scene's wind — a draught in a corridor the wind does not reach.
+     * @type {number[]}
+     */
+    noise_velocity: number[];
+    /**
+     * How much of the scene's wind this medium feels. 1 is all of it, 0 is none.
+     * @type {number}
+     */
+    noise_wind_factor: number;
+    /**
+     * Which tile: a slot of the scene's noise atlas. 0 is the one the engine bakes.
+     * @type {number}
+     */
+    noise_texture: number;
     /**
      * @param {number} value
      */
@@ -80,6 +145,12 @@ export class ParticipatingMedia {
             radius: number;
             g: number;
         };
+        noise_strength: number;
+        noise_scale: number;
+        noise_warp: number;
+        noise_velocity: number[];
+        noise_wind_factor: number;
+        noise_texture: number;
     };
     /**
      * @param {Object} options
@@ -88,11 +159,23 @@ export class ParticipatingMedia {
      * @param {object} [options.particle_spec] omitted resets the medium to fog rather than leaving whatever
      * the component already held — a load has to determine the whole component, or an instance being
      * reused would carry the previous level's particle into the next one
+     * @param {number} [options.noise_strength] every noise field omitted is its default, for the same reason
+     * @param {number} [options.noise_scale]
+     * @param {number} [options.noise_warp]
+     * @param {number[]} [options.noise_velocity]
+     * @param {number} [options.noise_wind_factor]
+     * @param {number} [options.noise_texture]
      */
-    fromJSON({ density, fade_distance, particle_spec }: {
+    fromJSON({ density, fade_distance, particle_spec, noise_strength, noise_scale, noise_warp, noise_velocity, noise_wind_factor, noise_texture, }: {
         density?: number;
         fade_distance?: number;
         particle_spec?: object;
+        noise_strength?: number;
+        noise_scale?: number;
+        noise_warp?: number;
+        noise_velocity?: number[];
+        noise_wind_factor?: number;
+        noise_texture?: number;
     }): void;
     /**
      * **The cross-sections and the radius are left out of this on purpose.** They run to 1e-16 and

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

@@ -1 +1 @@
-{"version":3,"file":"ParticipatingMedia.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMedia.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAyEI;;;OAGG;IACH,4BAFa,kBAAkB,CAQ9B;IAjFD;;;;;;;;OAQG;IACH,SAFU,MAAM,CAEU;IAE1B;;;;;;;;OAQG;IACH,eAFU,uBAAuB,CAE8C;IAE/E;;;;;;;;OAQG;IACH,eAFU,MAAM,CAEsB;IAmBtC;;OAEG;IACH,qCAgBC;IApCD;;;;;;;;;;;;OAYG;IACH,gCAEC;IAmCD;;;;;;;;;MAaC;IAED;;;;;;;OAOG;IACH;QAN4B,OAAO,GAAxB,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,aAAa,GAA9B,MAAM;aAyBhB;IAED;;;;;;;OAOG;IACH,QAFa,MAAM,CAUlB;IAED;;;OAGG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAMnB;CACJ;;kBAIS,MAAM;;wCAlMT,8DAA8D"}
+{"version":3,"file":"ParticipatingMedia.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMedia.js"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;GAGG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;GAGG;AACH,iCAFU,MAAM,CAEsB;AAEtC;;;GAGG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;GAGG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAuHI;;;OAGG;IACH,4BAFa,kBAAkB,CAQ9B;IA/HD;;;;;;;;OAQG;IACH,SAFU,MAAM,CAEU;IAE1B;;;;;;;;OAQG;IACH,eAFU,uBAAuB,CAE8C;IAE/E;;;;;;;;OAQG;IACH,eAFU,MAAM,CAEsB;IAEtC;;;;;;;;;;OAUG;IACH,gBAFU,MAAM,CAEwB;IAExC;;;;OAIG;IACH,aAFU,MAAM,CAEkB;IAElC;;;;OAIG;IACH,YAFU,MAAM,CAEgB;IAEhC;;;;OAIG;IACH,gBAFU,MAAM,EAAE,CAES;IAE3B;;;OAGG;IACH,mBAFU,MAAM,CAE8B;IAE9C;;;OAGG;IACH,eAFU,MAAM,CAEsB;IAmBtC;;OAEG;IACH,qCAgBC;IApCD;;;;;;;;;;;;OAYG;IACH,gCAEC;IAmCD;;;;;;;;;;;;;;;MAmBC;IAED;;;;;;;;;;;;;OAaG;IACH;QAZ4B,OAAO,GAAxB,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,aAAa,GAA9B,MAAM;QAGW,cAAc,GAA/B,MAAM;QACW,WAAW,GAA5B,MAAM;QACW,UAAU,GAA3B,MAAM;QACa,cAAc,GAAjC,MAAM,EAAE;QACS,iBAAiB,GAAlC,MAAM;QACW,aAAa,GAA9B,MAAM;aAkDhB;IAED;;;;;;;OAOG;IACH,QAFa,MAAM,CAsBlB;IAED;;;OAGG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAYnB;CACJ;;kBAIS,MAAM;;wCAvUT,8DAA8D"}