@woosh/meep-engine 3.38.0 → 3.39.0

package/src/engine/control/first-person/FirstPersonPlayerControllerSystem.js

@@ -16,6 +16,7 @@ import { Transform64 } from "../../ecs/transform/Transform64.js";
 import { Camera } from "../../graphics/ecs/camera/Camera.js";
 import { BodyKind } from "../../physics/ecs/BodyKind.js";
 import { Collider } from "../../physics/ecs/Collider.js";
+import { is_sensor } from "../../physics/ecs/is_sensor.js";
 import { PhysicsSystem } from "../../physics/ecs/PhysicsSystem.js";
 import { RigidBody } from "../../physics/ecs/RigidBody.js";
 import { PhysicsSurfacePoint } from "../../physics/queries/PhysicsSurfacePoint.js";
@@ -46,6 +47,9 @@ const SCRATCH_Q_C = new Quaternion();
 /** the transform holds its rotation as four numbers, so euler and axis-angle work goes through here */
 const SCRATCH_Q_EULER = new Quaternion();
 
+/** what a released body's velocities are set to; never written */
+const ZERO_VELOCITY = new Float64Array(3);
+
 const TWO_PI = Math.PI * 2;
 const LN2 = Math.log(2);
 
@@ -103,9 +107,12 @@ function makePostureCapsule(radius, totalHeight) {
 class PerEntityRuntime {
     /**
      * Co-attached kinematic body. Set by {@link FirstPersonPlayerControllerSystem.link}
-     * after asserting it's present. The controller writes Transform64.position
-     * directly (existing motion logic); physics derives the body's velocity
-     * from the per-step delta. Other physics systems (raycasts, contact
+     * after asserting it's present. Each tick ends by handing the pose the tick resolved
+     * ({@link bodyPosition}, {@link bodyRotation}) to {@link PhysicsSystem#setTargetPose}: the
+     * physics step that follows moves the body there with the velocity that covers the distance
+     * in the step, so what the player meets or carries sees a body moving at the player's speed,
+     * and the step ends with the body exactly on the pose. A warp ({@link bodyTeleport}) goes
+     * through {@link PhysicsSystem#setPose} instead. Other physics systems (raycasts, contact
      * events) see the player through this body.
      * @type {RigidBody|null}
      */
@@ -119,6 +126,25 @@ class PerEntityRuntime {
      */
     collider = null;
 
+    /**
+     * Query filter that leaves out every collider of the player's own body. A query asks its filter
+     * with the entity of the body a collider belongs to, so comparing that entity catches the
+     * capsule and anything else the body carries — a child trigger, a held item's collider — where
+     * comparing the capsule's Collider caught only the capsule, and a second collider on the body
+     * pushed the player out of itself. Made at link, so a tick allocates no closure.
+     * @type {((entity:number, collider:Collider)=>boolean)|null}
+     */
+    notSelf = null;
+
+    /**
+     * Shape-cast filter for the posture headroom probe: {@link notSelf}, and solid — a sensor (a
+     * collider or body flagged IsSensor) is no ceiling, as it is no wall to the mover. The shape cast
+     * reports sensors, so the probe drops them itself; it asks the physics system for the body behind
+     * the id the cast passes. Made at link.
+     * @type {((entity:number, collider:Collider, body_id:number)=>boolean)|null}
+     */
+    solidNotSelf = null;
+
     /**
      * This character's own mover.
      *
@@ -135,6 +161,43 @@ class PerEntityRuntime {
      */
     mover = null;
 
+    /**
+     * Where this tick puts the body. Read from the body's Transform64 at the top of the tick —
+     * the pose the body actually has — then moved by the mover, the flat-ground fallback or an
+     * ability, and handed to the body at the end of the tick (see {@link rigidBody}). Everything
+     * in the tick that asks where the player is reads it here, not from the transform, which
+     * does not move until the physics step: the land / apex bookkeeping, the posture probe, the
+     * published pose and the camera's interpolation endpoint.
+     * @type {Float64Array}
+     */
+    bodyPosition = new Float64Array(3);
+
+    /**
+     * The body's orientation this tick as `[x, y, z, w]`: the pure yaw of {@link bodyYaw}, made at
+     * the top of the tick and handed to the body with {@link bodyPosition}. The mover's and the
+     * posture probe's casts use it.
+     * @type {Float64Array}
+     */
+    bodyRotation = new Float64Array([0, 0, 0, 1]);
+
+    /**
+     * Where the body was at the top of this tick, as read into {@link bodyPosition}. Compared with
+     * the transform before the pose is handed over: a body moved under the tick by someone else —
+     * a respawn's `setPose` from a signal handler — is left where they put it, rather than pulled
+     * back to a pose resolved from where it used to be.
+     * @type {Float64Array}
+     */
+    bodyStartPosition = new Float64Array(3);
+
+    /**
+     * Set by whoever moved {@link bodyPosition} by a warp this tick rather than a motion — the
+     * ledge grab's snap onto the hang pose. The tick then ends with {@link PhysicsSystem#setPose}
+     * to the pose, so the body gets no velocity from the jump. Cleared when the pose is handed
+     * over.
+     * @type {boolean}
+     */
+    bodyTeleport = false;
+
     /**
      * Pre-built capsule colliders, one per posture. Cached at link
      * from `config.body.{height, crouchHeight, proneHeight, radius}`
@@ -400,6 +463,14 @@ class PerEntityRuntime {
  * - update runs L3 (camera composition) at render rate so the eye is never
  *   smoother than the screen.
  *
+ * The body is moved by the physics step, onto the pose each fixedUpdate
+ * resolves ({@link PhysicsSystem#setTargetPose}). The order the EntityManager
+ * derives runs this system's fixedUpdate before {@link PhysicsSystem}'s in the
+ * same step, so the body is on the tick's pose when the step ends. Run after
+ * it instead, nothing lags but the transform: the tick's own state, the
+ * published `pose.rootPosition` and the camera all use the pose it resolved,
+ * and the next step puts the body there.
+ *
  * The system itself integrates a simple flat-floor at y = `config.gravity.magnitude > 0
  * ? state.groundY : -Infinity` for the prototype. A real physics layer should
  * write `state.grounded`/`state.groundNormal` from outside instead; the
@@ -518,18 +589,23 @@ export class FirstPersonPlayerControllerSystem extends System {
         // attached on this entity. The body is the spatial proxy used
         // for sensor raycasts and physics-side observers (other entities
         // raycasting against the player, dynamic bodies colliding with
-        // the capsule, etc.). The controller writes Transform directly,
-        // physics derives velocity from the per-step delta. If a body is
-        // missing the controller could still drive the camera, but the
-        // physics integration silently breaks — assert here so the
-        // misconfiguration is caught at link time.
+        // the capsule, etc.). The controller moves it with
+        // PhysicsSystem.setTargetPose: each tick resolves a pose, and the
+        // physics step moves the body onto it at the velocity that covers
+        // the distance, so a dynamic body meets a wall moving at the
+        // player's speed. Only a warp (the ledge grab's snap) is a setPose.
+        // Without physics there is no step to move it, and the tick writes
+        // the Transform itself. If a body is missing the controller could
+        // still drive the camera, but the physics integration silently
+        // breaks — assert here so the misconfiguration is caught at link time.
         const rigidBody = ecd.getComponent(entity, RigidBody);
         assert.ok(rigidBody !== undefined,
             "FirstPersonPlayerController entity must have a co-attached RigidBody "
             + "(kinematic capsule). See prototype_first_person_controller.js for setup.");
         assert.equal(rigidBody.kind, BodyKind.KinematicPosition,
             "FirstPersonPlayerController RigidBody must be BodyKind.KinematicPosition; "
-            + "the controller owns the Transform and physics derives velocity.");
+            + "the controller moves the body to each tick's pose with PhysicsSystem.setTargetPose, "
+            + "which takes only that kind.");
         // Collider is also required — the KinematicMover casts this shape
         // against the world (recover / sweep / ground probe). Asserted
         // here so a missing collider surfaces at link rather than
@@ -542,6 +618,12 @@ export class FirstPersonPlayerControllerSystem extends System {
         const runtime = new PerEntityRuntime();
         runtime.rigidBody = rigidBody;
         runtime.collider = collider;
+        runtime.notSelf = (other_entity) => other_entity !== entity;
+        runtime.solidNotSelf = (other_entity, other_collider, body_id) => {
+            if (other_entity === entity) return false;
+            const body = this.physicsSystem.bodyOf(body_id);
+            return body !== undefined && !is_sensor(body, other_collider);
+        };
 
         // Pre-build one capsule per posture from cfg.body. Eye-height
         // doubles as collider-top by convention here — the prototype's
@@ -612,6 +694,15 @@ export class FirstPersonPlayerControllerSystem extends System {
         runtime.bodyYaw = SCRATCH_V3_A.y;
         runtime.eyePitch = 0;
 
+        // The body's pose as the controller holds it, until the first tick reads it again.
+        runtime.bodyPosition[0] = runtime.bodyStartPosition[0] = bodyTransform.translation_x;
+        runtime.bodyPosition[1] = runtime.bodyStartPosition[1] = bodyTransform.translation_y;
+        runtime.bodyPosition[2] = runtime.bodyStartPosition[2] = bodyTransform.translation_z;
+        runtime.bodyRotation[0] = bodyTransform.rotation_x;
+        runtime.bodyRotation[1] = bodyTransform.rotation_y;
+        runtime.bodyRotation[2] = bodyTransform.rotation_z;
+        runtime.bodyRotation[3] = bodyTransform.rotation_w;
+
         // Seed render-rate-look + position-interpolation state to the spawn pose.
         runtime.prevFixedYaw = runtime.bodyYaw;
         runtime.renderPrevPos.set(bodyTransform.translation_x, bodyTransform.translation_y, bodyTransform.translation_z);
@@ -663,9 +754,41 @@ export class FirstPersonPlayerControllerSystem extends System {
             controller.eyeEntity = -1;
         }
 
+        const runtime = this.runtime.get(entity);
+        if (runtime !== undefined) {
+            this._releaseBody(runtime, bodyTransform);
+        }
+
         this.runtime.delete(entity);
     }
 
+    /**
+     * Leave the body standing where the controller last put it. The velocities a target pose
+     * derives stay on the body after its step, so a body the controller stops driving would walk
+     * on at its last speed. When the last pose is still in flight - handed over, its step not run
+     * yet, as when the controller is removed from inside its own tick - the body is put there now,
+     * so the pending target derives no velocity either.
+     *
+     * @private
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform64} bodyTransform
+     */
+    _releaseBody(runtime, bodyTransform) {
+        const physics = this.physicsSystem;
+        const body = runtime.rigidBody;
+        if (physics === null || body === null || body === undefined) return;
+
+        const p = runtime.bodyPosition;
+        if (p[0] !== bodyTransform.translation_x
+            || p[1] !== bodyTransform.translation_y
+            || p[2] !== bodyTransform.translation_z) {
+            physics.setPose(body, p, runtime.bodyRotation);
+        }
+
+        physics.setLinearVelocity(body, ZERO_VELOCITY);
+        physics.setAngularVelocity(body, ZERO_VELOCITY);
+    }
+
     /**
      * Look up the per-entity runtime for an entity that has this
      * controller. Used by cross-system code (sensors system, future
@@ -743,14 +866,23 @@ export class FirstPersonPlayerControllerSystem extends System {
         runtime.yawRateRadPerSec = yawStep / Math.max(dt, 1e-4);
         runtime.prevFixedYaw = runtime.bodyYaw;
 
-        // Write body yaw back to the transform (pure yaw, no pitch on body) —
-        // the collision sweep + sensors use it. The camera uses runtime.bodyYaw
-        // directly, which _consumeLook keeps current at render rate.
+        // The tick starts from the pose the body has: the last tick's pose, landed by the physics
+        // step since (or where a teleport put it). Everything below moves runtime.bodyPosition, and
+        // the body gets it at the end of the tick (_commitBodyPose).
+        const bodyPosition = runtime.bodyPosition;
+        bodyPosition[0] = runtime.bodyStartPosition[0] = bodyTransform.translation_x;
+        bodyPosition[1] = runtime.bodyStartPosition[1] = bodyTransform.translation_y;
+        bodyPosition[2] = runtime.bodyStartPosition[2] = bodyTransform.translation_z;
+
+        // Body yaw (pure yaw, no pitch on body) — the collision sweep uses it, and the body turns to
+        // it with the move. The camera uses runtime.bodyYaw directly, which _consumeLook keeps
+        // current at render rate.
         SCRATCH_Q_EULER.fromAxisAngle(Vector3.up, runtime.bodyYaw);
-        bodyTransform.setRotation(
-            SCRATCH_Q_EULER.x, SCRATCH_Q_EULER.y, SCRATCH_Q_EULER.z, SCRATCH_Q_EULER.w
-        );
-        bodyTransform.updateMatrix();
+        const bodyRotation = runtime.bodyRotation;
+        bodyRotation[0] = SCRATCH_Q_EULER.x;
+        bodyRotation[1] = SCRATCH_Q_EULER.y;
+        bodyRotation[2] = SCRATCH_Q_EULER.z;
+        bodyRotation[3] = SCRATCH_Q_EULER.w;
 
         // -- Shared flags. Computed BEFORE the ability tick so abilities
         //    can read them. `isCrouchActive` is deliberately computed
@@ -790,7 +922,7 @@ export class FirstPersonPlayerControllerSystem extends System {
 
         // Now resolve crouch (updates prevCrouchHeld) — used by base and L2.
         // Headroom-aware: force-keeps the player crouched under an overhang.
-        const isCrouchActive = this._resolveCrouchHeld(controller, runtime, bodyTransform);
+        const isCrouchActive = this._resolveCrouchHeld(controller, runtime);
 
         if (runBaseLocomotion) {
             this._runBaseLocomotion(
@@ -907,31 +1039,11 @@ export class FirstPersonPlayerControllerSystem extends System {
         // Footstep on phase wraparound past 0 (R) or past 0.5 (L). Same
         // posture gate as stride advance — feet must be striking.
         if (feetStriking && state.grounded && horizSpeed > cfg.bob.minStepSpeed) {
-            const fireFootstep = () => {
-                state.stepCount++;
-                const side = runtime.nextFootSide;
-                runtime.nextFootSide = side === "R" ? "L" : "R";
-                // The foot that just fired is now the one bearing weight
-                // through the upcoming half-stride. Drives lateral-bob sign.
-                runtime.standingFoot = side;
-                sig.onFootStep.send1({ side, speed: horizSpeed, surfaceTag: state.surfaceTag });
-                // Kick the vertical impact spring DOWNWARD. The kick magnitude
-                // is the per-step desired peak dip × impactKickMultiplier; the
-                // multiplier is empirical (depends on impact spring params) so
-                // that "verticalAmpAtWalk" still corresponds approximately to
-                // the visible peak dip depth. Scaled by bobIntensity so a
-                // mid-deceleration footstep doesn't deliver a full-strength
-                // impulse.
-                const massBoost = (cfg.body.mass - 80) * cfg.bob.ampMassScale;
-                const ampVMult = 1 + (cfg.bob.backwardVerticalAmpFactor - 1) * runtime.backwardness;
-                const peakDip = (cfg.bob.verticalAmpAtWalk + massBoost) * runtime.bobIntensitySpring.value * ampVMult;
-                runtime.verticalImpactSpring.kick(-peakDip * cfg.bob.impactKickMultiplier);
-            };
             if (phaseCrossed(runtime.prevStridePhase, state.stridePhase, 0)) {
-                fireFootstep();
+                this._fireFootstep(controller, runtime, horizSpeed);
             }
             if (phaseCrossed(runtime.prevStridePhase, state.stridePhase, 0.5)) {
-                fireFootstep();
+                this._fireFootstep(controller, runtime, horizSpeed);
             }
         }
 
@@ -1027,15 +1139,17 @@ export class FirstPersonPlayerControllerSystem extends System {
         // Target is 0; under-damped (cfg zeta < 1) so it rings.
         runtime.landSpring.stepTo(0, cfg.landing.recovery.spring.halfLife, cfg.landing.recovery.spring.zeta, dt);
 
+        // -- L2.h.0: Keep a teleport made under the tick ----------------
+        // Every signal of the tick has been sent. A listener that moved the body - a respawn's
+        // setPose on a hard landing - left the transform somewhere other than where the tick
+        // started; the body stays there, and the camera jumps with it.
+        this._adoptExternalMove(runtime, bodyTransform);
+
         // -- L2.h: Publish pose channels --------------------------------
-        this._publishPose(controller, runtime, bodyTransform);
+        this._publishPose(controller, runtime);
 
-        // -- L2.h.1: Say that the body moved ----------------------------
-        // The yaw write above and the mover's write into the translation both land straight on the
-        // component, and a Transform64 announces nothing on its own. One event here, at the point
-        // where the pose is final, covers every writer in the tick and covers them once - which is
-        // what wakes the mesh placement, the audio emitter and anything else that follows a player.
-        t64_announce_change(ecd, entity);
+        // -- L2.h.1: Hand the pose to the body --------------------------
+        this._commitBodyPose(ecd, entity, runtime, bodyTransform);
 
         // -- L2.i: Sync collider shape to posture -----------------------
         // All posture-writers (base locomotion + any active ability)
@@ -1048,11 +1162,123 @@ export class FirstPersonPlayerControllerSystem extends System {
     }
 
     /**
+     * One footfall: count it, alternate the foot, send `onFootStep` and kick the vertical impact
+     * spring. A method rather than a closure made in the tick, which cost an allocation a tick
+     * while walking.
+     *
      * @private
      * @param {FirstPersonPlayerController} controller
      * @param {PerEntityRuntime} runtime
-     * @returns {boolean}
+     * @param {number} horizSpeed this tick's horizontal speed, m/s
+     */
+    _fireFootstep(controller, runtime, horizSpeed) {
+        const cfg = controller.config;
+        const state = controller.state;
+
+        state.stepCount++;
+        const side = runtime.nextFootSide;
+        runtime.nextFootSide = side === "R" ? "L" : "R";
+        // The foot that just fired is now the one bearing weight
+        // through the upcoming half-stride. Drives lateral-bob sign.
+        runtime.standingFoot = side;
+        controller.signals.onFootStep.send1({ side, speed: horizSpeed, surfaceTag: state.surfaceTag });
+        // Kick the vertical impact spring DOWNWARD. The kick magnitude
+        // is the per-step desired peak dip × impactKickMultiplier; the
+        // multiplier is empirical (depends on impact spring params) so
+        // that "verticalAmpAtWalk" still corresponds approximately to
+        // the visible peak dip depth. Scaled by bobIntensity so a
+        // mid-deceleration footstep doesn't deliver a full-strength
+        // impulse.
+        const massBoost = (cfg.body.mass - 80) * cfg.bob.ampMassScale;
+        const ampVMult = 1 + (cfg.bob.backwardVerticalAmpFactor - 1) * runtime.backwardness;
+        const peakDip = (cfg.bob.verticalAmpAtWalk + massBoost) * runtime.bobIntensitySpring.value * ampVMult;
+        runtime.verticalImpactSpring.kick(-peakDip * cfg.bob.impactKickMultiplier);
+    }
+
+    /**
+     * Keep a move someone else made to the body during this tick. The tick resolved its pose from
+     * where the body was when it started ({@link PerEntityRuntime#bodyStartPosition}); a transform
+     * that is no longer there was moved under the tick - a signal listener's `setPose`, a respawn
+     * on a hard landing - and handing the resolved pose over would pull the body back from where
+     * it was put, at whatever velocity covers that distance in one step. The tick's pose becomes
+     * the transform's instead, and the camera jumps to it.
+     *
+     * @private
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform64} bodyTransform
      */
+    _adoptExternalMove(runtime, bodyTransform) {
+        const start = runtime.bodyStartPosition;
+        const x = bodyTransform.translation_x;
+        const y = bodyTransform.translation_y;
+        const z = bodyTransform.translation_z;
+
+        if (x === start[0] && y === start[1] && z === start[2]) {
+            return;
+        }
+
+        const p = runtime.bodyPosition;
+        p[0] = x;
+        p[1] = y;
+        p[2] = z;
+
+        // the body is where it was put, so there is nothing left for a warp of the tick's own to do
+        runtime.bodyTeleport = false;
+        runtime.renderSnap = true;
+    }
+
+    /**
+     * Hand the pose this tick resolved ({@link PerEntityRuntime#bodyPosition},
+     * {@link PerEntityRuntime#bodyRotation}) to the body.
+     *
+     * With physics, it is a target ({@link PhysicsSystem#setTargetPose}): the next step sets the
+     * body's velocities to cover the distance in the step and ends with the body exactly on the
+     * pose, so what the player meets or carries sees a body moving at the player's speed, and the
+     * step announces the move. Every tick sets one, standing still included - the velocities a
+     * target derives stay on the body, and without a new target the last move's would carry the
+     * player on. A warp ({@link PerEntityRuntime#bodyTeleport}) puts the body on the pose first with
+     * {@link PhysicsSystem#setPose}, so the target derives no velocity from the jump.
+     *
+     * Without physics no step will move the body, so the tick writes the transform and announces
+     * it itself: a Transform64 announces nothing on its own, and the announcement is what wakes the
+     * mesh placement, the audio emitter and anything else that follows a player.
+     *
+     * @private
+     * @param {import("../../ecs/EntityComponentDataset.js").EntityComponentDataset} ecd
+     * @param {number} entity
+     * @param {PerEntityRuntime} runtime
+     * @param {Transform64} bodyTransform
+     */
+    _commitBodyPose(ecd, entity, runtime, bodyTransform) {
+        const p = runtime.bodyPosition;
+        const q = runtime.bodyRotation;
+        const teleport = runtime.bodyTeleport;
+        runtime.bodyTeleport = false;
+
+        const physics = this.physicsSystem;
+
+        if (physics === null) {
+            bodyTransform.setTranslation(p[0], p[1], p[2]);
+            bodyTransform.setRotation(q[0], q[1], q[2], q[3]);
+            bodyTransform.updateMatrix();
+            t64_announce_change(ecd, entity);
+            return;
+        }
+
+        const body = runtime.rigidBody;
+
+        // a hold on the pose the body already has is no warp, and needs none of setPose's work
+        if (teleport && (
+            p[0] !== bodyTransform.translation_x
+            || p[1] !== bodyTransform.translation_y
+            || p[2] !== bodyTransform.translation_z
+        )) {
+            physics.setPose(body, p, q);
+        }
+
+        physics.setTargetPose(body, p, q);
+    }
+
     /**
      * Swap {@link Collider.shape} to the pre-built capsule that matches
      * the player's current posture. Cheap — just a reference swap when
@@ -1083,7 +1309,7 @@ export class FirstPersonPlayerControllerSystem extends System {
         runtime.lastPosture = posture;
     }
 
-    _resolveCrouchHeld(controller, runtime, bodyTransform) {
+    _resolveCrouchHeld(controller, runtime) {
         const cfg = controller.config;
         const intent = controller.intent;
         const state = controller.state;
@@ -1118,7 +1344,7 @@ export class FirstPersonPlayerControllerSystem extends System {
             || runtime.lastPosture === FirstPersonPosture.Prone;
         if (!wantsCrouch && alreadyLow) {
             const growDelta = runtime.standTop - runtime.crouchTop;
-            if (!this._hasHeadroomToGrow(runtime, bodyTransform, runtime.colliderShapeCrouch, growDelta)) {
+            if (!this._hasHeadroomToGrow(runtime, runtime.colliderShapeCrouch, growDelta)) {
                 state.crouchBlocked = true;
                 return true;
             }
@@ -1139,22 +1365,22 @@ export class FirstPersonPlayerControllerSystem extends System {
      * overlap would false-positive on a wall *beside* the player. The
      * up-cast sweeps parallel to (and, per the mover's skin clearance,
      * clear of) lateral walls so they aren't hit; the floor is below
-     * the rising probe; the player's own body is filtered out. Only
-     * genuine overhead geometry blocks the grow. Relies on the player
+     * the rising probe; the player's own body, and sensors, are filtered
+     * out ({@link PerEntityRuntime#solidNotSelf}). Only genuine overhead
+     * geometry blocks the grow. Relies on the player
      * resting at `floor+skin` (the mover's stick-to-ground), so the
      * probe's bottom starts clear of the floor.
      *
      * @private
      */
-    _hasHeadroomToGrow(runtime, bodyTransform, fromShape, growDelta) {
+    _hasHeadroomToGrow(runtime, fromShape, growDelta) {
         if (this.physicsSystem === null || growDelta <= 1e-4) return true;
-        const ownCollider = runtime.collider;
-        const filter = (_e, c) => c !== ownCollider;
         const ray = this._postureRay;
-        ray.setOrigin(bodyTransform.translation_x, bodyTransform.translation_y, bodyTransform.translation_z);
+        const p = runtime.bodyPosition;
+        ray.setOrigin(p[0], p[1], p[2]);
         ray.setDirection(0, 1, 0);
         ray.tMax = growDelta;
-        return !this.physicsSystem.shapeCast(ray, fromShape, bodyTransform.rotation, this._postureHit, filter);
+        return !this.physicsSystem.shapeCast(ray, fromShape, runtime.bodyRotation, this._postureHit, runtime.solidNotSelf);
     }
 
     /**
@@ -1166,10 +1392,9 @@ export class FirstPersonPlayerControllerSystem extends System {
      * @private
      * @param {FirstPersonPlayerController} controller
      * @param {PerEntityRuntime} runtime
-     * @param {Transform64} bodyTransform
      * @param {number} dt
      */
-    _advanceJumpFsm(controller, runtime, bodyTransform, dt) {
+    _advanceJumpFsm(controller, runtime, dt) {
         const cfg = controller.config;
         const intent = controller.intent;
         const state = controller.state;
@@ -1230,7 +1455,7 @@ export class FirstPersonPlayerControllerSystem extends System {
                 runtime.velocityY = runtime.jumpInitialVy * masteryMul;
                 runtime.midJump = true;
                 runtime.apexFired = false;
-                runtime.peakAltitude = bodyTransform.translation_y;
+                runtime.peakAltitude = runtime.bodyPosition[1];
                 state.inJumpAnticipation = false;
                 state.isVariableJumpCut = false;
                 state.isAscending = true;
@@ -1257,17 +1482,19 @@ export class FirstPersonPlayerControllerSystem extends System {
      * a physics layer is present; otherwise a lightweight flat-ground
      * integrator for headless / unit-test scenes with no collidable
      * geometry. Land / leave-ground events flow identically from either.
+     * The move is resolved into {@link PerEntityRuntime#bodyPosition}.
      *
      * @private
      * @param {FirstPersonPlayerController} controller
      * @param {PerEntityRuntime} runtime
-     * @param {Transform64} bodyTransform
+     * @param {Transform64} bodyTransform the body's transform, holding the pose the tick started
+     *   from; not written
      * @param {number} dt
      */
     _integrateVerticalAndResolveGround(controller, runtime, bodyTransform, dt) {
         this._applyGravity(controller, runtime, dt);
         this._resolveMotion(controller, runtime, bodyTransform, dt);
-        this._detectJumpApex(controller, runtime, bodyTransform);
+        this._detectJumpApex(controller, runtime);
     }
 
     /**
@@ -1280,13 +1507,17 @@ export class FirstPersonPlayerControllerSystem extends System {
      * and then call this directly — so motion routes through one motor for
      * everyone (sweep-and-slide, anti-tunnel, land/leave events) rather than
      * a bespoke `position._add` + hand-rolled ground-catch.
+     *
+     * The move starts from {@link PerEntityRuntime#bodyPosition} and is resolved into it; the
+     * body reaches it at the end of the tick. `bodyTransform` holds the pose the tick started from
+     * and is not written.
      * @private
      */
     _resolveMotion(controller, runtime, bodyTransform, dt) {
         if (this.physicsSystem !== null) {
-            this._moveViaMover(controller, runtime, bodyTransform, dt);
+            this._moveViaMover(controller, runtime, dt);
         } else {
-            this._moveFlatGround(controller, runtime, bodyTransform, dt);
+            this._moveFlatGround(controller, runtime, dt);
         }
     }
 
@@ -1315,12 +1546,12 @@ export class FirstPersonPlayerControllerSystem extends System {
      * the result back to controller state and land / leave events.
      * @private
      */
-    _moveViaMover(controller, runtime, bodyTransform, dt) {
+    _moveViaMover(controller, runtime, dt) {
         const state = controller.state;
 
         // per character, not per system - see the note on PerEntityRuntime#mover
         if (runtime.mover === null) {
-            runtime.mover = new KinematicMover(this.physicsSystem, this.entityManager.dataset);
+            runtime.mover = new KinematicMover(this.physicsSystem);
         }
 
         // Fall speed captured BEFORE the move — the mover clips velocityY
@@ -1330,14 +1561,13 @@ export class FirstPersonPlayerControllerSystem extends System {
         const v = this._moverVelocity;
         v.set(runtime.velocityX, runtime.velocityY, runtime.velocityZ);
 
-        const ownCollider = runtime.collider;
-        const filter = (_e, c) => c !== ownCollider;
-
+        // From where the body is this tick (the pose it started from, or where an earlier move in
+        // the same tick left it) to where the move ends; the body gets there in the physics step.
         const result = runtime.mover.move(
-            bodyTransform.translation,
-            bodyTransform.rotation,
+            runtime.bodyPosition,
+            runtime.bodyRotation,
             runtime.collider.shape,
-            v, dt, filter,
+            v, dt, runtime.notSelf,
         );
 
         // Read back corrected horizontal velocity. Vertical follows the
@@ -1357,7 +1587,7 @@ export class FirstPersonPlayerControllerSystem extends System {
             state.airborneTime = 0;
             state.timeSinceGrounded = 0;
         } else {
-            if (wasGrounded) this._onLeaveGround(controller, runtime, bodyTransform);
+            if (wasGrounded) this._onLeaveGround(controller, runtime);
             state.grounded = false;
             state.verticalSpeed = runtime.velocityY;
             state.airborneTime += dt;
@@ -1375,28 +1605,24 @@ export class FirstPersonPlayerControllerSystem extends System {
      * `state.grounded`; we only advance timers.
      * @private
      */
-    _moveFlatGround(controller, runtime, bodyTransform, dt) {
+    _moveFlatGround(controller, runtime, dt) {
         const state = controller.state;
 
-        // translation lands in the matrix as it is written, so no updateMatrix is owed here
-        bodyTransform.setTranslation(
-            bodyTransform.translation_x + runtime.velocityX * dt,
-            bodyTransform.translation_y + runtime.velocityY * dt,
-            bodyTransform.translation_z + runtime.velocityZ * dt
-        );
+        const p = runtime.bodyPosition;
+        p[0] += runtime.velocityX * dt;
+        p[1] += runtime.velocityY * dt;
+        p[2] += runtime.velocityZ * dt;
 
         if (this.useBuiltInFlatGround || this.groundResolver !== null) {
             // Effective ground = max(built-in flat ground, resolver).
             let testY = this.useBuiltInFlatGround ? this.groundY : Number.NEGATIVE_INFINITY;
             if (this.groundResolver !== null) {
-                const resolved = this.groundResolver(
-                    bodyTransform.translation_x, bodyTransform.translation_y, bodyTransform.translation_z,
-                );
+                const resolved = this.groundResolver(p[0], p[1], p[2]);
                 if (resolved !== null && resolved > testY) testY = resolved;
             }
             const haveGround = testY !== Number.NEGATIVE_INFINITY;
-            if (haveGround && bodyTransform.translation_y <= testY) {
-                bodyTransform.setTranslation(bodyTransform.translation_x, testY, bodyTransform.translation_z);
+            if (haveGround && p[1] <= testY) {
+                p[1] = testY;
                 if (!state.grounded) this._onLand(controller, runtime, -runtime.velocityY);
                 state.grounded = true;
                 state.groundNormal.set(0, 1, 0);
@@ -1405,7 +1631,7 @@ export class FirstPersonPlayerControllerSystem extends System {
                 state.airborneTime = 0;
                 state.timeSinceGrounded = 0;
             } else {
-                if (state.grounded) this._onLeaveGround(controller, runtime, bodyTransform);
+                if (state.grounded) this._onLeaveGround(controller, runtime);
                 state.grounded = false;
                 state.verticalSpeed = runtime.velocityY;
                 state.airborneTime += dt;
@@ -1460,20 +1686,21 @@ export class FirstPersonPlayerControllerSystem extends System {
      * Shared by both move paths.
      * @private
      */
-    _onLeaveGround(controller, runtime, bodyTransform) {
+    _onLeaveGround(controller, runtime) {
         controller.signals.onLeaveGround.send1({ reason: runtime.midJump ? "jump" : "fall" });
         runtime.takeoffVy = runtime.velocityY;
-        runtime.peakAltitude = bodyTransform.translation_y;
+        runtime.peakAltitude = runtime.bodyPosition[1];
     }
 
     /**
      * Fire `onJumpApex` once, when an in-progress jump stops rising.
      * @private
      */
-    _detectJumpApex(controller, runtime, bodyTransform) {
+    _detectJumpApex(controller, runtime) {
         if (runtime.midJump && !runtime.apexFired) {
-            if (bodyTransform.translation_y > runtime.peakAltitude) {
-                runtime.peakAltitude = bodyTransform.translation_y;
+            const y = runtime.bodyPosition[1];
+            if (y > runtime.peakAltitude) {
+                runtime.peakAltitude = y;
             } else if (runtime.velocityY <= 0) {
                 controller.signals.onJumpApex.send0();
                 runtime.apexFired = true;
@@ -1605,7 +1832,7 @@ export class FirstPersonPlayerControllerSystem extends System {
         }
 
         // -- L1.e/f/g/h: jump FSM + vertical integration --------------
-        this._advanceJumpFsm(controller, runtime, bodyTransform, dt);
+        this._advanceJumpFsm(controller, runtime, dt);
         this._integrateVerticalAndResolveGround(controller, runtime, bodyTransform, dt);
 
         // -- Publish posture for L2 consumers (eye height, gait gating).
@@ -1626,7 +1853,7 @@ export class FirstPersonPlayerControllerSystem extends System {
         if (posture === FirstPersonPosture.Crouch
             && runtime.lastPosture === FirstPersonPosture.Prone) {
             const proneGrow = runtime.crouchTop - runtime.proneTop;
-            if (!this._hasHeadroomToGrow(runtime, bodyTransform, runtime.colliderShapeProne, proneGrow)) {
+            if (!this._hasHeadroomToGrow(runtime, runtime.colliderShapeProne, proneGrow)) {
                 posture = FirstPersonPosture.Prone;
             }
         }
@@ -1716,17 +1943,21 @@ export class FirstPersonPlayerControllerSystem extends System {
      * Read-only with respect to controller state — this is purely a publish
      * step.
      *
+     * The root position is the pose this tick resolved ({@link PerEntityRuntime#bodyPosition}),
+     * which the body reaches in the physics step: published now, it is where the body is once
+     * the step has run, whichever of the two systems runs first.
+     *
      * @private
      * @param {FirstPersonPlayerController} controller
      * @param {PerEntityRuntime} runtime
-     * @param {Transform64} bodyTransform
      */
-    _publishPose(controller, runtime, bodyTransform) {
+    _publishPose(controller, runtime) {
         const cfg = controller.config;
         const state = controller.state;
         const pose = controller.pose;
 
-        pose.rootPosition.set(bodyTransform.translation_x, bodyTransform.translation_y, bodyTransform.translation_z);
+        const p = runtime.bodyPosition;
+        pose.rootPosition.set(p[0], p[1], p[2]);
         pose.rootYawRad = runtime.bodyYaw;
         pose.headYawRad = runtime.bodyYaw;
         pose.headPitchRad = runtime.eyePitch;
@@ -1768,8 +1999,8 @@ export class FirstPersonPlayerControllerSystem extends System {
 
         pose.aimPitch = runtime.eyePitch;
 
-        this._assertTickInvariants(controller, runtime, bodyTransform);
-        this._snapshotRenderPose(runtime, bodyTransform);
+        this._assertTickInvariants(controller, runtime);
+        this._snapshotRenderPose(runtime);
     }
 
     /**
@@ -1779,18 +2010,20 @@ export class FirstPersonPlayerControllerSystem extends System {
      * position is smooth at any refresh rate. (Yaw/pitch aren't snapshotted —
      * they're render-rate.) On a teleport (`renderSnap`), prev and cur collapse
      * to the new position so the camera jumps rather than gliding across it.
+     * The position is the pose this tick resolved, not the transform, which
+     * reaches it only in the physics step.
      * @private
      */
-    _snapshotRenderPose(runtime, bodyTransform) {
-        const p = bodyTransform;
+    _snapshotRenderPose(runtime) {
+        const p = runtime.bodyPosition;
         if (runtime.renderSnap) {
             runtime.renderSnap = false;
-            runtime.renderPrevPos.set(p.translation_x, p.translation_y, p.translation_z);
-            runtime.renderCurPos.set(p.translation_x, p.translation_y, p.translation_z);
+            runtime.renderPrevPos.set(p[0], p[1], p[2]);
+            runtime.renderCurPos.set(p[0], p[1], p[2]);
             return;
         }
         runtime.renderPrevPos.copy(runtime.renderCurPos);
-        runtime.renderCurPos.set(p.translation_x, p.translation_y, p.translation_z);
+        runtime.renderCurPos.set(p[0], p[1], p[2]);
     }
 
     /**
@@ -1803,8 +2036,8 @@ export class FirstPersonPlayerControllerSystem extends System {
      * jump frames (or seconds) later when something finally reads it.
      * @private
      */
-    _assertTickInvariants(controller, runtime, bodyTransform) {
-        const p = bodyTransform;
+    _assertTickInvariants(controller, runtime) {
+        const p = runtime.bodyPosition;
         assert.ok(Number.isFinite(runtime.bodyYaw),
             "FP invariant: runtime.bodyYaw is non-finite (camera yaw corrupted)");
         assert.ok(Number.isFinite(runtime.eyePitch),
@@ -1818,7 +2051,7 @@ export class FirstPersonPlayerControllerSystem extends System {
             "FP invariant: runtime.velocity is non-finite",
         );
         assert.ok(
-            Number.isFinite(p.translation_x) && Number.isFinite(p.translation_y) && Number.isFinite(p.translation_z),
+            Number.isFinite(p[0]) && Number.isFinite(p[1]) && Number.isFinite(p[2]),
             "FP invariant: body position is non-finite",
         );
     }