@woosh/meep-engine 3.30.0 → 3.32.0

package/src/engine/physics/ecs/PhysicsSystem.js

@@ -1,5 +1,4 @@
 import { assert } from "../../../core/assert.js";
-import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
 import { ebvh_optimize_treelet } from "../../../core/bvh2/bvh3/ebvh_optimize_treelet.js";
 import {
@@ -46,7 +45,7 @@ import {
 import { BodyKind } from "./BodyKind.js";
 import { Collider, COLLIDER_UNBOUND } from "./Collider.js";
 import { find_non_finite_physics_state } from "./find_non_finite_physics_state.js";
-import { is_sensor } from "./is_sensor.js";
+import { body_is_wholly_sensor } from "./is_sensor.js";
 import { JOINT_UNALLOCATED, JOINT_WORLD } from "./Joint.js";
 import { PhysicsEvents } from "./PhysicsEvents.js";
 import { RIGID_BODY_UNALLOCATED, RigidBody } from "./RigidBody.js";
@@ -103,6 +102,12 @@ const scratch_stored_aabb = new Float64Array(6);
 const scratch_prox_mover = new Float64Array(6);
 const scratch_prox_sleeper = new Float64Array(6);
 
+/**
+ * {@link PhysicsSystem#interpolationLog} warns once per process, not once per system.
+ * @type {boolean}
+ */
+let interpolation_log_deprecation_warned = false;
+
 /**
  * Rigid-body physics system.
  *
@@ -388,39 +393,36 @@ export class PhysicsSystem extends System {
     __ccd_start_pos = new Float64Array(0);
 
     /**
-     * Set this to the {@link InterpolationSystem}'s log to get render
-     * interpolation: each step then restores every awake {@link Interpolated}
-     * body's authoritative pose before simulating, and records the result
-     * afterwards. Leave `null` on a headless world — the work is skipped
-     * entirely.
      * @type {InterpolationLog|null}
      */
-    interpolationLog = null;
-
-    /** @private @type {number} valid entries in {@link __interp_recorded} */
-    __interp_recorded_count = 0;
-
-    constructor() {
-        super();
-
-        /**
-         * Reusable decode buffer for restoring interpolated snapshots.
-         * @private
-         * @type {BinaryBuffer}
-         */
-        this.__interp_scratch = new BinaryBuffer();
-        this.__interp_scratch.fromArrayBuffer(new ArrayBuffer(256));
-
-        /**
-         * Body indices snapshotted by the LAST {@link __interp_record} — i.e. the awake
-         * Interpolated set as it was at the end of the previous tick. {@link __interp_restore}
-         * iterates THIS set (not the current awake set) so a body that slept on the previous
-         * tick — recorded before it slept, but absent from the current awake set — is still
-         * restored off its render-polluted pose. Sparse: O(interpolated moving bodies).
-         * @private
-         * @type {Uint32Array}
-         */
-        this.__interp_recorded = new Uint32Array(16);
+    #legacy_interpolation_log = null;
+
+    /**
+     * **Deprecated; does nothing.** Physics used to produce render interpolation itself: with this
+     * set to the {@link InterpolationSystem}'s log, each step restored every awake interpolated
+     * body from the previous tick's record and recorded it again afterwards. The
+     * {@link InterpolationSystem} now records and restores every {@link Interpolated} entity on its
+     * own, around the whole fixed step, so there is nothing to wire.
+     *
+     * The move fixed a defect rather than tidying one up: "restore from the previous tick's record"
+     * cannot tell a render blend from a legitimate write, so a network correction — or any other
+     * write made between steps — was put back to the recorded pose at the start of the next step,
+     * indefinitely for a predicted body the host kept correcting.
+     *
+     * Kept so existing wiring keeps working; setting it warns once.
+     * @deprecated
+     * @type {InterpolationLog|null}
+     */
+    get interpolationLog() {
+        return this.#legacy_interpolation_log;
+    }
+
+    set interpolationLog(log) {
+        if (log !== null && log !== undefined && !interpolation_log_deprecation_warned) {
+            interpolation_log_deprecation_warned = true;
+            console.warn('PhysicsSystem.interpolationLog is deprecated and ignored: InterpolationSystem records and restores Interpolated entities by itself. Remove the assignment.');
+        }
+        this.#legacy_interpolation_log = log;
     }
 
     /**
@@ -469,15 +471,23 @@ export class PhysicsSystem extends System {
     }
 
     /**
-     * First attached collider of a body, or `null` if none. Used for
-     * body-level checks that aren't yet per-collider: the sensor flag, the
-     * concave-shape dispatch flag, and the contact-filter callback's
-     * `colliderA` / `colliderB` arguments. Contact **materials** (friction /
-     * restitution) are NOT read here — the narrowphase tracks the specific
-     * source collider on each side of every contact and stamps the combined
-     * coefficients into the manifold per contact, so mixed-material compound
-     * bodies are accurate. (Per-contact source colliders for the filter
-     * callback / sensor flag remain a follow-up.)
+     * First attached collider of a body, or `null` if none. Used for the
+     * contact-filter callback's `colliderA` / `colliderB` arguments, and as a
+     * "does this body have any colliders" test.
+     *
+     * It is NOT how the solver decides anything about a body. Contact
+     * materials (friction / restitution) and the sensor flag are per contact:
+     * the narrowphase tracks the specific source collider on each side of
+     * every contact and stamps the combined coefficients and
+     * {@link CONTACT_FLAG_SENSOR} into the manifold, so a compound body whose
+     * colliders disagree — different materials, or a trigger volume beside a
+     * solid hull — is handled per contact rather than by whichever collider
+     * {@link ColliderObserverSystem} happened to attach first. The remaining
+     * body-level questions read the whole list, through
+     * {@link body_is_wholly_sensor}.
+     *
+     * (Per-contact source colliders for the filter callback remain a
+     * follow-up.)
      *
      * @private
      * @param {number} body_idx
@@ -1126,14 +1136,16 @@ export class PhysicsSystem extends System {
     /**
      * Teleport a body to a new pose, bypassing integration: writes the body's
      * Transform64 directly and wakes it. For an interpolated body this also flags a
-     * render `snap` on its {@link Interpolated} component, so the producer keeps
-     * this pose (rather than restoring the previous tick over it) and the
-     * renderer shows the new pose without sliding across the jump.
+     * render `snap` on its {@link Interpolated} component, so the interpolation
+     * history is rewritten to the new pose and the renderer shows it without
+     * sliding across the jump.
      *
-     * This is the authoritative way to reposition an interpolated body — a raw
-     * `Transform64` write would be undone by the per-step restore. Velocity is left
-     * as-is; zero it via {@link setLinearVelocity} if the teleport should also
-     * stop the body.
+     * Prefer this to a raw `Transform64` write. On an interpolated body a raw write
+     * made between steps is put back when the next step opens, unless it set `snap`
+     * or restored the interpolation first; and a raw write neither wakes a sleeping
+     * body nor re-homes a non-dynamic body's broadphase leaves. Velocity is left
+     * as-is; zero it via {@link setLinearVelocity} if the teleport should also stop
+     * the body.
      *
      * Works for STATIC bodies too: their broadphase leaves are re-homed to
      * the new pose, and sleepers at both the old and the new location are
@@ -1191,21 +1203,10 @@ export class PhysicsSystem extends System {
             this.__wake_body(rigidBody);
         }
 
-        // Flag a snap on the body's Interpolated component, if any, so the
-        // interpolation producer (restore) and consumer (blend) treat this pose
-        // as authoritative this frame instead of interpolating across the jump.
-        //
-        // KNOWN BUG (deferred): `snap` is a single flag with two independent consumers —
-        // __interp_restore (skips restore) and InterpolationSystem.update (skips blend AND
-        // CLEARS it). The renderer's update runs every render cycle while a fixed step only
-        // runs when the accumulator crosses the step size, so a render frame landing between
-        // this setPose and the next fixedUpdate clears `snap` before __interp_restore reads
-        // it — restore then overwrites the teleported Transform64 with the pre-teleport tick's
-        // snapshot and the teleport is silently reverted in the SIMULATION. This only bites
-        // once InterpolationSystem is wired (the app does not wire it yet). The robust fix is
-        // to make the teleport authoritative independent of the shared flag — either overwrite
-        // the log's latest-tick record for this body (needs new InterpolationLog API), or give
-        // the producer and consumer independent snap state each clears itself.
+        // Flag a snap on the body's Interpolated component, if any: the
+        // InterpolationSystem keeps this pose rather than putting back what a render
+        // blend displaced, and rewrites the body's recent interpolation records with
+        // it, so the blend resumes from here instead of sliding across the jump.
         const em = this.entityManager;
         if (em !== null && em !== undefined) {
             const dataset = em.dataset;
@@ -1230,6 +1231,15 @@ export class PhysicsSystem extends System {
     /**
      * Force the body asleep. Dynamic bodies will not re-enter the active list
      * until a wake event occurs.
+     *
+     * Velocity is zeroed, exactly as {@link __atomic_sleep_island_range} does
+     * when the simulation puts an island down. That is not a courtesy — the
+     * solver gathers a sleeping Dynamic body as a zero-mass anchor and feeds
+     * its velocity to every contact row it appears in, on the invariant that a
+     * sleeping body is at rest. A body forced asleep mid-flight would otherwise
+     * push its awake neighbours around while immovable itself, and discharge
+     * the stored velocity as a lurch on the next wake.
+     *
      * @param {RigidBody} rigidBody
      */
     sleep(rigidBody) {
@@ -1246,6 +1256,12 @@ export class PhysicsSystem extends System {
             return;
         }
         rigidBody.sleepState = SleepState.Sleeping;
+        rigidBody.linearVelocity[0] = 0;
+        rigidBody.linearVelocity[1] = 0;
+        rigidBody.linearVelocity[2] = 0;
+        rigidBody.angularVelocity[0] = 0;
+        rigidBody.angularVelocity[1] = 0;
+        rigidBody.angularVelocity[2] = 0;
         const index = body_id_index(rigidBody._bodyId);
         this.storage.mark_sleeping(index);
     }
@@ -1510,7 +1526,8 @@ export class PhysicsSystem extends System {
             // IslandBuilder, the contact solver). It must not wake a sleeper either — otherwise a
             // moving trigger volume re-wakes everything it overlaps every frame, holding whole
             // islands permanently awake. Skip the pair, mirroring IslandBuilder.__body_is_sensor.
-            if (is_sensor(a, this.__primary_collider(idxA)) || is_sensor(b, this.__primary_collider(idxB))) {
+            if (body_is_wholly_sensor(a, this.__body_collider_lists[idxA])
+                || body_is_wholly_sensor(b, this.__body_collider_lists[idxB])) {
                 continue;
             }
 
@@ -1841,148 +1858,6 @@ export class PhysicsSystem extends System {
         }
     }
 
-    /**
-     * Producer — restore pass. At the top of a fixed step, reset every awake
-     * {@link Interpolated} body's live components to their authoritative state
-     * from the previous tick's snapshot, undoing any render-time interpolation
-     * the {@link InterpolationSystem} wrote between frames so the sim integrates
-     * from truth, not an interpolated pose. A body with no previous snapshot
-     * (first step ever, or just woken) is left as-is — its live state is already
-     * authoritative. No-op unless {@link interpolationLog} is wired.
-     * @private
-     */
-    __interp_restore() {
-        const log = this.interpolationLog;
-        const em = this.entityManager;
-        if (log === null || em === null || em === undefined) return;
-        const dataset = em.dataset;
-        if (dataset === null || dataset === undefined) return;
-
-        const prev_tick = em.fixedStepTick - 1;
-        if (prev_tick < 0) return;
-
-        const storage = this.storage;
-        // Iterate the set snapshotted at prev_tick (the previous __interp_record), NOT the current
-        // awake set: a body that fell asleep on prev_tick was awake when it was recorded (record runs
-        // before the sleep test) so it carries a prev_tick snapshot, yet it is no longer in the awake
-        // set. Restoring only the awake set would leave that just-slept body holding the render-blended
-        // pose the last frame wrote — which the sim then reads via __swept_proximity and integrates
-        // from if it wakes this step. A body woken THIS step has no prev_tick record, so log.interpolate
-        // returns false and it is correctly left on its (authoritative) live pose.
-        const recorded = this.__interp_recorded;
-        const count = this.__interp_recorded_count;
-        const scratch = this.__interp_scratch;
-
-        for (let i = 0; i < count; i++) {
-            const idx = recorded[i];
-            const entity = storage.entity_at(idx);
-            if (entity < 0) continue; // slot freed since it was recorded
-            const interpolated = dataset.getComponent(entity, Interpolated);
-            if (interpolated === undefined || interpolated === null) continue;
-            // A teleported body (snap set, e.g. via setPose) keeps its live pose
-            // this step — restoring the previous tick would undo the teleport.
-            if (interpolated.snap) continue;
-            const key = interpolated.key;
-            if (key < 0) continue;
-
-            const interpolands = interpolated.interpolands;
-            for (let k = 0; k < interpolands.length; k++) {
-                const ip = interpolands[k];
-                scratch.position = 0;
-                // Snap to the previous tick's snapshot (both offsets equal → t irrelevant).
-                const ok = log.interpolate(scratch, key, ip.type_id, prev_tick, prev_tick, 0, ip.interpolation_adapter);
-                if (!ok) continue;
-                const target = dataset.getComponent(entity, ip.component_class);
-                if (target === undefined || target === null) continue;
-                scratch.position = 0;
-                ip.serialization_adapter.deserialize(scratch, target);
-            }
-        }
-    }
-
-    /**
-     * Producer — record pass. At the end of a fixed step, snapshot every awake
-     * {@link Interpolated} body's live components into the shared log under the
-     * current `entityManager.fixedStepTick`. The render-time
-     * {@link InterpolationSystem} blends consecutive ticks from these snapshots.
-     * Only awake (moving) bodies are recorded, so the log stays sparse. No-op
-     * unless {@link interpolationLog} is wired.
-     *
-     * **A body created after this pass has no snapshot for the step it was born on, and renders
-     * from one snapshot for a step.** This pass runs at the end of `fixedUpdate`, and game code
-     * runs after it — that ordering is correct, the sim must read the solved poses — so a body
-     * spawned by game code is invisible to the tick it was spawned into. Its first record is the
-     * NEXT tick, and `InterpolationLog.interpolate` handles the missing half gracefully by falling
-     * back to whichever snapshot exists. That is the right primitive behaviour and it produces a
-     * bad picture: the entity is drawn at the *newer* tick for a whole frame budget, so it appears
-     * to jump a full step's travel and then hold still for one. Measured at 165 Hz by a port
-     * (GAP-036) as four frames of a rocket parked at the muzzle, reported by a player as
-     * "projectiles move with jerks".
-     *
-     * **Why this is documented rather than fixed, which is the part worth knowing.** The obvious
-     * fix — record a body's pose when it links — does not fit this log. {@link InterpolationLog} is
-     * a strictly monotonic tick ring: `begin_tick` throws while a tick is open, pages are
-     * contiguous ranges that the next page's bytes follow immediately, and `#ticks` is keyed by
-     * tick number — so re-opening the closed tick to append one body would overwrite that tick's
-     * metadata for every other body in it. The fix that does work is to move this pass out of
-     * `fixedUpdate` into a system registered after every simulation system, which is what a
-     * consumer hitting this did; that costs a second mandatory registration, which is a trade this
-     * engine has decided against elsewhere. Closing it properly means either a per-body "first
-     * tick" the blend can consult, or a log that accepts an out-of-order record.
-     *
-     * The workaround needs no engine change: put the body on the application's own timeline via a
-     * pose recorder registered last, since `__interp_restore` does not filter by `sourceId` and
-     * `PhysicsSystem` still restores the authoritative pose before it integrates.
-     *
-     * @private
-     */
-    __interp_record() {
-        const log = this.interpolationLog;
-        const em = this.entityManager;
-        if (log === null || em === null || em === undefined) return;
-        const dataset = em.dataset;
-        if (dataset === null || dataset === undefined) return;
-
-        const tick = em.fixedStepTick;
-        const storage = this.storage;
-        const count = storage.awake_count;
-
-        // Rebuild the "recorded this tick" set that __interp_restore will iterate next tick.
-        let recorded = this.__interp_recorded;
-        let recorded_count = 0;
-
-        log.begin_tick(tick);
-        for (let i = 0; i < count; i++) {
-            const idx = storage.awake_at(i);
-            const entity = storage.entity_at(idx);
-            const interpolated = dataset.getComponent(entity, Interpolated);
-            if (interpolated === undefined || interpolated === null) continue;
-            const key = interpolated.key;
-            if (key < 0) continue;
-
-            if (recorded_count === recorded.length) {
-                const grown = new Uint32Array(recorded.length * 2);
-                grown.set(recorded);
-                recorded = grown;
-                this.__interp_recorded = grown;
-            }
-            recorded[recorded_count++] = idx;
-
-            const interpolands = interpolated.interpolands;
-            for (let k = 0; k < interpolands.length; k++) {
-                const ip = interpolands[k];
-                const target = dataset.getComponent(entity, ip.component_class);
-                if (target === undefined || target === null) continue;
-                const buf = log.begin_record(key, ip.type_id);
-                ip.serialization_adapter.serialize(buf, target);
-                log.end_record();
-            }
-        }
-        log.end_tick();
-
-        this.__interp_recorded_count = recorded_count;
-    }
-
     /**
      * Advance the simulation by one step: forces, broadphase, narrowphase,
      * islands, the substep solve, CCD, sleep, and contact-event dispatch.
@@ -1995,10 +1870,6 @@ export class PhysicsSystem extends System {
      * @param {number} dt seconds
      */
     fixedUpdate(dt) {
-        // Producer: restore authoritative pose (undo render interpolation)
-        // before the sim reads any Transform64 this step.
-        this.__interp_restore();
-
         const gx = this.gravity[0];
         const gy = this.gravity[1];
         const gz = this.gravity[2];
@@ -2351,12 +2222,6 @@ export class PhysicsSystem extends System {
             ccd_resolve(this);
         }
 
-        // Producer: record the post-step authoritative pose of every awake
-        // interpolated body under this step's tick. Before the sleep test, so a
-        // body that settles this step still records its final pose for the last
-        // interpolation interval.
-        this.__interp_record();
-
         // Stage 9: sleep test.
         this.__sleep_test(dt);
 

package/src/engine/physics/ecs/is_sensor.d.ts

@@ -15,4 +15,28 @@
  * @returns {boolean}
  */
 export function is_sensor(rb: RigidBody, collider: Collider | null): boolean;
+/**
+ * Whether a body is a sensor ALL THE WAY THROUGH: the body flag, or every
+ * attached collider carrying {@link ColliderFlags.IsSensor}. A body with no
+ * colliders falls back to the body flag alone.
+ *
+ * The body-level questions — is this pair excluded from sleep islands, may it
+ * wake a sleeper, can the whole manifold be skipped — used to be answered from
+ * the body's PRIMARY collider, whichever one `ColliderObserverSystem.link`
+ * happened to see first. A body's colliders need not agree: a body built as
+ * [trigger volume, solid hull] read as a sensor and let everything fall
+ * through the solid hull, and the same body built the other way round had its
+ * trigger push. Attach order is not under the author's control.
+ *
+ * Only a body that is wholly a sensor can be treated as one. A mixed body is
+ * gated per contact, from the flag the narrowphase stamps where it knows which
+ * collider pair produced each contact.
+ *
+ * @param {RigidBody} rb
+ * @param {Array<{collider: Collider}>} [collider_list] the body's collider list
+ * @returns {boolean}
+ */
+export function body_is_wholly_sensor(rb: RigidBody, collider_list?: Array<{
+    collider: Collider;
+}>): boolean;
 //# sourceMappingURL=is_sensor.d.ts.map

package/src/engine/physics/ecs/is_sensor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is_sensor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/is_sensor.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,mDAJW,WAAS,IAAI,GAEX,OAAO,CASnB"}
+{"version":3,"file":"is_sensor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/is_sensor.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,mDAJW,WAAS,IAAI,GAEX,OAAO,CASnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qEAHW,MAAM;IAAC,QAAQ,WAAU;CAAC,CAAC,GACzB,OAAO,CAkBnB"}

package/src/engine/physics/ecs/is_sensor.js

@@ -25,3 +25,42 @@ export function is_sensor(rb, collider) {
     return collider !== null && collider !== undefined
         && (collider.flags & ColliderFlags.IsSensor) !== 0;
 }
+
+/**
+ * Whether a body is a sensor ALL THE WAY THROUGH: the body flag, or every
+ * attached collider carrying {@link ColliderFlags.IsSensor}. A body with no
+ * colliders falls back to the body flag alone.
+ *
+ * The body-level questions — is this pair excluded from sleep islands, may it
+ * wake a sleeper, can the whole manifold be skipped — used to be answered from
+ * the body's PRIMARY collider, whichever one `ColliderObserverSystem.link`
+ * happened to see first. A body's colliders need not agree: a body built as
+ * [trigger volume, solid hull] read as a sensor and let everything fall
+ * through the solid hull, and the same body built the other way round had its
+ * trigger push. Attach order is not under the author's control.
+ *
+ * Only a body that is wholly a sensor can be treated as one. A mixed body is
+ * gated per contact, from the flag the narrowphase stamps where it knows which
+ * collider pair produced each contact.
+ *
+ * @param {RigidBody} rb
+ * @param {Array<{collider: Collider}>} [collider_list] the body's collider list
+ * @returns {boolean}
+ */
+export function body_is_wholly_sensor(rb, collider_list) {
+    if ((rb.flags & RigidBodyFlags.IsSensor) !== 0) {
+        return true;
+    }
+
+    if (collider_list === undefined || collider_list.length === 0) {
+        return false;
+    }
+
+    for (let i = 0; i < collider_list.length; i++) {
+        if ((collider_list[i].collider.flags & ColliderFlags.IsSensor) === 0) {
+            return false;
+        }
+    }
+
+    return true;
+}

package/src/engine/physics/fluid/ecs/FluidComponent.d.ts

@@ -141,10 +141,24 @@ export class FluidComponent {
     hash(): number;
     /**
      * Write the field's world-space axis-aligned bounding box into `out`. Used by
-     * {@link FluidSystem} as a broad-phase target when filtering effectors. The box
-     * spans cell `(0, 0, 0)` (centred at `origin`) to cell `(res_x-1, res_y-1, res_z-1)`
-     * plus a `cell_size` margin on the far side, so a point exactly on the field's
-     * boundary cells lies inside the AABB.
+     * {@link FluidSystem} and {@link WorkerFluidSystem} as the broad-phase target when
+     * filtering effectors.
+     *
+     * `origin` is cell `(0,0,0)`'s CENTRE, so the occupied volume runs from
+     * `origin - cell_size/2` to `origin + (res - 0.5) * cell_size`. The box is that
+     * volume plus one `cell_size` on every side.
+     *
+     * The margin is not slack. An effector's own AABB is its position expanded by its
+     * USER radius, while the splat floors the effective kernel at one grid cell
+     * ({@link ImpulseFluidEffector}), so a sub-cell-radius source deposits up to a cell
+     * further than its AABB reaches. Covering that here is what keeps the broad-phase
+     * conservative: a false positive costs one wasted splat, a false negative is a fan
+     * that silently stops working.
+     *
+     * This used to write `[origin, origin + res * cell_size]` — a full cell of slack
+     * past the far side and NONE at all on the near one — so a source placed within half
+     * a cell outside the near face was dropped for this field entirely while the same
+     * source on the far side worked.
      *
      * @param {AABB3} out
      */

package/src/engine/physics/fluid/ecs/FluidComponent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidComponent.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidComponent.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAEI;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;OAOG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;;;;;;OAQG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;OAKG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAOhC;IAED;;;;;;;;;;;;;;OAcG;IACH,2BANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACL,MAAM,CAQjB;IAED;;;OAGG;IACH,cAHW,cAAc,GACb,OAAO,CAoBlB;IAED;;OAEG;IACH,QAFY,MAAM,CAgBjB;IAED;;;;;;;;OAQG;IACH,iCAYC;IAGL,0BAAyC;CAFxC;2BA1O0B,kBAAkB"}
+{"version":3,"file":"FluidComponent.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidComponent.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAEI;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;OAOG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;;;;;;OAQG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;OAKG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAOhC;IAED;;;;;;;;;;;;;;OAcG;IACH,2BANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACL,MAAM,CAQjB;IAED;;;OAGG;IACH,cAHW,cAAc,GACb,OAAO,CAoBlB;IAED;;OAEG;IACH,QAFY,MAAM,CAgBjB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iCAmBC;IAGL,0BAAyC;CAFxC;2BA/P0B,kBAAkB"}

package/src/engine/physics/fluid/ecs/FluidComponent.js

@@ -214,24 +214,45 @@ export class FluidComponent {
 
     /**
      * Write the field's world-space axis-aligned bounding box into `out`. Used by
-     * {@link FluidSystem} as a broad-phase target when filtering effectors. The box
-     * spans cell `(0, 0, 0)` (centred at `origin`) to cell `(res_x-1, res_y-1, res_z-1)`
-     * plus a `cell_size` margin on the far side, so a point exactly on the field's
-     * boundary cells lies inside the AABB.
+     * {@link FluidSystem} and {@link WorkerFluidSystem} as the broad-phase target when
+     * filtering effectors.
+     *
+     * `origin` is cell `(0,0,0)`'s CENTRE, so the occupied volume runs from
+     * `origin - cell_size/2` to `origin + (res - 0.5) * cell_size`. The box is that
+     * volume plus one `cell_size` on every side.
+     *
+     * The margin is not slack. An effector's own AABB is its position expanded by its
+     * USER radius, while the splat floors the effective kernel at one grid cell
+     * ({@link ImpulseFluidEffector}), so a sub-cell-radius source deposits up to a cell
+     * further than its AABB reaches. Covering that here is what keeps the broad-phase
+     * conservative: a false positive costs one wasted splat, a false negative is a fan
+     * that silently stops working.
+     *
+     * This used to write `[origin, origin + res * cell_size]` — a full cell of slack
+     * past the far side and NONE at all on the near one — so a source placed within half
+     * a cell outside the near face was dropped for this field entirely while the same
+     * source on the far side worked.
      *
      * @param {AABB3} out
      */
     getBoundingBox(out) {
         const res = this.field.getResolution();
         const cs = this.cell_size;
+
+        // half a cell to the face of cell 0, then one cell of kernel-clamp margin
+        const margin = cs * 1.5;
+
         const ox = this.origin[0];
         const oy = this.origin[1];
         const oz = this.origin[2];
+
         out.setBounds(
-            ox, oy, oz,
-            ox + res[0] * cs,
-            oy + res[1] * cs,
-            oz + res[2] * cs
+            ox - margin,
+            oy - margin,
+            oz - margin,
+            ox + (res[0] - 1) * cs + margin,
+            oy + (res[1] - 1) * cs + margin,
+            oz + (res[2] - 1) * cs + margin
         );
     }
 }

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#403@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#416@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#403@#clear_field"(fluid: FluidComponent): void;
+    static "__#416@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#403@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#416@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#403@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#416@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/engine/physics/fluid/effector/AbstractFluidEffector.d.ts

@@ -16,6 +16,14 @@
  * dt, matrix). They must not retain references to field buffers between calls (the
  * field's buffer references are stable, but caching them across resolution changes
  * would break).
+ *
+ * One stated exception: a MANUALLY driven {@link WakeFluidEffector} advances its own
+ * trail at the end of `apply`, because a source positioned by hand outside the ECS
+ * has nothing else to advance it. That mode hands the segment to whichever field
+ * steps first and a zero segment to the rest, so pair it with a single field —
+ * driving the same effector from a `Transform64` advances the trail in
+ * `syncFromTransform` instead and every overlapping field receives the same wake.
+ * See the {@link WakeFluidEffector} class docstring.
  */
 export class AbstractFluidEffector {
     /**

package/src/engine/physics/fluid/effector/AbstractFluidEffector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/AbstractFluidEffector.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IACI;;;;;;OAMG;IACH,6BALW,MAAM,iBACN,YAAY,GAAC,MAAM,EAAE,QAO/B;IAED;;;;;;;OAOG;IACH,gDAEC;IAED;;;;;;OAMG;IACH,cAHW,qBAAqB,GACpB,OAAO,CAIlB;IAED;;;;;OAKG;IACH,QAFY,MAAM,CAIjB;IAED;;;;;;;;;;;OAWG;IACH,iCAEC;CACJ"}
+{"version":3,"file":"AbstractFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/AbstractFluidEffector.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IACI;;;;;;OAMG;IACH,6BALW,MAAM,iBACN,YAAY,GAAC,MAAM,EAAE,QAO/B;IAED;;;;;;;OAOG;IACH,gDAEC;IAED;;;;;;OAMG;IACH,cAHW,qBAAqB,GACpB,OAAO,CAIlB;IAED;;;;;OAKG;IACH,QAFY,MAAM,CAIjB;IAED;;;;;;;;;;;OAWG;IACH,iCAEC;CACJ"}

package/src/engine/physics/fluid/effector/AbstractFluidEffector.js

@@ -16,6 +16,14 @@
  * dt, matrix). They must not retain references to field buffers between calls (the
  * field's buffer references are stable, but caching them across resolution changes
  * would break).
+ *
+ * One stated exception: a MANUALLY driven {@link WakeFluidEffector} advances its own
+ * trail at the end of `apply`, because a source positioned by hand outside the ECS
+ * has nothing else to advance it. That mode hands the segment to whichever field
+ * steps first and a zero segment to the rest, so pair it with a single field —
+ * driving the same effector from a `Transform64` advances the trail in
+ * `syncFromTransform` instead and every overlapping field receives the same wake.
+ * See the {@link WakeFluidEffector} class docstring.
  */
 export class AbstractFluidEffector {
     /**