@woosh/meep-engine 3.68.0 → 3.70.0

package/src/engine/graphics3/GPUFluidSystem.js

@@ -27,6 +27,7 @@ import {
 } from "../physics/fluid/ecs/GPUFluidComponent.js";
 import { fluid_effector_record_create } from "../physics/fluid/effector/record/fluid_effector_record_create.js";
 import { FLUID_ATMOSPHERE_WORDS, FluidAtmosphere } from "../physics/fluid/FluidAtmosphere.js";
+import { fluid_atmosphere_velocity_at } from "../physics/fluid/turbulence/fluid_atmosphere_velocity_at.js";
 import { fluid_obstacle_record_create } from "../physics/fluid/obstacle/fluid_obstacle_record_create.js";
 import {
     FLUID_OBSTACLE_PLANES_CHANGED,
@@ -154,6 +155,20 @@ class ObstacleEntry {
     held = false;
 }
 
+/**
+ * Point `i` of `n` along an axis of a request's box: `mix(min, max, i / (n − 1))`, or `min` for one
+ * point, as the device's gather places it.
+ *
+ * @param {number} min
+ * @param {number} max
+ * @param {number} i
+ * @param {number} n
+ * @returns {number}
+ */
+function request_axis_point(min, max, i, n) {
+    return n > 1 ? min + (max - min) * (i / (n - 1)) : min;
+}
+
 /**
  * # The GPU wind fluid of a scene
  *
@@ -172,11 +187,12 @@ class ObstacleEntry {
  * new Entity().add(new Transform64()).add(new GPUFluidComponent()).build(dataset);
  * ```
  *
- * ## The CPU half: {@link far_field}
+ * ## The CPU half: {@link far_field} and {@link far_field_at}
  *
  * The far field in m/s, synchronously, from {@link FluidEffectorsSystem}'s fold: deterministic, the
  * same headless as on a device, and still air with no `FluidEffectorsSystem`. Gameplay reads this,
- * never the fluid (§6).
+ * never the fluid (§6). `far_field` is its mean; `far_field_at` is the far field at a point, its
+ * turbulence included, as every GPU reader of the wind field takes it beyond the cascades.
  *
  * ## The CPU half: {@link request}, a lattice of the wind, asynchronously
  *
@@ -198,8 +214,8 @@ class ObstacleEntry {
  *   most 4 batches (a frame's requests each) in flight; a frame's requests past that are dropped,
  *   with the status. Measured latency: see the proposal (§12). Rows are freed after delivery or a
  *   drop. A device restart drops what was in flight; requests not yet recorded go to the new device.
- * - **Headless** (no scene context at the update): answered from {@link far_field} at the next
- *   {@link update}, every point the far field.
+ * - **Headless** (no scene context at the update): answered from {@link far_field_at} at the next
+ *   {@link update}, every point the far field there.
  *
  * At steady state nothing is allocated per request.
  *
@@ -370,6 +386,15 @@ export class GPUFluidSystem extends System {
     #bounds = new Float64Array(6);
     #far = new Float64Array(3);
 
+    /** The turbulence `σ` last written into the wind field with no domain. */
+    #wind_sigma = 0;
+
+    /** Scratch for an atmosphere's turbulence offset. */
+    #turbulence_offset = new Float64Array(3);
+
+    /** The atmosphere a tick steps against, its turbulence carried back to the tick. */
+    #tick_atmosphere = new Float64Array(FLUID_ATMOSPHERE_WORDS);
+
     /*
      The read API: per handle, the request's box and counts, its target, and its status.
     */
@@ -478,6 +503,21 @@ export class GPUFluidSystem extends System {
         out[2] = atmosphere[FluidAtmosphere.VELOCITY_Z];
     }
 
+    /**
+     * The far field now at a world point, m/s: its mean plus its turbulence there, `u + σ·T((x − o) ⊙ S⁻¹)`,
+     * as every GPU reader of the wind field takes it where no cascade holds the point
+     * (`fluid_atmosphere_velocity_at`). Synchronous and deterministic, with or without a device; the mean
+     * alone ({@link far_field}) with no turbulence. Allocates nothing once the turbulence tile exists.
+     *
+     * @param {Float64Array|Float32Array|number[]} out receives `[x, y, z]`
+     * @param {number} x world metres
+     * @param {number} y
+     * @param {number} z
+     */
+    far_field_at(out, x, y, z) {
+        fluid_atmosphere_velocity_at(out, this.#read_atmosphere(), 0, x, y, z);
+    }
+
     /**
      * What became of each request, by handle: a `GPUReadbackStatus`. `Pending` from {@link request}
      * until the apply point ({@link update}) that answers it, `Delivered` (the lattice is in its
@@ -646,26 +686,38 @@ export class GPUFluidSystem extends System {
             return;
         }
 
-        // headless: every point the far field
+        // headless: every point the far field there, at the points the device would gather
         const far = this.#far;
-
-        this.far_field(far);
+        const atmosphere = this.#read_atmosphere();
 
         const asked = this.#asked;
         const counts = this.#request_counts;
+        const box = this.#request_box;
 
         for (let i = 0; i < this.#asked_count; i++) {
             const h = asked[i];
             const target = this.#request_targets[h];
-            const points = counts[3 * h] * counts[3 * h + 1] * counts[3 * h + 2];
+            const nx = counts[3 * h], ny = counts[3 * h + 1], nz = counts[3 * h + 2];
 
             let at = this.#request_offsets[h];
 
-            for (let p = 0; p < points; p++, at += FLUID_QUERY_SAMPLE_FLOATS) {
-                target[at] = far[0];
-                target[at + 1] = far[1];
-                target[at + 2] = far[2];
-                target[at + 3] = 0;
+            for (let k = 0; k < nz; k++) {
+                const z = request_axis_point(box[6 * h + 2], box[6 * h + 5], k, nz);
+
+                for (let j = 0; j < ny; j++) {
+                    const y = request_axis_point(box[6 * h + 1], box[6 * h + 4], j, ny);
+
+                    for (let p = 0; p < nx; p++, at += FLUID_QUERY_SAMPLE_FLOATS) {
+                        const x = request_axis_point(box[6 * h], box[6 * h + 3], p, nx);
+
+                        fluid_atmosphere_velocity_at(far, atmosphere, 0, x, y, z);
+
+                        target[at] = far[0];
+                        target[at + 1] = far[1];
+                        target[at + 2] = far[2];
+                        target[at + 3] = 0;
+                    }
+                }
             }
 
             this.#settle(h, GPUReadbackStatus.Delivered);
@@ -740,6 +792,22 @@ export class GPUFluidSystem extends System {
         this.#queries = null;
     }
 
+    /**
+     * The turbulence's offset in an atmosphere record, into {@link #turbulence_offset}.
+     *
+     * @param {Float64Array} atmosphere
+     * @returns {Float64Array}
+     */
+    #read_turbulence_offset(atmosphere) {
+        const out = this.#turbulence_offset;
+
+        out[0] = atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_X];
+        out[1] = atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_Y];
+        out[2] = atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_Z];
+
+        return out;
+    }
+
     /**
      * The far field and its terms, into {@link #atmosphere}; still air at time 0 with no effectors
      * system.
@@ -1556,16 +1624,39 @@ export class GPUFluidSystem extends System {
             anchor[1] = transform.translation_y;
             anchor[2] = transform.translation_z;
 
+            const wind = context.wind;
+            const sigma = atmosphere[FluidAtmosphere.TURBULENCE_SIGMA];
+
+            // the tile, before any pass binds it
+            if (sigma !== 0) {
+                this.#read_turbulence_offset(atmosphere);
+                wind.set_turbulence(sigma, this.#turbulence_offset, atmosphere[FluidAtmosphere.TURBULENCE_LENGTH]);
+            }
+
+            const tick_atmosphere = this.#tick_atmosphere;
+            tick_atmosphere.set(atmosphere);
+
             for (let tick = first_tick; tick <= tick_now; tick++) {
+                // every tick steps against the far field at the end of the frame's last, its eddies
+                // carried back by the mean to where the tick left them, so a frame of several ticks
+                // advances them as one tick at a time does
+                const behind = (tick_now - tick) * dt;
+
+                tick_atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_X] = atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_X] - atmosphere[FluidAtmosphere.VELOCITY_X] * behind;
+                tick_atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_Y] = atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_Y] - atmosphere[FluidAtmosphere.VELOCITY_Y] * behind;
+                tick_atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_Z] = atmosphere[FluidAtmosphere.TURBULENCE_OFFSET_Z] - atmosphere[FluidAtmosphere.VELOCITY_Z] * behind;
+
                 stack.record_tick({
                     graph,
                     tick,
                     dt,
                     anchor,
-                    atmosphere,
+                    atmosphere: tick_atmosphere,
                     atmosphere_offset: 0,
                     forcing: this.#forcing,
                     vorticity_confinement: domain.component.vorticity_confinement,
+                    // always the wind's: a cascade may still hold turbulence the far field has let go of
+                    turbulence: wind.turbulence,
                 });
             }
         }
@@ -1583,25 +1674,31 @@ export class GPUFluidSystem extends System {
     }
 
     /**
-     * With no domain, the wind field is the far field alone: written when it changes.
+     * With no domain, the wind field is the far field alone: written when it changes, which with
+     * turbulence is every frame, the mean carrying the eddies.
      *
      * @param {GPUSceneContext} context
      */
     #publish_far_field(context) {
         const far = this.#far;
         const written = this.#wind_far;
