@woosh/meep-engine 3.68.0 → 3.70.0

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

@@ -3,18 +3,12 @@
  * @enum {number}
  */
 export const Trail3DFlags = {
-    Spawning: 1,
-    Aging: 2,
-    Built: 4,
-    BoundsNeedUpdate: 8,
-
     /**
-     * Set by Trail3D.clear(); consumed by the next updateHead(), which collapses
-     * the whole tube onto the new head position before resuming. Guarantees no
-     * segment can bridge post-clear geometry to pre-clear history (e.g. a long
-     * streak after teleporting the entity).
+     * The head follows the entity and lays knots down behind it. Clear it to stop the trail where it
+     * is and let it fade out; a stroke ({@link seed_trail_stroke}) clears it, having its whole shape at
+     * birth.
      */
-    Reseed: 16,
+    Spawning: 1,
 
     /**
      * The tube processes standard scene lighting (receive-only — it never casts

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

@@ -1,18 +1,21 @@
 /**
  * Lay a trail down as a fixed stroke between two world points.
  *
- * **This is the other kind of trail.** {@link seed_trail_tube} collapses every knot onto the head
- * and lets the entity's travel draw the shape — a wake. A stroke has its whole shape at birth and
- * only ages: a beam leaves its source and arrives at its target inside one frame, so there is no
- * travel to lay it down with. Both are the same tube afterwards, aged by the same simulator and
- * drawn by the same renderer, which is what keeps the game to one trail mechanism (D19/I-6c).
+ * **This is the other kind of trail.** A wake collapses onto the head and lets the entity's travel draw
+ * the shape. A stroke has its whole shape at birth and only ages: a beam leaves its source and arrives at
+ * its target inside one frame, so there is no travel to lay it down with. Both are the same tube
+ * afterwards, aged and drawn by the same system, which is what keeps the game to one trail mechanism
+ * (D19/I-6c).
  *
- * The two ends carry their own starting age, and that is the whole of the gradient: the simulator
- * fades a knot's alpha as it approaches `maxAge`, so an end seeded older thins out first. A beam
- * whose source end starts most of the way through its life reads as retracting towards its target.
+ * The two ends carry their own starting age, and that is the whole of the gradient: a knot fades as it
+ * approaches `maxAge`, so an end seeded older thins out first. A beam whose source end starts most of the
+ * way through its life reads as retracting towards its target.
  *
- * **The caller must clear {@link Trail3DFlags.Spawning}**, or the per-frame update will drag the
- * head onto the entity and the stroke will grow a tail towards it.
+ * **The caller must clear {@link Trail3DFlags.Spawning}**, or the head will follow the entity and the
+ * stroke will grow a tail towards it.
+ *
+ * The knots go into {@link Trail3D#knots}, the authored layout the system uploads when the trail is
+ * registered.
  *
  * @param {Trail3D} trail
  * @param {Vector3} from world position the stroke starts at

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

@@ -1 +1 @@
-{"version":3,"file":"seed_trail_stroke.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/seed_trail_stroke.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wFAJW,MAAM,UACN,MAAM,GACJ,IAAI,CAqDhB"}
+{"version":3,"file":"seed_trail_stroke.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/seed_trail_stroke.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wFAJW,MAAM,UACN,MAAM,GACJ,IAAI,CA0ChB"}

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

@@ -3,8 +3,7 @@ import { v3_length } from "../../../../core/geom/vec3/v3_length.js";
 import {
     v3_orthonormal_matrix_from_normal
 } from "../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.js";
-import { TUBE_ATTRIBUTE_ADDRESS_AGE, TUBE_ATTRIBUTE_ADDRESS_UV_V } from "../../trail/tube/tube_attributes_spec.js";
-import { Trail3DFlags } from "./Trail3DFlags.js";
+import { TrailKnots } from "../../trail/TrailKnots.js";
 
 /**
  * The frame every knot of a straight stroke shares.
@@ -16,18 +15,21 @@ const frame = new Float64Array(9);
 /**
  * Lay a trail down as a fixed stroke between two world points.
  *
- * **This is the other kind of trail.** {@link seed_trail_tube} collapses every knot onto the head
- * and lets the entity's travel draw the shape — a wake. A stroke has its whole shape at birth and
- * only ages: a beam leaves its source and arrives at its target inside one frame, so there is no
- * travel to lay it down with. Both are the same tube afterwards, aged by the same simulator and
- * drawn by the same renderer, which is what keeps the game to one trail mechanism (D19/I-6c).
+ * **This is the other kind of trail.** A wake collapses onto the head and lets the entity's travel draw
+ * the shape. A stroke has its whole shape at birth and only ages: a beam leaves its source and arrives at
+ * its target inside one frame, so there is no travel to lay it down with. Both are the same tube
+ * afterwards, aged and drawn by the same system, which is what keeps the game to one trail mechanism
+ * (D19/I-6c).
  *
- * The two ends carry their own starting age, and that is the whole of the gradient: the simulator
- * fades a knot's alpha as it approaches `maxAge`, so an end seeded older thins out first. A beam
- * whose source end starts most of the way through its life reads as retracting towards its target.
+ * The two ends carry their own starting age, and that is the whole of the gradient: a knot fades as it
+ * approaches `maxAge`, so an end seeded older thins out first. A beam whose source end starts most of the
+ * way through its life reads as retracting towards its target.
  *
- * **The caller must clear {@link Trail3DFlags.Spawning}**, or the per-frame update will drag the
- * head onto the entity and the stroke will grow a tail towards it.
+ * **The caller must clear {@link Trail3DFlags.Spawning}**, or the head will follow the entity and the
+ * stroke will grow a tail towards it.
+ *
+ * The knots go into {@link Trail3D#knots}, the authored layout the system uploads when the trail is
+ * registered.
  *
  * @param {Trail3D} trail
  * @param {Vector3} from world position the stroke starts at
@@ -50,41 +52,30 @@ export function seed_trail_stroke(trail, from, to, age_from, age_to) {
 
     assert.greaterThan(length, 0, 'a stroke needs two distinct ends');
 
-    const segment_count = 2;
-
-    trail.build(segment_count);
-
-    const tube = trail.tube;
-
-    trail.time = 0;
-    trail.trailingIndex = 0;
-    trail.timeSinceLastUpdate = 0;
-    trail.distanceSinceLastUpdate = 0;
+    const knot_count = 2;
 
     const inv = 1 / length;
 
+    // the stroke is straight, so every ring shares one frame and no transport is needed
     v3_orthonormal_matrix_from_normal(frame, 0, dx * inv, dy * inv, dz * inv);
 
-    const color = trail.color;
-
     const max_age = trail.maxAge;
 
-    for (let i = 0; i < segment_count; i++) {
-        const f = i / (segment_count - 1);
-
-        const age = (age_from + (age_to - age_from) * f) * max_age;
+    const knots = new TrailKnots();
 
-        tube.setKnotPosition(i, from.x + dx * f, from.y + dy * f, from.z + dz * f);
+    knots.setCount(knot_count);
 
-        // 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]);
+    for (let i = 0; i < knot_count; i++) {
+        const f = i / (knot_count - 1);
 
-        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);
-        tube.setKnotAlpha(i, (1 - age / max_age) * color.w);
+        knots.setKnot(
+            i,
+            from.x + dx * f, from.y + dy * f, from.z + dz * f,
+            frame[0], frame[1], frame[2], frame[3], frame[4], frame[5],
+            trail.width,
+            (age_from + (age_to - age_from) * f) * max_age
+        );
     }
 
-    trail.setFlag(Trail3DFlags.Built);
+    trail.knots = knots;
 }

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

@@ -0,0 +1,10 @@
+/**
+ * Knots a trail that lasts `max_age` seconds lays down: one per sixtieth of a second, never fewer than 2
+ * nor more than 1,024. A trail's knots are a ring of fixed capacity, so this is what turns an age into a
+ * length.
+ *
+ * @param {number} max_age seconds
+ * @returns {number}
+ */
+export function trail_knot_count(max_age: number): number;
+//# sourceMappingURL=trail_knot_count.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trail_knot_count.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/trail_knot_count.js"],"names":[],"mappings":"AAgBA;;;;;;;GAOG;AACH,0CAHW,MAAM,GACJ,MAAM,CAIlB"}

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

@@ -0,0 +1,27 @@
+import { clamp } from "../../../../core/math/clamp.js";
+
+/**
+ * Knots laid down per second of trail life.
+ *
+ * @type {number}
+ */
+const KNOTS_PER_SECOND = 60;
+
+/**
+ * The most knots a trail's ring holds.
+ *
+ * @type {number}
+ */
+const MAX_KNOTS = 1024;
+
+/**
+ * Knots a trail that lasts `max_age` seconds lays down: one per sixtieth of a second, never fewer than 2
+ * nor more than 1,024. A trail's knots are a ring of fixed capacity, so this is what turns an age into a
+ * length.
+ *
+ * @param {number} max_age seconds
+ * @returns {number}
+ */
+export function trail_knot_count(max_age) {
+    return Math.ceil(clamp(max_age * KNOTS_PER_SECOND, 2, MAX_KNOTS));
+}

package/src/engine/graphics/trail/TrailKnots.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A trail laid down whole by its author instead of by an entity's travel: a stroke, a helix. Each knot
+ * has a position, the frame its ring stands in, a thickness and the age it starts with. The knots never
+ * move; they only age, and fade by the trail's curve as they do.
+ *
+ * Plain data on the component: whatever draws the trail uploads it when the trail is linked, and again
+ * when {@link version} moves. Ages are seconds, as `Trail3D.maxAge` is.
+ */
+export class TrailKnots {
+    /**
+     * Moved by every write, so a consumer holding an upload can tell it is stale.
+     * @type {number}
+     */
+    version: number;
+    /**
+     * @returns {number} knots
+     */
+    get count(): number;
+    /**
+     * Resize to `count` knots. Knots kept keep their values; new ones are zero.
+     *
+     * @param {number} count at least 2, the two ends of one segment
+     */
+    setCount(count: number): void;
+    /**
+     * @param {number} index
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} nx ring frame's first axis, unit
+     * @param {number} ny
+     * @param {number} nz
+     * @param {number} bx second axis, unit, orthogonal to the first and to the tube's direction
+     * @param {number} by
+     * @param {number} bz
+     * @param {number} thickness tube diameter
+     * @param {number} age seconds the knot is born having lived
+     */
+    setKnot(index: number, x: number, y: number, z: number, nx: number, ny: number, nz: number, bx: number, by: number, bz: number, thickness: number, age: number): void;
+    /**
+     * @param {number[]|Float32Array|Float64Array} out
+     * @param {number} index
+     */
+    getPosition(out: number[] | Float32Array | Float64Array, index: number): void;
+    /**
+     * @param {number[]|Float32Array|Float64Array} out `[nx, ny, nz, bx, by, bz]`
+     * @param {number} index
+     */
+    getFrame(out: number[] | Float32Array | Float64Array, index: number): void;
+    /**
+     * @param {number} index
+     * @returns {number}
+     */
+    getThickness(index: number): number;
+    /**
+     * @param {number} index
+     * @returns {number} seconds
+     */
+    getAge(index: number): number;
+    #private;
+}
+//# sourceMappingURL=TrailKnots.d.ts.map

package/src/engine/graphics/trail/TrailKnots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrailKnots.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/trail/TrailKnots.js"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH;IAWI;;;OAGG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,oBAEC;IAED;;;;OAIG;IACH,gBAFW,MAAM,QAgBhB;IAED;;;;;;;;;;;;;OAaG;IACH,eAbW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,aACN,MAAM,OACN,MAAM,QAsBhB;IAED;;;OAGG;IACH,iBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,SAClC,MAAM,QAQhB;IAED;;;OAGG;IACH,cAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,SAClC,MAAM,QAQhB;IAED;;;OAGG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,cAHW,MAAM,GACJ,MAAM,CAIlB;;CACJ"}

