@woosh/meep-engine 3.38.0 → 3.39.0

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

@@ -78,10 +78,20 @@ export class PhysicsSystem extends System<any> {
      */
     __solver_state: SolverBodyState;
     /**
-     * Velocity-squared threshold below which a body is eligible to start
-     * accumulating sleep time. Combined linear + angular kinetic-ish
-     * metric: `vx²+vy²+vz² + ωx²+ωy²+ωz²`. Default 0.01 corresponds to
-     * ~0.1 m/s linear or ~0.1 rad/s angular.
+     * Speed-squared threshold, (m/s)², below which a body is eligible to start
+     * accumulating sleep time. The speed measured is that of the body's far
+     * end, `|v|² + |ω|²·R²`, where `R` is the body's extent
+     * ({@link __body_extent}: a bound on how far its colliders reach from its
+     * centre, from their local bounding boxes) floored at 1 m. Default 0.01
+     * corresponds to ~0.1 m/s linear; for a body whose extent is no more than
+     * a metre, ~0.1 rad/s angular, exactly as before the extent was counted;
+     * for a larger one, ~0.1 m/s at its far end (a 100 m rod turning at
+     * 0.05 rad/s is moving 5 m/s at the tip, and stays awake).
+     *
+     * The far end of a long body magnifies any wobble of its contacts, and the
+     * test sees it at full size: a long plank resting on a bumpy mesh or
+     * heightmap floor whose contacts jitter can stay awake where a short body
+     * would sleep.
      * @type {number}
      */
     sleepVelocitySqrThreshold: number;
@@ -111,6 +121,46 @@ export class PhysicsSystem extends System<any> {
      * @type {number}
      */
     positionIterations: number;
+    /**
+     * Restitution passes per step, after the substep loop: Gauss-Seidel sweeps
+     * over the contacts with non-zero restitution, each driving a bouncing
+     * contact's normal velocity toward `-e` times its approach. A body that
+     * strikes at several points at once needs more than one: after a single
+     * pass, a cube dropped flat at e = 0.8 left the ground spinning at 5 rad/s
+     * and rebounded at 0.77 of its impact speed instead of 0.8. Two (Box3D's
+     * default) bring it within half a percent of 0.8, all but without spin.
+     * Each contact's bounce is capped at `e` times the impulse it took, which
+     * stops an unconverged pass overshooting: in zero gravity, uncapped, one
+     * pass sent a cube tumbling onto frictionless ground at e = 1 off with up
+     * to 7% more kinetic energy than it struck with; capped, 0.2% at worst.
+     * More passes still change the result, not just the cost: they converge
+     * contacts that load each other further — an e = 1 stack of four boxes
+     * struck by a ball keeps 201 J of its 309 J after 10 s at 2 passes, 88 J
+     * at 8. `0` turns restitution off.
+     *
+     * Under gravity a bounce can still gain energy, mostly not from these
+     * passes: a landing body is corrected out of the depth it sank into the
+     * ground — by the penetration bias with soft contacts, by the position pass
+     * with hard ones — and that lift is potential energy, while restitution
+     * still returns the full approach speed. Tumbling cubes landing on
+     * frictionless ground at e = 1, 60 drops of 5 s: no drop gains at all at
+     * the defaults (soft contacts, 2 passes, 4 substeps); 22 gain over 0.1%
+     * at 8 substeps
+     * (worst +0.64%: the contact is stiffer against the shorter substep and
+     * recovers more depth); with hard contacts 53 (+2.2%), and +6.4% at 8
+     * substeps. At 2 passes, turning off the bias, the position pass or
+     * restitution leaves none gaining. At 1 pass 8 gain (+2.2%), and the pass
+     * itself is part of it: with the bias off, 4 still gain (+0.8%).
+     * @type {number}
+     */
+    restitutionIterations: number;
+    /**
+     * Approach speed, m/s, below which a contact does not bounce whatever its
+     * restitution, so resting and slowly settling bodies do not buzz. The
+     * discrete solver and the CCD pass apply the same rule.
+     * @type {number}
+     */
+    restitutionThreshold: number;
     /**
      * Contact softness frequency, Hz. Softening is what lets resting stacks
      * settle instead of ringing just above the sleep threshold; `0` gives
@@ -207,10 +257,14 @@ export class PhysicsSystem extends System<any> {
      */
     private __joints_sorted;
     /**
-     * Velocity iterations per substep for the joint solver. Joints (and
-     * especially joint chains) want a few more iterations than contacts to
-     * propagate impulses along the chain; cheap because joints are far
-     * fewer than contacts.
+     * Joint solver passes per substep. Each pass is one Gauss-Seidel sweep over
+     * every joint, so joints that load each other — a chain, a ragdoll limb, a
+     * heavy body on a light rope — converge together: more passes, tighter
+     * joints under load. The first pass also warm-starts each joint; a relax
+     * pass over the limit / motor / spring rows after the position integrate
+     * comes on top. Cost is passes × joints; cheap because joints are far fewer
+     * than contacts. 0 turns the joint solver off, relax included: the joints
+     * still tie their bodies' islands together, but push on nothing.
      * @type {number}
      */
     jointIterations: number;
@@ -218,13 +272,13 @@ export class PhysicsSystem extends System<any> {
      * Per-body pseudo-velocity for the Catto split-impulse position
      * pass (TGS Phase 1). Flat layout, 6 doubles per body slot index:
      * `[lin.x, lin.y, lin.z, ang.x, ang.y, ang.z]`. Sized to
-     * `storage.high_water_mark * 6` at the top of each fixedUpdate
-     * and zeroed in place so unwritten slots contribute nothing to
-     * `integrate_position`.
+     * `storage.high_water_mark * 6` at the top of each fixedUpdate, and
+     * zero wherever `integrate_position` reads it unless a position pass
+     * wrote it this substep, so unwritten slots contribute nothing.
      *
      * The solver writes during its position pass; `integrate_position`
-     * reads and folds into the pose update on the same tick, then
-     * the next tick's zero-pass wipes the state. It NEVER lands in
+     * reads and folds into the pose update on the same substep, and the
+     * next substep wipes it first. It NEVER lands in
      * `linearVelocity` / `angularVelocity` — that's the point of
      * split impulse: depth correction does not contaminate persistent
      * velocity (so a `restitution = 0` impact stops cleanly).
@@ -232,6 +286,20 @@ export class PhysicsSystem extends System<any> {
      * @type {Float64Array}
      */
     __pseudo_velocity: Float64Array;
+    /**
+     * Length of the prefix of {@link __pseudo_velocity} that a position pass
+     * may have written since it was last zeroed; everything past it is zero.
+     * Set by the hard-contact position pass of {@link fixedUpdate} and of the
+     * `solve_contacts` driver. `0` when the whole buffer is zero — always,
+     * with soft contacts (the default), which run no position pass. The wipes
+     * zero this prefix only, and only when it is non-empty: zeroing the whole
+     * buffer every substep cost work proportional to the body-slot
+     * high-water mark, not to the bodies awake — most of a 0.6 ms step at
+     * 100k slots with ten awake.
+     * @private
+     * @type {number}
+     */
+    private __pseudo_velocity_dirty;
     /**
      * Master switch for the continuous-collision pass. When false the
      * {@link RigidBodyFlags.CCD} flag is ignored and no swept queries run.
@@ -247,6 +315,77 @@ export class PhysicsSystem extends System<any> {
      * @type {Float64Array}
      */
     __ccd_start_pos: Float64Array;
+    /**
+     * Start-of-step linear velocities of the awake DYNAMIC bodies — every one,
+     * not only the CCD-flagged — captured with {@link __ccd_start_pos} (after
+     * forces, before the substep loop) in any step with a flagged body awake;
+     * 3 doubles per body slot index. The CCD pass replaces each with the
+     * body's velocity change through the solve, which tells it how a body it
+     * struck fell through the step.
+     * @type {Float64Array}
+     */
+    __ccd_start_vel: Float64Array;
+    /**
+     * The CCD movers of the current step: storage indices of the bodies whose
+     * start pose {@link __ccd_start_pos} took this step, the first
+     * {@link __ccd_mover_count} of them. The CCD pass sweeps these and no
+     * others — a body made a mover after the capture, by a listener on an
+     * announcement, has no start pose this step. Grows by doubling.
+     * @type {Uint32Array}
+     */
+    __ccd_movers: Uint32Array;
+    /**
+     * Beside each of {@link __ccd_movers}, the collider its start pose was
+     * taken from, its body's primary at the time; a mover whose primary
+     * collider has changed since is not swept this step.
+     * @type {Array<Collider|null>}
+     */
+    __ccd_mover_colliders: Array<Collider | null>;
+    /**
+     * Number of live entries in {@link __ccd_movers}.
+     * @type {number}
+     */
+    __ccd_mover_count: number;
+    /**
+     * Per-body extent, metres, indexed by body slot: a bound on the distance
+     * from the body's centre to any point of its colliders — the largest, over
+     * its colliders, of the local bounding box's corner radius plus the
+     * collider's offset from the body. Exact for a box centred on its body;
+     * larger than the body for other shapes (a sphere of radius r reads
+     * r·√3). Written for every awake body in stage 2 of each
+     * step, from the step's starting poses, and read by the sleep test to
+     * turn angular velocity into the speed of the body's far end. Rotation
+     * invariant (local boxes, not world ones), so a body's orientation does
+     * not change when it may sleep. Derived state: recomputed each step,
+     * never serialized. Grows to `storage.high_water_mark`.
+     * @type {Float64Array}
+     */
+    __body_extent: Float64Array;
+    /**
+     * Pending {@link setTargetPose} targets, {@link TARGET_POSE_STRIDE} doubles per body slot
+     * index: the packed id of the body that set the target ({@link RIGID_BODY_UNALLOCATED} for
+     * none), then position `[x, y, z]` and rotation `[x, y, z, w]`. Keyed by the packed id rather
+     * than a flag, so a slot freed and reused by another body before the step never inherits a
+     * target. Grows to cover the slots targets are set on; never shrinks.
+     * @private
+     * @type {Float64Array}
+     */
+    private __target_poses;
+    /**
+     * Packed ids of the bodies holding a pending target in {@link __target_poses}, in call order:
+     * the first {@link __target_pose_count}. Consumed and emptied by the next {@link fixedUpdate},
+     * which resets the count and keeps the array's storage — truncating it gave the storage up, and
+     * the next step's first target allocated it again.
+     * @private
+     * @type {number[]}
+     */
+    private __target_pose_bodies;
+    /**
+     * How many of {@link __target_pose_bodies} are pending.
+     * @private
+     * @type {number}
+     */
+    private __target_pose_count;
     set interpolationLog(log: any);
     /**
      * **Deprecated; does nothing.** Physics used to produce render interpolation itself: with this
@@ -306,16 +445,24 @@ export class PhysicsSystem extends System<any> {
     private __primary_collider;
     /**
      * Resize {@link __pseudo_velocity} to cover every live body slot and
-     * zero its contents. Called at the top of each fixedUpdate so the
-     * split-impulse position pass starts from a clean state — bodies the
-     * solver doesn't touch contribute zero pseudo-velocity to
-     * {@link integrate_position}.
+     * bring it to all-zero, zeroing only what a position pass may have
+     * written since it last was ({@link __pseudo_velocity_dirty}), so bodies
+     * the solver doesn't touch contribute zero pseudo-velocity to
+     * {@link integrate_position}. Called at the top of each fixedUpdate, and
+     * by a caller of the `solve_contacts` driver whose buffer may hold a
+     * hard-contact step's last correction.
      *
      * Doubles on growth like the other physics scratches; never shrinks.
      *
      * @private
      */
     private __reset_pseudo_velocity;
+    /**
+     * Zero what a position pass may have written to {@link __pseudo_velocity}
+     * since it was last zeroed; nothing if none has run.
+     * @private
+     */
+    private __clear_pseudo_velocity;
     /**
      * Replace the world gravity vector. Effective on the next step.
      * @param {Vector3|ArrayLike<number>} v indexed as [x, y, z]
@@ -323,6 +470,14 @@ export class PhysicsSystem extends System<any> {
     setGravity(v: Vector3 | ArrayLike<number>): void;
     /**
      * Install (or remove with `null`) the contact filter callback.
+     *
+     * It is asked during the step, and also from inside the CCD pass's sweep — a
+     * {@link shapeCast} — so it may run a {@link raycast} or an {@link overlap},
+     * but not a {@link shapeCast} (refused by an assert: a cast cannot run
+     * inside another). A production build strips asserts, and there nothing
+     * refuses it: the sweep's own cast is overwritten and CCD tunnels without a
+     * word — 200 of 200 fast spheres fired at a 2 cm wall went through it.
+     *
      * @param {((entityA:number, entityB:number, colliderA:Collider, colliderB:Collider) => boolean) | null} fn
      */
     setContactFilter(fn: ((entityA: number, entityB: number, colliderA: Collider, colliderB: Collider) => boolean) | null): void;
@@ -437,6 +592,42 @@ export class PhysicsSystem extends System<any> {
      * @returns {number}
      */
     entityOf(packed_body_id: number): number;
+    /**
+     * Resolve a packed body id to the {@link RigidBody} linked under it, or `undefined` if the id
+     * is stale. The id a query reports names a body; this is how its flags, kind and velocity are
+     * read without the dataset.
+     *
+     * @param {number} packed_body_id as a query reports it
+     * @returns {RigidBody|undefined}
+     */
+    bodyOf(packed_body_id: number): RigidBody | undefined;
+    /**
+     * The colliders attached to a body, in attach order. Each entry gives the `collider`, the world
+     * `transform` it is posed at — the body's own Transform64 for a collider on the body entity, the
+     * child entity's for a compound body's child — and the `entity` that owns the collider. These are
+     * the colliders a query tests when it reaches the body, each at its own transform, in this
+     * order; an overlap query reports the body on the first of them that overlaps.
+     *
+     * **This is the system's live list, not a copy: never write to it.** The array and its entries
+     * are what the broadphase, the narrowphase and every query read, so a `push`, `pop` or `splice`,
+     * or an edit to an entry, changes what the body collides with everywhere — a caller's `pop()`
+     * drops a collider from every query. Attach and detach colliders through
+     * {@link attach_collider} / {@link detach_collider}. The list changes in place on the body's
+     * next attach, detach or unlink; copy what must outlive that. A stale id has no colliders: the
+     * result is one shared, frozen empty array.
+     *
+     * A read-only view is not offered because it is not free: a Proxy that refuses writes made a
+     * walk of an 8-entry list 8.5x as slow to read, and a frozen copy per body would allocate on
+     * every attach and detach and still hand out the live entries.
+     *
+     * @param {number} packed_body_id as a query reports it
+     * @returns {ReadonlyArray<{collider: Collider, transform: Transform64, entity: number}>}
+     */
+    collidersOf(packed_body_id: number): ReadonlyArray<{
+        collider: Collider;
+        transform: Transform64;
+        entity: number;
+    }>;
     /**
      * Number of live bodies (regardless of awake/sleeping state).
      * @returns {number}
@@ -467,8 +658,11 @@ export class PhysicsSystem extends System<any> {
      */
     applyImpulseAt(rigidBody: RigidBody, transform: Transform64, impulse: Vector3 | ArrayLike<number>, worldPoint: Vector3 | ArrayLike<number>): void;
     /**
-     * Accumulate a continuous torque (world-space) for integration on the
-     * next fixedUpdate. Pairs with {@link applyForce} for the rotational case.
+     * Accumulate a torque (world-space, N·m) for the next fixedUpdate. Pairs
+     * with {@link applyForce} for the rotational case, and is spent the same
+     * way: once, as the angular impulse `τ·dt` over the whole step, before the
+     * substeps — a per-step budget, to be applied again every step it should
+     * last.
      *
      * Wakes the body if asleep.
      *
@@ -477,9 +671,12 @@ export class PhysicsSystem extends System<any> {
      */
     applyTorque(rigidBody: RigidBody, torque: Vector3 | ArrayLike<number>): void;
     /**
-     * Apply a continuous force at a specific world-space point. The force
-     * generates both a linear acceleration (F/m) and a torque (r × F) about
-     * the body's centre of mass.
+     * Accumulate a force at a specific world-space point for the next
+     * fixedUpdate. The force generates both a linear acceleration (F/m) and a
+     * torque (r × F) about the body's centre of mass, `r` taken from
+     * `transform` now. Both are spent like {@link applyForce}'s: once, as
+     * `F·dt` and `(r × F)·dt` over the whole step, before the substeps — a
+     * per-step budget, to be applied again every step it should last.
      *
      * Wakes the body if asleep.
      *
@@ -490,7 +687,17 @@ export class PhysicsSystem extends System<any> {
      */
     applyForceAt(rigidBody: RigidBody, transform: Transform64, force: Vector3 | ArrayLike<number>, worldPoint: Vector3 | ArrayLike<number>): void;
     /**
-     * Accumulate a continuous force to be integrated next fixedUpdate step.
+     * Accumulate a force (world-space, newtons) for the next fixedUpdate.
+     *
+     * The step spends the accumulated force once: as the impulse `F·dt`, `dt`
+     * the whole step, added to the body's velocity before the substeps run,
+     * after which the accumulator is empty. It is not re-applied at each
+     * substep the way gravity is. So a force is a per-step budget — the same
+     * change of momentum whatever {@link substeps} is — and one that should
+     * last must be applied again every step. A force worked out from the
+     * body's state (a spring's pull, a drag) is evaluated at the pose and
+     * velocity it was computed from and acts unchanged through the step.
+     *
      * Wakes the body if asleep.
      *
      * @param {RigidBody} rigidBody
@@ -528,6 +735,9 @@ export class PhysicsSystem extends System<any> {
      * as-is; zero it via {@link setLinearVelocity} if the teleport should also stop
      * the body.
      *
+     * Cancels a {@link setTargetPose} target set for the body earlier in the step, so the
+     * teleport is where the step finds it.
+     *
      * 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
@@ -538,6 +748,59 @@ export class PhysicsSystem extends System<any> {
      * @param {Quaternion|ArrayLike<number>} rotation world unit-quaternion rotation, indexed as [x, y, z, w]
      */
     setPose(rigidBody: RigidBody, position: Vector3 | ArrayLike<number>, rotation: Quaternion | ArrayLike<number>): void;
+    /**
+     * Move a {@link BodyKind.KinematicPosition} body to a pose over the next {@link fixedUpdate},
+     * as a motion rather than a teleport: a moving platform, a door, an animated collider.
+     *
+     * The target is consumed by the next `fixedUpdate(dt)`. Before anything in that step reads
+     * velocity, the step sets the body's {@link RigidBody#linearVelocity} to the displacement from
+     * its current position over `dt`, and its {@link RigidBody#angularVelocity} to the shortest-arc
+     * rotation from its current orientation to the target's, as axis × angle over `dt`. Those are
+     * the velocities the contact solver sees, so a body resting on it is carried by friction
+     * (along, and round when it turns), and a body in its way is pushed. The step integrates them
+     * like any velocity and then writes the target pose exactly, so the body ends the step on the
+     * target to the last bit, whatever the substep count does to the rotation's integration.
+     *
+     * - Calling it again before the step replaces the target; the last call wins.
+     * - The velocities stay on the body after the step, as Box3D's `b3Body_SetTargetTransform`
+     *   leaves them: a step with no new target integrates them like any kinematic velocity, so the
+     *   body keeps moving at the same rate. To stop it, target the pose it is at (zero velocity),
+     *   or set its velocities to zero.
+     * - It is a motion from the pose the body has when the step begins. {@link setPose} is the
+     *   teleport — it moves the body with no velocity, so nothing riding it is carried. The later
+     *   of the two calls wins: a setPose after this one cancels the target, and this one after a
+     *   setPose is a motion from the teleported pose.
+     * - Only a KinematicPosition body takes a target. A Dynamic body's motion is the solver's; a
+     *   KinematicVelocity body is driven by the velocity written to it; a Static one never moves.
+     * - Unlike Box3D, which takes the time step with the target and derives the velocity at the
+     *   call, the velocity is derived from the step's own `dt` when the step runs, so the two
+     *   cannot disagree. Kinematic bodies never sleep here, so there is no sleep-threshold skip.
+     *
+     * @param {RigidBody} rigidBody a linked {@link BodyKind.KinematicPosition} body
+     * @param {Vector3|ArrayLike<number>} position world position to reach, indexed as [x, y, z]
+     * @param {Quaternion|ArrayLike<number>} rotation world unit-quaternion rotation to reach,
+     *   indexed as [x, y, z, w]; asserted unit (squared length within 1e-6 of 1), since it is
+     *   written into the transform as given
+     */
+    setTargetPose(rigidBody: RigidBody, position: Vector3 | ArrayLike<number>, rotation: Quaternion | ArrayLike<number>): void;
+    /**
+     * Start of {@link fixedUpdate}: give every body with a pending {@link setTargetPose} target the
+     * velocity that reaches it over `dt`. A step of no duration reaches nothing; its targets stay
+     * pending for the next one.
+     *
+     * @private
+     * @param {number} dt
+     */
+    private __derive_target_velocities;
+    /**
+     * After the substep loop of {@link fixedUpdate}: write every body driven by
+     * {@link setTargetPose} onto its target exactly, and empty the pending list. Skipped, like
+     * {@link __derive_target_velocities}, by a step of no duration.
+     *
+     * @private
+     * @param {number} dt
+     */
+    private __land_target_poses;
     /**
      * Force the body awake. Static bodies are ignored.
      * @param {RigidBody} rigidBody
@@ -594,10 +857,18 @@ export class PhysicsSystem extends System<any> {
      * Raycast against both broadphase trees. Fills `result` with the nearest
      * hit and returns `true` on hit, `false` on miss.
      *
-     * 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.
+     * Resolves against the real shapes: `result.t` is the distance to the
+     * struck surface and `result.normal` its normal there, for every shape the
+     * engine defines (a shape from outside it falls back to its tight bounding
+     * box). Every collider of a compound body is tested; `result.collider_entity`
+     * names the one struck, and `result.triangle` the triangle of a mesh or
+     * heightmap collider. Sensors are passed through.
+     *
+     * The filter may run a {@link shapeCast} or an {@link overlap} of its own,
+     * but not another raycast (refused by an assert: queries of one kind share
+     * their working state). A production build strips asserts, and there
+     * nothing refuses it: the answer is silently wrong — a ray whose filter cast
+     * another ray named entity 8 at t 1.5, where the truth is entity 1 at 2.5.
      *
      * @param {Ray3} ray  origin + unit direction + `tMax`
      * @param {PhysicsSurfacePoint} result populated on hit; untouched on miss
@@ -611,15 +882,23 @@ export class PhysicsSystem extends System<any> {
      * The shape starts at `ray.origin` oriented by `rotation` and translates
      * along `ray.direction` for up to `ray.tMax` units.
      *
-     * 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.
+     * `t` is the time of impact — the swept shape at `t` is just apart from
+     * what it struck — and `result.position` the swept shape's centre there,
+     * not a point on the surface. `result.collider_entity` names the struck
+     * collider and `result.triangle` the triangle of a mesh or heightmap one.
+     *
+     * The filter may run a {@link raycast} or an {@link overlap} of its own,
+     * but not another shapeCast (refused by an assert: queries of one kind
+     * share their working state). A production build strips asserts, and there
+     * nothing refuses it: the outer cast silently misses what it should hit.
      *
      * @param {Ray3} ray  origin + unit direction + `tMax`
      * @param {AbstractShape3D} shape
      * @param {ArrayLike<number>} rotation fixed orientation of the swept shape
-     *   as `[x, y, z, w]`, a unit quaternion — which a Transform64's `rotation`
-     *   already is. Read by index, so an `{x, y, z, w}` object silently misses
-     *   everything rather than throwing
+     *   as `[x, y, z, w]`, a unit quaternion, in an array the caller retains —
+     *   not a Transform64's `rotation`, which allocates a view on every read.
+     *   Read by index, so an `{x, y, z, w}` object silently misses everything
+     *   rather than throwing
      * @param {PhysicsSurfacePoint} result populated on hit; untouched on miss
      * @param {(entity:number, collider:Collider)=>boolean} [filter]
      * @returns {boolean}
@@ -637,13 +916,17 @@ export class PhysicsSystem extends System<any> {
      * available.
      *
      * `filter` runs before the shape test, which is the expensive part — use
-     * it to skip the caller's own body, allies, sensors.
+     * it to skip the caller's own body, allies, sensors. It may run a
+     * {@link raycast} or a {@link shapeCast} of its own, but not another overlap
+     * (refused by an assert: queries of one kind share their working state). A
+     * production build strips asserts, and there nothing refuses it: the outer
+     * overlap silently comes back short — 0 of the 8 bodies it overlapped.
      *
      * The query shape must be convex; a concave one throws.
      *
      * @param {AbstractShape3D} shape convex query shape, in its local frame
-     * @param {ArrayLike<number>} position world position of the query shape, as `[x, y, z]` -
-     *   which a Transform64's translation already is
+     * @param {ArrayLike<number>} position world position of the query shape, as `[x, y, z]`, in an
+     *   array the caller retains - not a Transform64's `translation`, which allocates a view per read
      * @param {ArrayLike<number>} rotation world rotation as `[x, y, z, w]`, a unit quaternion
      * @param {Uint32Array|number[]} output buffer to receive body_ids
      * @param {number} output_offset starting index in output
@@ -740,7 +1023,8 @@ export class PhysicsSystem extends System<any> {
      *
      *  - If any member carries {@link RigidBodyFlags.DisableSleep}, the
      *    entire island is exempt; every member's sleep_timer is reset.
-     *  - If `max(|v|² + |ω|²)` across all members is below
+     *  - If `max(|v|² + |ω|²·max(R, 1)²)` across all members (`R` the
+     *    member's extent, {@link __body_extent}) is below
      *    {@link sleepVelocitySqrThreshold}, every member's sleep_timer is
      *    incremented by `dt`. When the smallest member's timer crosses
      *    {@link sleepTimeThreshold}, the whole island sleeps atomically in

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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"}