+        const atmosphere = this.#read_atmosphere();
+        const sigma = atmosphere[FluidAtmosphere.TURBULENCE_SIGMA];
 
         this.far_field(far);
 
-        if (far[0] === written[0] && far[1] === written[1] && far[2] === written[2]) {
+        if (far[0] === written[0] && far[1] === written[1] && far[2] === written[2] && sigma === 0 && this.#wind_sigma === 0) {
             return;
         }
 
         const wind = context.wind;
 
         wind.set_far_velocity(far);
+        wind.set_turbulence(sigma, this.#read_turbulence_offset(atmosphere), atmosphere[FluidAtmosphere.TURBULENCE_LENGTH]);
         wind.update();
 
+        this.#wind_sigma = sigma;
+
         written[0] = far[0];
         written[1] = far[1];
         written[2] = far[2];

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

@@ -32,7 +32,7 @@ export function apply_particle_effect(emitter: ParticleEmitter, effect: Particle
  * @property {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null} context
  * the scene context the emitter is registered with, at the entity's row; null until a frame has
  * registered it, or after a device restart took that context away
- * @property {function():void} on_transform_changed
+ * @property {EntityRowHold} hold the entity's row, held in {@link context} while the emitter is registered
  * @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
@@ -248,7 +248,10 @@ export type ParticleEmitterEntry = {
      * registered it, or after a device restart took that context away
      */
     context: import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext | null;
-    on_transform_changed: () => void;
+    /**
+     * the entity's row, held in {@link context } while the emitter is registered
+     */
+    hold: EntityRowHold;
     /**
      * last observed {@link ParticleEffecttexture }
      */
@@ -280,4 +283,5 @@ import { ParticleEffect } from "../graphics/ecs/particles/ParticleEffect.js";
 import { System } from "../ecs/System.js";
 import { Transform64 } from "../ecs/transform/Transform64.js";
 import { SpriteAtlas } from "../graphics/texture/atlas/SpriteAtlas.js";
+import { EntityRowHold } from "./EntityRowHold.js";
 //# sourceMappingURL=GPUParticleEmitterSystem.d.ts.map

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":"AA6tCA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,+CAJW,eAAe,UACf,cAAc,GACZ,OAAO,CAyGnB;AA1zCD;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH;IA4FI;;;;;OAKG;IACH,sBALW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,gEAoB7D;IAjHD,6DAA6C;IAE7C;;;OAGG;IACH,OAFU,WAAW,CAEkC;IA6GvD;;;;;;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;IA8PD,+BAA+B;IAC/B,YADc,QAAQ,IAAI,CAAC,CAuB1B;IA0ED;;;;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,CAgDhB;;CAoVJ;;YAvrCa,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;;gCA/ClE,2DAA2D;+BAU5D,6CAA6C;uBARrD,kBAAkB;4BAEb,iCAAiC;4BAQjC,0CAA0C"}
+{"version":3,"file":"GPUParticleEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GPUParticleEmitterSystem.js"],"names":[],"mappings":"AA4rCA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,+CAJW,eAAe,UACf,cAAc,GACZ,OAAO,CAyGnB;AAzxCD;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH;IA4FI;;;;;OAKG;IACH,sBALW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,gEAoB7D;IAjHD,6DAA6C;IAE7C;;;OAGG;IACH,OAFU,WAAW,CAEkC;IA6GvD;;;;;;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;IA8PD,+BAA+B;IAC/B,YADc,QAAQ,IAAI,CAAC,CAuB1B;IA0ED;;;;OAIG;IACH,aAJW,cAAc,aACd,WAAW,UACX,MAAM,QA6BhB;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,CAgDhB;;CA6TJ;;YAtpCa,MAAM;;;;YACN,cAAc;;;;eACd,WAAW;;;;aACX,eAAe,GAAC,IAAI;;;;;aACpB,OAAO,+CAA+C,EAAE,eAAe,GAAC,IAAI;;;;UAG5E,aAAa;;;;SACb,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;;gCA/ClE,2DAA2D;+BAU5D,6CAA6C;uBARrD,kBAAkB;4BAGb,iCAAiC;4BAOjC,0CAA0C;8BATxC,oBAAoB"}

package/src/engine/graphics3/GPUParticleEmitterSystem.js

@@ -5,10 +5,10 @@ import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.
 import { ParticleEmitter } from "../../shade/renderer/particles/runtime/ParticleEmitter.js";
 import { GPUTextureContext } from "../../shade/renderer/texture/GPUTextureContext.js";
 import { System } from "../ecs/System.js";
+import { EntityRowHold } from "./EntityRowHold.js";
 import Name from "../ecs/name/Name.js";
 import { Transform64 } from "../ecs/transform/Transform64.js";
 import { EventType } from "../ecs/EventType.js";
-import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
 import { row_of_entity } from "../../shade/renderer/scene/rows/GPUSceneRows.js";
 import { GameAssetType } from "../asset/GameAssetType.js";
 import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
@@ -41,7 +41,7 @@ const BURST_QUEUE_LIMIT = 256;
  * @property {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null} context
  * the scene context the emitter is registered with, at the entity's row; null until a frame has
  * registered it, or after a device restart took that context away
- * @property {function():void} on_transform_changed
+ * @property {EntityRowHold} hold the entity's row, held in {@link context} while the emitter is registered
  * @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
@@ -744,7 +744,7 @@ export class GPUParticleEmitterSystem extends System {
             transform,
             emitter: null,
             context: null,
-            on_transform_changed: null,
+            hold: null,
             url: null,
             texture: null,
             bound: new Map(),
@@ -753,18 +753,8 @@ export class GPUParticleEmitterSystem extends System {
 
         this.#entries.set(entity, entry);
 
-        /*
-         The emitter is placed the moment its transform moves rather than on a poll. A Transform64
-         has no signals of its own, so the announcement comes from the dataset: whoever wrote the
-         transform sends TRANSFORM64_EVENT_CHANGE and this wakes on it. Coarser than watching
-         position, rotation and scale separately — a scale write wakes a placement that reads the
-         whole transform anyway — and that is the trade the type makes everywhere.
-        */
-        entry.on_transform_changed = () => this.#place(entry);
-
-        this.#dataset.addEntityEventListener(
-            entity, TRANSFORM64_EVENT_CHANGE, entry.on_transform_changed
-        );
+        // The emitter is placed the moment its transform moves rather than on a poll: see EntityRowHold.
+        entry.hold = new EntityRowHold(this.#dataset, entity, () => this.#graphics.scene_context(this.#scene));
 
         // Everything else — building the emitter, acquiring the texture — is what a frame does
         // anyway, and doing it here as well would be a second copy of it that has to stay in step.
@@ -916,14 +906,12 @@ export class GPUParticleEmitterSystem extends System {
      * @param {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} scene_context
      */
     #register(particles, scene_context) {
-        const rows = scene_context.rows;
-
         for (const entry of this.#entries.values()) {
             if (entry.emitter === null || entry.context === scene_context || entry.emitter.program === entry.refused_program) {
                 continue;
             }
 
-            rows.acquire(entry.entity);
+            entry.hold.acquire(scene_context);
 
             try {
                 particles.add_emitter(entry.emitter, row_of_entity(entry.entity));
@@ -931,7 +919,7 @@ export class GPUParticleEmitterSystem extends System {
                 // The program's global imports do not link against the scene's global fields. One
                 // effect must not stop every other one: it is reported, and not tried again until
                 // its program changes.
-                rows.release(entry.entity);
+                entry.hold.release();
                 entry.refused_program = entry.emitter.program;
                 warn_limited(`GPUParticleEmitterSystem: an effect was refused: ${e.message}`);
                 continue;
@@ -1073,21 +1061,6 @@ export class GPUParticleEmitterSystem extends System {
         }
     }
 
-    /**
-     * The entity moved: its row is rewritten from its transform by the context that holds it.
-     *
-     * @param {ParticleEmitterEntry} entry
-     */
-    #place(entry) {
-        const context = entry.context;
-
-        if (context === null || context !== this.#graphics.scene_context(this.#scene)) {
-            return;
-        }
-
-        context.rows.mark_world(entry.entity);
-    }
-
     /**
      * Retire an entity's emitter and let go of its row, leaving the entry linked.
      *
@@ -1111,14 +1084,15 @@ export class GPUParticleEmitterSystem extends System {
                 particles.remove_emitter(emitter);
             }
 
-            context.rows.release(entry.entity);
-
             // the registry dropped the bindings with the emitter; the rows they held go too
             for (const binding of entry.bound.values()) {
                 this.#let_go(context, binding);
             }
         }
 
+        // a hold in a context that has been replaced went with it, and releasing it gives nothing back
+        entry.hold.release();
+
         entry.context = null;
         this.#forget_bindings(entry);
 
@@ -1137,15 +1111,8 @@ export class GPUParticleEmitterSystem extends System {
             return;
         }
 
-        if (entry.on_transform_changed !== null) {
-            this.#dataset.removeEntityEventListener(
-                entity, TRANSFORM64_EVENT_CHANGE, entry.on_transform_changed
-            );
-
-            entry.on_transform_changed = null;
-        }
-
         this.#detach_emitter(entry);
+        entry.hold.dispose();
         entry.texture?.release();
 
         entry.url = null;

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

@@ -1,48 +1,43 @@
 /**
- * Draws {@link Trail3D}'s tubes under Shade, as dynamic geometry inside the transparency pipeline.
+ * Copy a component onto runtime parameters.
  *
- * **A trail is dynamic content by definition** — every knot of it is rewritten as the entity moves
- * and every knot's opacity as it ages — so its geometry is a {@link DynamicMesh} (D5/I-10), not a
- * meshlet build, the same as paths and debug shapes.
- *
- * **It is drawn through AVBOIT, not over it.** The batch is a transparency channel
- * ({@link DynamicMeshAVBOITChannel}, registered with the facade): its fragments go into the same
- * extinction volume and accumulators as the transparent meshes and the GPU particles, so a trail
- * behind glass is seen through the glass, a trail inside smoke is hidden by the smoke in front of it
- * and hides the smoke behind it, and two trails crossing composite by depth, not by the order they
- * were linked in. Everything drawn at `AfterTransparency` runs after the transparency resolve they
- * are part of, so path display and the selection highlight land over a trail rather than under it.
- * Under MBOIT, the legacy transparency mode, trails are not drawn — as the particles are not.
+ * @param {TrailParameters} parameters
+ * @param {Trail3D} trail
+ * @param {Trail3DEntry} entry
+ */
+export function apply_trail3d(parameters: TrailParameters, trail: Trail3D, entry: Trail3DEntry): void;
+/**
+ * Draws every {@link Trail3D}: simulated on the GPU, its head following the entity's `transforms` row,
+ * its knots seeded and committed in compute and its tube extruded in the vertex stage, drawn inside the
+ * transparency pipeline (AVBOIT), so a trail behind glass or smoke composites with them by depth.
+ * Nothing per knot happens on the CPU.
  *
- * **The simulation is not this system's, and that is deliberate.** {@link seed_trail_tube} and
- * {@link advance_trail} are what the legacy `Trail3DSystem` runs too: the knots a trail lays down
- * are a property of the trail, not of the renderer drawing it, and two implementations of them
- * would be two trails that age differently. What is this system's is turning those knots into
- * vertices, once a frame, per trail.
+ * **What is the CPU's:** registering a trail with the scene context's {@link GPUTrailSystem} — a row, a
+ * knot run, the entity's transform row held through {@link EntityRowHold} — comparing each component's
+ * fields once a tick with what was staged and restaging what differs, and moving the clock by the
+ * simulation time it is given. A game writes `trail.color` or `trail.maxAge` from code that never heard
+ * of this system; there is no change signal to send.
  *
- * **Every trail is rewritten every frame it exists**, moving or not, because the simulator ages
- * every knot on every tick and the age is what the vertex opacity carries. There is no quiet trail
- * — a trail that has stopped is a trail fading out.
+ * **The head follows announced transforms.** A trail reads where its entity is from the GPU row, which a
+ * transform write reaches when it is announced (`TRANSFORM64_EVENT_CHANGE`), as meshes and particle
+ * emitters do.
  *
- * **What the tube material had and this does not**: a texture, lighting, and per-trail depth
- * writing. The dynamic path has one vertex layout — position and colour — and a trail is drawn as
- * unlit straight alpha, depth tested against the opaque scene and never written, which is what a
- * trail wants and what the game's trails are authored as. `Trail3D.textureURL` therefore draws
- * untinted here; nothing in the game's own effects sets it to anything a flat colour does not
- * carry.
+ * A trail's knot count (from its `maxAge`, or its authored layout's) and its `radialSegments` are fixed
+ * when it registers; a replaced authored layout brings its own count.
  */
 export class Trail3DSystem extends System<any> {
     /**
-     * @param {GraphicsEngine} graphics
+     * @param {import("./GraphicsEngine.js").GraphicsEngine} graphics
+     * @param {import("../../shade/renderer/scene/Scene.js").Scene} scene the scene the trails' entities are in
      */
-    constructor(graphics: GraphicsEngine);
+    constructor(graphics: import("./GraphicsEngine.js").GraphicsEngine, scene: import("../../shade/renderer/scene/Scene.js").Scene);
     dependencies: (typeof Transform64 | typeof Trail3D)[];
     /**
-     * What the transparency channel draws. Read-only — the meshes follow the entities.
+     * The runtime the scene's trails are registered with, or null while there is no scene context.
      *
-     * @returns {DynamicMeshBatch}
+     * @returns {GPUTrailSystem|null}
      */
-    get batch(): DynamicMeshBatch;
+    get runtime(): GPUTrailSystem;
     startup(entityManager: any): Promise<void>;
     shutdown(entityManager: any): Promise<void>;
     /**
@@ -57,7 +52,19 @@ export class Trail3DSystem extends System<any> {
      * @param {number} entity
      */
     unlink(trail: Trail3D, transform: Transform64, entity: number): void;
-    update(timeDelta: any): void;
+    /**
+     * Move the clock by the simulation time given, register what is waiting, and restage every trail
+     * whose component changed.
+     *
+     * @param {number} [time_delta_seconds]
+     */
+    update(time_delta_seconds?: number): void;
+    /**
+     * Record the frame's trail work — called by the frame extension.
+     *
+     * @param {import("../../shade/renderer/extension/FrameContext.js").FrameContext} frame
+     */
+    record(frame: import("../../shade/renderer/extension/FrameContext.js").FrameContext): void;
     #private;
 }
 /**
@@ -73,9 +80,36 @@ export class Trail3DSystem extends System<any> {
 export class TrailExtension extends RenderExtension {
     record(frame: any): void;
 }
+export type Trail3DEntry = {
+    entity: number;
+    trail: Trail3D;
+    /**
+     * the entity's row, kept current as it moves
+     */
+    hold: EntityRowHold;
+    /**
+     * the
+     * trail in the runtime, or null while it is not registered
+     */
+    context: import("../../shade/renderer/trails/GPUTrailSystem.js").GPUTrailContext | null;
+    /**
+     * knots of the trail's ring, fixed when it is built
+     */
+    knot_count: number;
+    /**
+     * radial segments, fixed when it is built
+     */
+    radial: number;
+    /**
+     * the component's `clearCount` as last seen
+     */
+    clears: number;
+};
+import { TrailParameters } from "../../shade/renderer/trails/runtime/TrailParameters.js";
+import Trail3D from "../graphics/ecs/trail3d/Trail3D.js";
 import { System } from "../ecs/System.js";
 import { Transform64 } from "../ecs/transform/Transform64.js";
-import Trail3D from "../graphics/ecs/trail3d/Trail3D.js";
-import { DynamicMeshBatch } from "../../shade/renderer/scene/DynamicMeshBatch.js";
+import { GPUTrailSystem } from "../../shade/renderer/trails/GPUTrailSystem.js";
 import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { EntityRowHold } from "./EntityRowHold.js";
 //# sourceMappingURL=Trail3DSystem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Trail3DSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/Trail3DSystem.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAuCI;;OAEG;IACH,sCAMC;IA/CD,sDAAsC;IA6BtC;;;;OAIG;IACH,8BAEC;IAaD,2CAIC;IAED,4CAQC;IAED;;;;OAIG;IACH,YAJW,OAAO,aACP,WAAW,UACX,MAAM,QAgBhB;IAED;;;;OAIG;IACH,cAJW,OAAO,aACP,WAAW,UACX,MAAM,QAiBhB;IAED,6BAaC;;CACJ;AAQD;;;;;;;;;GASG;AACH;IAeI,yBAEC;CACJ;uBA3MsB,kBAAkB;4BACb,iCAAiC;oBAGzC,oCAAoC;iCALvB,gDAAgD;gCAHjD,mDAAmD"}
+{"version":3,"file":"Trail3DSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/Trail3DSystem.js"],"names":[],"mappings":"AAsCA;;;;;;GAMG;AACH,0CAJW,eAAe,SACf,OAAO,SACP,YAAY,QA8BtB;AA8BD;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAuDI;;;OAGG;IACH,sBAHW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,EAW7D;IAnED,sDAAsC;IAqEtC;;;;OAIG;IACH,8BAEC;IAED,2CAOC;IAED,4CAWC;IA4BD;;;;OAIG;IACH,YAJW,OAAO,aACP,WAAW,UACX,MAAM,QAqBhB;IAED;;;;OAIG;IACH,cAJW,OAAO,aACP,WAAW,UACX,MAAM,QAIhB;IAED;;;;;OAKG;IACH,4BAFW,MAAM,QAchB;IAED;;;;OAIG;IACH,cAFW,OAAO,gDAAgD,EAAE,YAAY,QA2B/E;;CA2IJ;AAQD;;;;;;;;;GASG;AACH;IAeI,yBAEC;CACJ;;YA3ea,MAAM;WACN,OAAO;;;;UACP,aAAa;;;;;aACb,OAAO,+CAA+C,EAAE,eAAe,GAAC,IAAI;;;;gBAE5E,MAAM;;;;YACN,MAAM;;;;YACN,MAAM;;gCAlBY,wDAAwD;oBAIpE,oCAAoC;uBAHjC,kBAAkB;4BACb,iCAAiC;+BAH9B,+CAA+C;gCAJ9C,mDAAmD;8BAYrD,oBAAoB"}