package/src/engine/graphics/trail/TrailKnots.js

@@ -0,0 +1,137 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * Numbers per knot: position (3), normal (3), binormal (3), thickness, age.
+ * @type {number}
+ */
+const KNOT_STRIDE = 11;
+
+/**
+ * A trail laid down whole by its author instead of by an entity's travel: a stroke, a helix. Each knot
+ * has a position, the frame its ring stands in, a thickness and the age it starts with. The knots never
+ * move; they only age, and fade by the trail's curve as they do.
+ *
+ * Plain data on the component: whatever draws the trail uploads it when the trail is linked, and again
+ * when {@link version} moves. Ages are seconds, as `Trail3D.maxAge` is.
+ */
+export class TrailKnots {
+    /**
+     * @type {Float64Array}
+     */
+    #data = new Float64Array(0);
+
+    /**
+     * @type {number}
+     */
+    #count = 0;
+
+    /**
+     * Moved by every write, so a consumer holding an upload can tell it is stale.
+     * @type {number}
+     */
+    version = 0;
+
+    /**
+     * @returns {number} knots
+     */
+    get count() {
+        return this.#count;
+    }
+
+    /**
+     * Resize to `count` knots. Knots kept keep their values; new ones are zero.
+     *
+     * @param {number} count at least 2, the two ends of one segment
+     */
+    setCount(count) {
+        assert.isNonNegativeInteger(count, 'count');
+        assert.greaterThanOrEqual(count, 2, 'a trail needs at least two knots');
+
+        if (this.#data.length < count * KNOT_STRIDE) {
+            const data = new Float64Array(count * KNOT_STRIDE);
+
+            data.set(this.#data.subarray(0, this.#count * KNOT_STRIDE));
+
+            this.#data = data;
+        }
+
+        this.#count = count;
+        this.version++;
+    }
+
+    /**
+     * @param {number} index
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} nx ring frame's first axis, unit
+     * @param {number} ny
+     * @param {number} nz
+     * @param {number} bx second axis, unit, orthogonal to the first and to the tube's direction
+     * @param {number} by
+     * @param {number} bz
+     * @param {number} thickness tube diameter
+     * @param {number} age seconds the knot is born having lived
+     */
+    setKnot(index, x, y, z, nx, ny, nz, bx, by, bz, thickness, age) {
+        assert.isNonNegativeInteger(index, 'index');
+        assert.lessThan(index, this.#count, 'index');
+
+        const d = this.#data;
+        const at = index * KNOT_STRIDE;
+
+        d[at] = x;
+        d[at + 1] = y;
+        d[at + 2] = z;
+        d[at + 3] = nx;
+        d[at + 4] = ny;
+        d[at + 5] = nz;
+        d[at + 6] = bx;
+        d[at + 7] = by;
+        d[at + 8] = bz;
+        d[at + 9] = thickness;
+        d[at + 10] = age;
+
+        this.version++;
+    }
+
+    /**
+     * @param {number[]|Float32Array|Float64Array} out
+     * @param {number} index
+     */
+    getPosition(out, index) {
+        const at = index * KNOT_STRIDE;
+
+        out[0] = this.#data[at];
+        out[1] = this.#data[at + 1];
+        out[2] = this.#data[at + 2];
+    }
+
+    /**
+     * @param {number[]|Float32Array|Float64Array} out `[nx, ny, nz, bx, by, bz]`
+     * @param {number} index
+     */
+    getFrame(out, index) {
+        const at = index * KNOT_STRIDE + 3;
+
+        for (let i = 0; i < 6; i++) {
+            out[i] = this.#data[at + i];
+        }
+    }
+
+    /**
+     * @param {number} index
+     * @returns {number}
+     */
+    getThickness(index) {
+        return this.#data[index * KNOT_STRIDE + 9];
+    }
+
+    /**
+     * @param {number} index
+     * @returns {number} seconds
+     */
+    getAge(index) {
+        return this.#data[index * KNOT_STRIDE + 10];
+    }
+}

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

@@ -1,5 +1,5 @@
 /**
- * Material configuration for a {@link TubeX}. Used as a cache key in
+ * Material configuration for a {@link Trail3D}'s tube. Used as a cache key in
  * {@link TubeXPlugin}, so any field that changes the compiled material (texture,
  * depth-write mode, lighting) participates in {@link equals}/{@link hash}.
  */

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

@@ -2,7 +2,7 @@ import { assert } from "../../../../core/assert.js";
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 
 /**
- * Material configuration for a {@link TubeX}. Used as a cache key in
+ * Material configuration for a {@link Trail3D}'s tube. Used as a cache key in
  * {@link TubeXPlugin}, so any field that changes the compiled material (texture,
  * depth-write mode, lighting) participates in {@link equals}/{@link hash}.
  */

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

@@ -0,0 +1,48 @@
+/**
+ * One system's hold on an entity's `transforms` row in a scene context, kept current as the entity
+ * moves: for a system whose GPU work reads where an entity is — a particle emitter, a trail's head.
+ *
+ * The listener on {@link TRANSFORM64_EVENT_CHANGE} stands from construction to {@link dispose}, whether
+ * or not a row is held, because an entity is linked before there is a scene context to hold a row in: a
+ * level loads before the device is up, and a device restart replaces the context under every entity.
+ * While a row is held in the context that is current, a move marks it, and the context's next build
+ * rewrites it from the transform. A Transform64 has no signals of its own; whoever writes it announces
+ * the change, and this wakes on that.
+ *
+ * {@link acquire} and {@link release} are the hold itself. A hold in a context that has since been
+ * replaced went with that context, so releasing it gives nothing back.
+ */
+export class EntityRowHold {
+    /**
+     * @param {import("../ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
+     * @param {number} entity
+     * @param {function(): (import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null)} current
+     * the scene context the entity's scene renders through now
+     */
+    constructor(dataset: import("../ecs/EntityComponentDataset.js").EntityComponentDataset, entity: number, current: () => (import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext | null));
+    /**
+     * @returns {number}
+     */
+    get entity(): number;
+    /**
+     * @returns {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null} where the row
+     * is held, or null when it is not
+     */
+    get context(): import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext;
+    /**
+     * Hold the entity's row in `context`, letting go of any hold in another.
+     *
+     * @param {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} context
+     */
+    acquire(context: import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext): void;
+    /**
+     * Let go of the row, if one is held in the context that is current.
+     */
+    release(): void;
+    /**
+     * Release, and stop listening.
+     */
+    dispose(): void;
+    #private;
+}
+//# sourceMappingURL=EntityRowHold.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EntityRowHold.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/EntityRowHold.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH;IAuBI;;;;;OAKG;IACH,qBALW,OAAO,kCAAkC,EAAE,sBAAsB,UACjE,MAAM,iBACM,CAAC,OAAO,+CAA+C,EAAE,eAAe,GAAC,IAAI,CAAC,EAapG;IAED;;OAEG;IACH,qBAEC;IAED;;;OAGG;IACH,uFAEC;IAED;;;;OAIG;IACH,iBAFW,OAAO,+CAA+C,EAAE,eAAe,QAcjF;IAED;;OAEG;IACH,gBAYC;IAED;;OAEG;IACH,gBAIC;;CAWJ"}

package/src/engine/graphics3/EntityRowHold.js

@@ -0,0 +1,128 @@
+import { assert } from "../../core/assert.js";
+import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
+
+/**
+ * One system's hold on an entity's `transforms` row in a scene context, kept current as the entity
+ * moves: for a system whose GPU work reads where an entity is — a particle emitter, a trail's head.
+ *
+ * The listener on {@link TRANSFORM64_EVENT_CHANGE} stands from construction to {@link dispose}, whether
+ * or not a row is held, because an entity is linked before there is a scene context to hold a row in: a
+ * level loads before the device is up, and a device restart replaces the context under every entity.
+ * While a row is held in the context that is current, a move marks it, and the context's next build
+ * rewrites it from the transform. A Transform64 has no signals of its own; whoever writes it announces
+ * the change, and this wakes on that.
+ *
+ * {@link acquire} and {@link release} are the hold itself. A hold in a context that has since been
+ * replaced went with that context, so releasing it gives nothing back.
+ */
+export class EntityRowHold {
+    /**
+     * @type {import("../ecs/EntityComponentDataset.js").EntityComponentDataset}
+     */
+    #dataset;
+
+    /**
+     * @type {number}
+     */
+    #entity;
+
+    /**
+     * Answers which scene context is current.
+     * @type {function(): (import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null)}
+     */
+    #current;
+
+    /**
+     * The context the row is held in, or null.
+     * @type {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null}
+     */
+    #context = null;
+
+    /**
+     * @param {import("../ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
+     * @param {number} entity
+     * @param {function(): (import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null)} current
+     * the scene context the entity's scene renders through now
+     */
+    constructor(dataset, entity, current) {
+        assert.defined(dataset, 'dataset');
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.isFunction(current, 'current');
+
+        this.#dataset = dataset;
+        this.#entity = entity;
+        this.#current = current;
+
+        dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, this.#moved, this);
+    }
+
+    /**
+     * @returns {number}
+     */
+    get entity() {
+        return this.#entity;
+    }
+
+    /**
+     * @returns {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null} where the row
+     * is held, or null when it is not
+     */
+    get context() {
+        return this.#context;
+    }
+
+    /**
+     * Hold the entity's row in `context`, letting go of any hold in another.
+     *
+     * @param {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} context
+     */
+    acquire(context) {
+        assert.defined(context, 'context');
+
+        if (this.#context === context) {
+            return;
+        }
+
+        this.release();
+
+        context.rows.acquire(this.#entity);
+
+        this.#context = context;
+    }
+
+    /**
+     * Let go of the row, if one is held in the context that is current.
+     */
+    release() {
+        const context = this.#context;
+
+        if (context === null) {
+            return;
+        }
+
+        if (context === this.#current()) {
+            context.rows.release(this.#entity);
+        }
+
+        this.#context = null;
+    }
+
+    /**
+     * Release, and stop listening.
+     */
+    dispose() {
+        this.release();
+
+        this.#dataset.removeEntityEventListener(this.#entity, TRANSFORM64_EVENT_CHANGE, this.#moved, this);
+    }
+
+    #moved() {
+        const context = this.#context;
+
+        if (context === null || context !== this.#current()) {
+            return;
+        }
+
+        context.rows.mark_world(this.#entity);
+    }
+}

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

@@ -32,11 +32,12 @@ export const GPU_FLUID_SYSTEM_TICK_CAP: number;
  * 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
  *
@@ -58,8 +59,8 @@ export const GPU_FLUID_SYSTEM_TICK_CAP: number;
  *   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.
  *
@@ -168,6 +169,18 @@ export class GPUFluidSystem extends System<any> {
      * @param {Float64Array|Float32Array|number[]} out receives `[x, y, z]`
      */
     far_field(out: Float64Array | Float32Array | number[]): void;
+    /**
+     * 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: Float64Array | Float32Array | number[], x: number, y: number, z: number): void;
     /**
      * 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

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

@@ -1 +1 @@
-{"version":3,"file":"GPUFluidSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GPUFluidSystem.js"],"names":[],"mappings":"AAyCA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,wCAFU,MAAM,CAE2B;AAmG3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkGG;AACH;IAEI;;;;;OAKG;IACH,iCAFW,OAAO,gDAAgD,EAAE,eAAe,QAMlF;IAyID;;;OAGG;IACH,sBAHW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,EAU7D;IAnJD,gEAAgD;IAEhD,oOAME;IA6IF;;OAEG;IACH,iEAEC;IAED;;;;;OAKG;IACH,qBAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;OAKG;IACH,+BAEC;IAED;;;;;OAKG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,eAFW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,QAQ5C;IAED;;;;;;;;;;OAUG;IACH,yBAEC;IAED;;;;;OAKG;IACH,+BAEC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAbW,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,UACN,YAAY,iBACZ,MAAM,GACJ,MAAM,CA+ClB;IAmMD,2CAOC;IAED,4CAaC;IA4DD;;;;OAIG;IACH,gBAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAOhB;IAED;;;;OAIG;IACH,kBAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAiBhB;IAqiBD;;;;;OAKG;IACH,eAFW,YAAY,QAetB;IAkKL;;;;;;;OAOG;IACH,2BAFU,OAAO,CAEwB;;CAVxC;AAYD;;;GAGG;AACH;IAII;;OAEG;IACH,oBAFW,cAAc,EAMxB;IADG,uBAAoB;CAkB3B;8BA1kDY,OAAO,+CAA+C,EAAE,eAAe;2BACvE,OAAO,gDAAgD,EAAE,YAAY;oCACrE,OAAO,oDAAoD,EAAE,qBAAqB;kCAClF,OAAO,kEAAkE,EAAE,mBAAmB;kCAC9F,OAAO,2DAA2D,EAAE,mBAAmB;8BACvF,OAAO,6CAA6C,EAAE,eAAe;uBAjC3D,kBAAkB;4BACb,iCAAiC;kCAWtD,2CAA2C;wCARV,iDAAiD;4CAf7C,iDAAiD;8BAiB/D,uCAAuC;yBAJ5C,4BAA4B;0BAC3B,6BAA6B;qCARlB,oDAAoD;gCADzD,uDAAuD;gCAE5B,qDAAqD;gCAJhF,mDAAmD"}
+{"version":3,"file":"GPUFluidSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GPUFluidSystem.js"],"names":[],"mappings":"AA0CA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,wCAFU,MAAM,CAE2B;AAiH3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH;IAEI;;;;;OAKG;IACH,iCAFW,OAAO,gDAAgD,EAAE,eAAe,QAMlF;IAkJD;;;OAGG;IACH,sBAHW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,EAU7D;IA5JD,gEAAgD;IAEhD,oOAME;IAsJF;;OAEG;IACH,iEAEC;IAED;;;;;OAKG;IACH,qBAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;OAKG;IACH,+BAEC;IAED;;;;;OAKG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,eAFW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,QAQ5C;IAED;;;;;;;;;;OAUG;IACH,kBALW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,KAClC,MAAM,KACN,MAAM,KACN,MAAM,QAIhB;IAED;;;;;;;;;;OAUG;IACH,yBAEC;IAED;;;;;OAKG;IACH,+BAEC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAbW,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,UACN,YAAY,iBACZ,MAAM,GACJ,MAAM,CA+ClB;IA+ND,2CAOC;IAED,4CAaC;IA4DD;;;;OAIG;IACH,gBAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAOhB;IAED;;;;OAIG;IACH,kBAJW,iBAAiB,aACjB,WAAW,UACX,MAAM,QAiBhB;IAqiBD;;;;;OAKG;IACH,eAFW,YAAY,QAetB;IA+LL;;;;;;;OAOG;IACH,2BAFU,OAAO,CAEwB;;CAVxC;AAYD;;;GAGG;AACH;IAII;;OAEG;IACH,oBAFW,cAAc,EAMxB;IADG,uBAAoB;CAkB3B;8BA1qDY,OAAO,+CAA+C,EAAE,eAAe;2BACvE,OAAO,gDAAgD,EAAE,YAAY;oCACrE,OAAO,oDAAoD,EAAE,qBAAqB;kCAClF,OAAO,kEAAkE,EAAE,mBAAmB;kCAC9F,OAAO,2DAA2D,EAAE,mBAAmB;8BACvF,OAAO,6CAA6C,EAAE,eAAe;uBAlC3D,kBAAkB;4BACb,iCAAiC;kCAWtD,2CAA2C;wCARV,iDAAiD;4CAf7C,iDAAiD;8BAiB/D,uCAAuC;yBAJ5C,4BAA4B;0BAC3B,6BAA6B;qCARlB,oDAAoD;gCADzD,uDAAuD;gCAE5B,qDAAqD;gCAJhF,mDAAmD"}