@woosh/meep-engine 3.9.0 → 3.11.0

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

@@ -23,15 +23,20 @@ export class PhysicsSystem extends System<any> {
     dependencies: (typeof Transform | typeof RigidBody)[];
     components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider>)[];
     /**
+     * Body slots, the awake / sleeping sets, and generation counters.
      * @type {BodyStorage}
      * @readonly
      */
     readonly storage: BodyStorage;
     /**
+     * Broadphase tree holding every static collider leaf. The step never
+     * refits it — statics do not move.
      * @type {BVH}
      */
     staticBvh: BVH;
     /**
+     * Broadphase tree holding every dynamic and kinematic collider leaf.
+     * Leaves carry a velocity-fattened AABB and are refit each step.
      * @type {BVH}
      */
     dynamicBvh: BVH;
@@ -43,9 +48,8 @@ export class PhysicsSystem extends System<any> {
     readonly manifolds: ManifoldStore;
     /**
      * Per-frame list of broadphase-overlapping pairs, each in
-     * entity-canonical role order (A = the smaller entity id — see
-     * generate_pairs). Cleared at the top of each step; purely
-     * intra-step state.
+     * entity-canonical role order (A = the smaller entity id). Cleared at
+     * the top of each step.
      * @type {PairList}
      */
     pairs: PairList;
@@ -56,11 +60,9 @@ export class PhysicsSystem extends System<any> {
      */
     contactEvents: ContactEventBuffer;
     /**
-     * Per-frame island partitioning of the awake-body + contact graph.
-     * Rebuilt after narrowphase, consumed by the solver (and, in the
-     * follow-up slice, by the per-island atomic sleep test). Bodies
-     * static and kinematic act as constraint anchors and do not enlarge
-     * islands.
+     * Per-frame island partitioning of the awake-body + contact graph,
+     * consumed by the solver and the sleep test. Static and kinematic
+     * bodies act as constraint anchors and do not enlarge islands.
      * @type {IslandBuilder}
      */
     islands: IslandBuilder;
@@ -91,14 +93,9 @@ export class PhysicsSystem extends System<any> {
     sleepTimeThreshold: number;
     /**
      * Number of TGS substeps per `fixedUpdate`. Each substep re-runs the
-     * velocity + position solve at `dt / substeps` against contacts whose
-     * penetration is re-derived analytically from the bodies' moved poses
-     * — narrowphase still runs once per outer step. Higher counts buy
-     * stack stability, high-mass-ratio robustness, and smoother
-     * trajectories at a near-linear solver cost (sleeping islands are
-     * unaffected — they never enter the loop).
-     *
-     * `1` reproduces the non-substepped (single-step) solve.
+     * velocity + position solve at `dt / substeps`. Higher counts buy stack
+     * stability, high-mass-ratio robustness and smoother trajectories, at
+     * near-linear solver cost. `1` gives a plain single-step solve.
      * @type {number}
      */
     substeps: number;
@@ -115,15 +112,12 @@ export class PhysicsSystem extends System<any> {
      */
     positionIterations: number;
     /**
-     * Contact softness frequency, Hz (Box2D-v3 soft step, hybrid form:
-     * the velocity rows get the hertz/ζ-derived mass + impulse-decay
-     * scales; penetration recovery stays in the split-impulse position
-     * pass). The decay term is what lets resting stacks converge
-     * asymptotically instead of ringing in the hard form's limit cycle
-     * just above the sleep threshold. Clamped per step to an eighth of
-     * the substep rate. `0` = hard contacts (bit-exact legacy rows).
-     * Pairs with a non-dynamic side use 2× this frequency (stiffer, so
-     * piles don't sag into the ground). @type {number}
+     * Contact softness frequency, Hz. Softening is what lets resting stacks
+     * settle instead of ringing just above the sleep threshold; `0` gives
+     * hard contacts. Clamped per step to an eighth of the substep rate.
+     * Pairs with a non-dynamic side use 2× this frequency — stiffer, so
+     * piles don't sag into the ground.
+     * @type {number}
      */
     contactHertz: number;
     /**
@@ -186,9 +180,11 @@ export class PhysicsSystem extends System<any> {
      */
     __joints: Joint[];
     /**
-     * Lowest free index in {@link __joints} for slot reuse on link.
+     * Freed {@link __joints} slot ids, reused LIFO by {@link link_joint} so
+     * ids stay dense. Solve order does not follow it — {@link __joints_sorted}
+     * owns that.
      * @private
-     * @type {number}
+     * @type {number[]}
      */
     private __joint_free;
     /**
@@ -248,13 +244,11 @@ export class PhysicsSystem extends System<any> {
      */
     __ccd_start_pos: Float64Array;
     /**
-     * Optional shared interpolation log to produce per-step pose snapshots
-     * into (the {@link InterpolationSystem}'s log). When set — and only then —
-     * each fixedUpdate restores every awake {@link Interpolated} body's live
-     * components from the previous tick (undoing render-time interpolation so
-     * the sim reads authoritative state), then records the post-step state
-     * under the current `entityManager.fixedStepTick`. Null on a headless /
-     * non-rendering world, where the producer work is skipped entirely.
+     * 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: InterpolationLog | null;
@@ -569,10 +563,10 @@ export class PhysicsSystem extends System<any> {
      * as-is; zero it via {@link setLinearVelocity} if the teleport should also
      * stop the body.
      *
-     * Works for STATIC bodies too: their broadphase leaves (which the step
-     * never refits) are re-homed to the new pose, and sleeping bodies at both
-     * the old and the new location are woken — a moved support drops what
-     * rested on it, and whatever the static moved into must react.
+     * 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
+     * woken — a moved support drops what rested on it, and whatever it moved
+     * into must react.
      *
      * @param {RigidBody} rigidBody
      * @param {Vector3|{x:number,y:number,z:number}} position world position
@@ -632,13 +626,13 @@ export class PhysicsSystem extends System<any> {
      */
     private __atomic_sleep_island_range;
     /**
-     * Broadphase raycast against both BVHs. Fills `result` with the nearest
+     * Raycast against both broadphase trees. Fills `result` with the nearest
      * hit and returns `true` on hit, `false` on miss.
      *
-     * Narrowphase refinement against the actual shape geometry is a
-     * follow-up — for now `result.t` is the distance to the leaf's
-     * inflated AABB and `result.normal` is the AABB face normal. Both are
-     * exact for AABB-shaped colliders.
+     * Resolves to the BVH leaf, not the shape: `result.t` is the distance to
+     * the leaf's inflated AABB and `result.normal` is that AABB's face
+     * normal. Exact for AABB-shaped colliders, approximate for the rest —
+     * use {@link shapeCast} when you need the true surface.
      *
      * @param {Ray3} ray  origin + unit direction + `tMax`
      * @param {PhysicsSurfacePoint} result populated on hit; untouched on miss
@@ -648,17 +642,12 @@ export class PhysicsSystem extends System<any> {
      */
     raycast(ray: Ray3, result: PhysicsSurfacePoint, filter?: (entity: number, collider: Collider) => boolean): boolean;
     /**
-     * Sweep a convex shape along a ray and find the first body it
-     * would hit. The shape starts at `ray.origin` oriented by
-     * `rotation` and translates along `ray.direction` for up to
-     * `ray.tMax` units. Returns the nearest impact within that
-     * interval.
+     * Sweep a convex shape along a ray and return the first body it hits.
+     * The shape starts at `ray.origin` oriented by `rotation` and translates
+     * along `ray.direction` for up to `ray.tMax` units.
      *
-     * The "swept AABB" broadphase finds candidate bodies whose BVH
-     * leaves overlap the shape's swept volume; the narrowphase then
-     * bisects [0, t] on GJK overlap to find the time-of-impact for
-     * each candidate. Best-t early termination skips candidates that
-     * can't tighten the answer.
+     * Unlike {@link raycast} this resolves against the real shapes, so `t` is
+     * a true time of impact rather than a distance to a bounding box.
      *
      * @param {Ray3} ray  origin + unit direction + `tMax`
      * @param {AbstractShape3D} shape
@@ -674,33 +663,20 @@ export class PhysicsSystem extends System<any> {
         w: number;
     }, result: PhysicsSurfacePoint, filter?: (entity: number, collider: Collider) => boolean): boolean;
     /**
-     * Speculative overlap query: find all bodies whose collider would
-     * overlap the given convex shape placed at the given world pose,
-     * without mutating the simulation. Intended for kinematic /
-     * character controllers that need to test "would I collide if I
-     * moved here?" before committing the move.
-     *
-     * Pipeline:
-     *   1. The shape's world AABB is computed from `position` + `rotation`.
-     *   2. Both broadphase trees (static + dynamic) are queried for
-     *      bodies whose leaf AABB overlaps that envelope.
-     *   3. Each candidate is GJK-tested in world frame. Convex
-     *      candidates run one GJK call; concave candidates (heightmap,
-     *      mesh) run per-triangle GJK via the decomposition path.
-     *   4. The optional `filter` is consulted before the GJK test —
-     *      useful for skipping the caller's own body, allies, sensors,
-     *      etc.
-     *
-     * The output buffer is filled with overlapping bodies' `body_id`
-     * values (uint32 with packed generation), starting at
-     * `output_offset`. The caller is responsible for sizing the buffer;
-     * IDs past its end are dropped silently and the count caps at the
-     * available space.
-     *
-     * The query shape must be convex. Concave query shapes throw —
-     * they're typically static terrain and not used as kinematic
-     * probes; the M×N triangle-pair cost wouldn't be worth the rare
-     * use case.
+     * Find every body whose collider overlaps the given convex shape at the
+     * given world pose, without mutating the simulation. Intended for
+     * kinematic / character controllers testing "would I collide if I moved
+     * here?" before committing the move.
+     *
+     * Writes overlapping bodies' packed `body_id` values into `output` from
+     * `output_offset`. Sizing the buffer is the caller's job: ids past its
+     * end are dropped silently and the returned count caps at the space
+     * available.
+     *
+     * `filter` runs before the shape test, which is the expensive part — use
+     * it to skip the caller's own body, allies, sensors.
+     *
+     * The query shape must be convex; a concave one throws.
      *
      * @param {AbstractShape3D} shape convex query shape, in its local frame
      * @param {{x:number,y:number,z:number}} position world position of
@@ -723,6 +699,19 @@ export class PhysicsSystem extends System<any> {
         z: number;
         w: number;
     }, output: Uint32Array | number[], output_offset: number, filter?: (entity: number, collider: Collider) => boolean): number;
+    /**
+     * Re-shape both broadphase trees so subsequent queries — {@link raycast},
+     * {@link shapeCast}, {@link overlap}, and the per-step broadphase — walk
+     * fewer nodes.
+     *
+     * Call it once after a level's statics are linked. Statics keep the win
+     * for good (~12% fewer nodes visited); the dynamic tree's fades within
+     * seconds as bodies move, so repeat calls are not worth scheduling. Costs
+     * ~20 ms for 4000 bodies — a load-time operation, not a per-frame one.
+     *
+     * @returns {void}
+     */
+    optimize(): void;
     /**
      * Wake propagation through contact pairs. Runs BEFORE broadphase so a
      * body woken here participates in THIS frame's broadphase / narrowphase
@@ -849,7 +838,6 @@ export class PhysicsSystem extends System<any> {
      * @private
      */
     private __interp_record;
-    fixedUpdate(dt: any): void;
     /**
      * @readonly
      * @type {boolean}

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

@@ -1 +1 @@
-{"version":3,"file":"PhysicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsSystem.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"PhysicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsSystem.js"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,7 @@
 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 {
     bvh_query_user_data_intersects_aabb
 } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_aabb.js";
@@ -129,17 +130,22 @@ export class PhysicsSystem extends System {
     ];
 
     /**
+     * Body slots, the awake / sleeping sets, and generation counters.
      * @type {BodyStorage}
      * @readonly
      */
     storage = new BodyStorage();
 
     /**
+     * Broadphase tree holding every static collider leaf. The step never
+     * refits it — statics do not move.
      * @type {BVH}
      */
     staticBvh = new BVH();
 
     /**
+     * Broadphase tree holding every dynamic and kinematic collider leaf.
+     * Leaves carry a velocity-fattened AABB and are refit each step.
      * @type {BVH}
      */
     dynamicBvh = new BVH();
@@ -153,9 +159,8 @@ export class PhysicsSystem extends System {
 
     /**
      * Per-frame list of broadphase-overlapping pairs, each in
-     * entity-canonical role order (A = the smaller entity id — see
-     * generate_pairs). Cleared at the top of each step; purely
-     * intra-step state.
+     * entity-canonical role order (A = the smaller entity id). Cleared at
+     * the top of each step.
      * @type {PairList}
      */
     pairs = new PairList();
@@ -168,11 +173,9 @@ export class PhysicsSystem extends System {
     contactEvents = new ContactEventBuffer();
 
     /**
-     * Per-frame island partitioning of the awake-body + contact graph.
-     * Rebuilt after narrowphase, consumed by the solver (and, in the
-     * follow-up slice, by the per-island atomic sleep test). Bodies
-     * static and kinematic act as constraint anchors and do not enlarge
-     * islands.
+     * Per-frame island partitioning of the awake-body + contact graph,
+     * consumed by the solver and the sleep test. Static and kinematic
+     * bodies act as constraint anchors and do not enlarge islands.
      * @type {IslandBuilder}
      */
     islands = new IslandBuilder();
@@ -207,14 +210,9 @@ export class PhysicsSystem extends System {
 
     /**
      * Number of TGS substeps per `fixedUpdate`. Each substep re-runs the
-     * velocity + position solve at `dt / substeps` against contacts whose
-     * penetration is re-derived analytically from the bodies' moved poses
-     * — narrowphase still runs once per outer step. Higher counts buy
-     * stack stability, high-mass-ratio robustness, and smoother
-     * trajectories at a near-linear solver cost (sleeping islands are
-     * unaffected — they never enter the loop).
-     *
-     * `1` reproduces the non-substepped (single-step) solve.
+     * velocity + position solve at `dt / substeps`. Higher counts buy stack
+     * stability, high-mass-ratio robustness and smoother trajectories, at
+     * near-linear solver cost. `1` gives a plain single-step solve.
      * @type {number}
      */
     substeps = 4;
@@ -234,15 +232,12 @@ export class PhysicsSystem extends System {
     positionIterations = 1;
 
     /**
-     * Contact softness frequency, Hz (Box2D-v3 soft step, hybrid form:
-     * the velocity rows get the hertz/ζ-derived mass + impulse-decay
-     * scales; penetration recovery stays in the split-impulse position
-     * pass). The decay term is what lets resting stacks converge
-     * asymptotically instead of ringing in the hard form's limit cycle
-     * just above the sleep threshold. Clamped per step to an eighth of
-     * the substep rate. `0` = hard contacts (bit-exact legacy rows).
-     * Pairs with a non-dynamic side use 2× this frequency (stiffer, so
-     * piles don't sag into the ground). @type {number}
+     * Contact softness frequency, Hz. Softening is what lets resting stacks
+     * settle instead of ringing just above the sleep threshold; `0` gives
+     * hard contacts. Clamped per step to an eighth of the substep rate.
+     * Pairs with a non-dynamic side use 2× this frequency — stiffer, so
+     * piles don't sag into the ground.
+     * @type {number}
      */
     contactHertz = 30;
 
@@ -316,9 +311,11 @@ export class PhysicsSystem extends System {
     __joints = [];
 
     /**
-     * Lowest free index in {@link __joints} for slot reuse on link.
+     * Freed {@link __joints} slot ids, reused LIFO by {@link link_joint} so
+     * ids stay dense. Solve order does not follow it — {@link __joints_sorted}
+     * owns that.
      * @private
-     * @type {number}
+     * @type {number[]}
      */
     __joint_free = [];
 
@@ -384,13 +381,11 @@ export class PhysicsSystem extends System {
     __ccd_start_pos = new Float64Array(0);
 
     /**
-     * Optional shared interpolation log to produce per-step pose snapshots
-     * into (the {@link InterpolationSystem}'s log). When set — and only then —
-     * each fixedUpdate restores every awake {@link Interpolated} body's live
-     * components from the previous tick (undoing render-time interpolation so
-     * the sim reads authoritative state), then records the post-step state
-     * under the current `entityManager.fixedStepTick`. Null on a headless /
-     * non-rendering world, where the producer work is skipped entirely.
+     * 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;
@@ -1083,10 +1078,10 @@ export class PhysicsSystem extends System {
      * as-is; zero it via {@link setLinearVelocity} if the teleport should also
      * stop the body.
      *
-     * Works for STATIC bodies too: their broadphase leaves (which the step
-     * never refits) are re-homed to the new pose, and sleeping bodies at both
-     * the old and the new location are woken — a moved support drops what
-     * rested on it, and whatever the static moved into must react.
+     * 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
+     * woken — a moved support drops what rested on it, and whatever it moved
+     * into must react.
      *
      * @param {RigidBody} rigidBody
      * @param {Vector3|{x:number,y:number,z:number}} position world position
@@ -1297,13 +1292,13 @@ export class PhysicsSystem extends System {
     }
 
     /**
-     * Broadphase raycast against both BVHs. Fills `result` with the nearest
+     * Raycast against both broadphase trees. Fills `result` with the nearest
      * hit and returns `true` on hit, `false` on miss.
      *
-     * Narrowphase refinement against the actual shape geometry is a
-     * follow-up — for now `result.t` is the distance to the leaf's
-     * inflated AABB and `result.normal` is the AABB face normal. Both are
-     * exact for AABB-shaped colliders.
+     * Resolves to the BVH leaf, not the shape: `result.t` is the distance to
+     * the leaf's inflated AABB and `result.normal` is that AABB's face
+     * normal. Exact for AABB-shaped colliders, approximate for the rest —
+     * use {@link shapeCast} when you need the true surface.
      *
      * @param {Ray3} ray  origin + unit direction + `tMax`
      * @param {PhysicsSurfacePoint} result populated on hit; untouched on miss
@@ -1316,17 +1311,12 @@ export class PhysicsSystem extends System {
     }
 
     /**
-     * Sweep a convex shape along a ray and find the first body it
-     * would hit. The shape starts at `ray.origin` oriented by
-     * `rotation` and translates along `ray.direction` for up to
-     * `ray.tMax` units. Returns the nearest impact within that
-     * interval.
+     * Sweep a convex shape along a ray and return the first body it hits.
+     * The shape starts at `ray.origin` oriented by `rotation` and translates
+     * along `ray.direction` for up to `ray.tMax` units.
      *
-     * The "swept AABB" broadphase finds candidate bodies whose BVH
-     * leaves overlap the shape's swept volume; the narrowphase then
-     * bisects [0, t] on GJK overlap to find the time-of-impact for
-     * each candidate. Best-t early termination skips candidates that
-     * can't tighten the answer.
+     * Unlike {@link raycast} this resolves against the real shapes, so `t` is
+     * a true time of impact rather than a distance to a bounding box.
      *
      * @param {Ray3} ray  origin + unit direction + `tMax`
      * @param {AbstractShape3D} shape
@@ -1340,33 +1330,20 @@ export class PhysicsSystem extends System {
     }
 
     /**
-     * Speculative overlap query: find all bodies whose collider would
-     * overlap the given convex shape placed at the given world pose,
-     * without mutating the simulation. Intended for kinematic /
-     * character controllers that need to test "would I collide if I
-     * moved here?" before committing the move.
+     * Find every body whose collider overlaps the given convex shape at the
+     * given world pose, without mutating the simulation. Intended for
+     * kinematic / character controllers testing "would I collide if I moved
+     * here?" before committing the move.
      *
-     * Pipeline:
-     *   1. The shape's world AABB is computed from `position` + `rotation`.
-     *   2. Both broadphase trees (static + dynamic) are queried for
-     *      bodies whose leaf AABB overlaps that envelope.
-     *   3. Each candidate is GJK-tested in world frame. Convex
-     *      candidates run one GJK call; concave candidates (heightmap,
-     *      mesh) run per-triangle GJK via the decomposition path.
-     *   4. The optional `filter` is consulted before the GJK test —
-     *      useful for skipping the caller's own body, allies, sensors,
-     *      etc.
+     * Writes overlapping bodies' packed `body_id` values into `output` from
+     * `output_offset`. Sizing the buffer is the caller's job: ids past its
+     * end are dropped silently and the returned count caps at the space
+     * available.
      *
-     * The output buffer is filled with overlapping bodies' `body_id`
-     * values (uint32 with packed generation), starting at
-     * `output_offset`. The caller is responsible for sizing the buffer;
-     * IDs past its end are dropped silently and the count caps at the
-     * available space.
+     * `filter` runs before the shape test, which is the expensive part — use
+     * it to skip the caller's own body, allies, sensors.
      *
-     * The query shape must be convex. Concave query shapes throw —
-     * they're typically static terrain and not used as kinematic
-     * probes; the M×N triangle-pair cost wouldn't be worth the rare
-     * use case.
+     * The query shape must be convex; a concave one throws.
      *
      * @param {AbstractShape3D} shape convex query shape, in its local frame
      * @param {{x:number,y:number,z:number}} position world position of
@@ -1383,6 +1360,24 @@ export class PhysicsSystem extends System {
         return overlap_shape_query(this, shape, position, rotation, output, output_offset, filter);
     }
 
+    /**
+     * Re-shape both broadphase trees so subsequent queries — {@link raycast},
+     * {@link shapeCast}, {@link overlap}, and the per-step broadphase — walk
+     * fewer nodes.
+     *
+     * Call it once after a level's statics are linked. Statics keep the win
+     * for good (~12% fewer nodes visited); the dynamic tree's fades within
+     * seconds as bodies move, so repeat calls are not worth scheduling. Costs
+     * ~20 ms for 4000 bodies — a load-time operation, not a per-frame one.
+     *
+     * @returns {void}
+     */
+    optimize() {
+        // empty and single-leaf trees are a no-op inside the optimizer
+        ebvh_optimize_treelet(this.staticBvh);
+        ebvh_optimize_treelet(this.dynamicBvh);
+    }
+
     /**
      * Wake propagation through contact pairs. Runs BEFORE broadphase so a
      * body woken here participates in THIS frame's broadphase / narrowphase
@@ -1893,6 +1888,17 @@ export class PhysicsSystem extends System {
         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.
+     * Reads and writes the linked {@link RigidBody} and {@link Transform}
+     * components in place.
+     *
+     * Pass the same `dt` every step — warm-starting and sleep timing both
+     * assume a fixed rate.
+     *
+     * @param {number} dt seconds
+     */
     fixedUpdate(dt) {
         // Producer: restore authoritative pose (undo render interpolation)
         // before the sim reads any Transform this step.

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

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#349@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#354@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#349@#clear_field"(fluid: FluidComponent): void;
+    static "__#354@#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 "__#349@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#354@#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 "__#349@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#354@#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 Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];