@jgengine/core 0.14.0 → 0.15.0

package/dist/movement/movementModel.js

@@ -22,17 +22,24 @@ const IDLE_INTENT = {
     jumping: false,
     moving: false,
 };
+/** Below this deflection an analog stick reads as centered — filters sensor noise without eating small deliberate tilts (the shell applies its own radial deadzone before publishing). */
+const ANALOG_MOVE_EPSILON = 0.02;
 /**
  * Translate the set of held keys into an intent. When `canMove` is false (a
  * menu is open, the world is paused) the avatar is fully idle so it never
- * drifts behind an overlay.
+ * drifts behind an overlay. An `analog` vector (virtual joystick, gamepad
+ * stick) replaces the digital WASD axes with its fractional deflection (#1370).
   * @internal
   */
-export function resolveMovementIntent(keys, canMove) {
+export function resolveMovementIntent(keys, canMove, analog) {
     if (!canMove)
         return IDLE_INTENT;
-    const forward = (keys.w ? 1 : 0) - (keys.s ? 1 : 0);
-    const right = (keys.d ? 1 : 0) - (keys.a ? 1 : 0);
+    let forward = (keys.w ? 1 : 0) - (keys.s ? 1 : 0);
+    let right = (keys.d ? 1 : 0) - (keys.a ? 1 : 0);
+    if (analog !== undefined && analog !== null) {
+        forward = Math.abs(analog.forward) < ANALOG_MOVE_EPSILON ? 0 : Math.max(-1, Math.min(1, analog.forward));
+        right = Math.abs(analog.right) < ANALOG_MOVE_EPSILON ? 0 : Math.max(-1, Math.min(1, analog.right));
+    }
     const crouching = keys.control || keys.c;
     const running = keys.shift && !crouching;
     return {
@@ -142,7 +149,10 @@ export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpee
         targetVelocityZ = fz * intent.forward + rightZ * intent.right;
         const lengthSq = targetVelocityX * targetVelocityX + targetVelocityZ * targetVelocityZ;
         if (lengthSq > 1e-6) {
-            const scale = targetSpeed / Math.sqrt(lengthSq);
+            // Analog sticks walk at their deflection: speed scales with the intent magnitude, capped at
+            // 1 so digital diagonals (length √2) still normalize to exactly full speed.
+            const length = Math.sqrt(lengthSq);
+            const scale = (targetSpeed * Math.min(1, length)) / length;
             targetVelocityX *= scale;
             targetVelocityZ *= scale;
         }
@@ -191,15 +201,31 @@ const DEFAULT_OBSTACLE_HALF_EXTENTS = [0.5, 0.5, 0.5];
 export const DEFAULT_OBSTACLE_PLAYER_RADIUS = 0.3;
 /** Feet-to-head span used for the obstacle's vertical overlap test; matches DEFAULT_VOXEL_DIMS.height. */
 const OBSTACLE_PLAYER_HEIGHT = 1.8;
+/** Extra nudge past a solid face when depenetrating so the escaped capsule lands just outside, not on, the box. */
+const PENETRATION_EPSILON = 1e-3;
+/**
+ * Swept clamp of a single-axis step against a box span. Entering from outside stops on the near
+ * face — including when the raw target would land *beyond* the far face (the old form returned the
+ * full step there, tunneling a fast mover straight through the box in one frame). Starting inside
+ * the span still permits full exits (the depenetration path owns true stuck-inside cases), and
+ * motion beginning at or past a face moving away is untouched.
+ */
 function clampAxisStep(originalCoord, step, min, max) {
     if (step === 0)
         return 0;
     const target = originalCoord + step;
-    if (target <= min || target >= max)
+    if (step > 0) {
+        if (originalCoord >= max)
+            return step;
+        if (originalCoord <= min)
+            return target > min ? min - originalCoord : step;
+        return target >= max ? step : 0;
+    }
+    if (originalCoord <= min)
         return step;
-    if (step > 0)
-        return originalCoord <= min ? min - originalCoord : 0;
-    return originalCoord >= max ? max - originalCoord : 0;
+    if (originalCoord >= max)
+        return target < max ? max - originalCoord : step;
+    return target <= min ? step : 0;
 }
 /**
  * Resolve a horizontal step against nearby placed objects with classic
@@ -209,17 +235,23 @@ function clampAxisStep(originalCoord, step, min, max) {
  * by `playerRadius`; an obstacle whose vertical span misses the player's
  * feet-to-head span is skipped entirely. Callers should pre-filter to nearby
  * objects — this also early-exits per obstacle on horizontal distance.
+ *
+ * `stepUpHeight` treats boxes whose top sits within that height above the feet
+ * as walkable ledges instead of walls: they stop blocking here, and the caller
+ * stands the player on them via {@link obstacleSupportHeight} — a curb or stair
+ * tread is stepped up, not bumped into.
   * @internal
   */
-export function resolveObstacleStep(current, stepX, stepZ, obstacles, playerRadius = DEFAULT_OBSTACLE_PLAYER_RADIUS) {
+export function resolveObstacleStep(current, stepX, stepZ, obstacles, playerRadius = DEFAULT_OBSTACLE_PLAYER_RADIUS, stepUpHeight = 0) {
     const feetY = current[1];
     const headY = feetY + OBSTACLE_PLAYER_HEIGHT;
     const reachX = Math.abs(stepX) + playerRadius;
     const reachZ = Math.abs(stepZ) + playerRadius;
     const nearby = [];
     const considerBox = (minX, maxX, minY, maxY, minZ, maxZ) => {
-        // Vertical-span cull: a sub-box entirely above the head (walk under the lintel) or below the feet is skipped.
-        if (maxY <= feetY || minY >= headY)
+        // Vertical-span cull: a sub-box entirely above the head (walk under the lintel), below the feet,
+        // or low enough to step up onto (`stepUpHeight`) is skipped — walkable ledges don't wall.
+        if (maxY <= feetY + stepUpHeight || minY >= headY)
             return;
         const centerX = (minX + maxX) / 2;
         const centerZ = (minZ + maxZ) / 2;
@@ -251,20 +283,94 @@ export function resolveObstacleStep(current, stepX, stepZ, obstacles, playerRadi
         const cz = pz + (offset !== undefined ? offset[2] : 0);
         considerBox(cx - halfExtents[0], cx + halfExtents[0], cy - halfExtents[1], cy + halfExtents[1], cz - halfExtents[2], cz + halfExtents[2]);
     }
-    let resultX = stepX;
+    // Depenetration escape: axis-clamped sliding alone returns zero on BOTH axes once the capsule is
+    // strictly inside a solid box (a prior frame wedged it into a corner, an object spawned overlapping
+    // it, or a ground snap dropped it in), so the player locks up forever — "I collide and get stuck".
+    // Boxes the capsule is inside are pushed out here along their shallowest face and excluded from the
+    // slide below; resting exactly on a face (the clamp's natural stopping point) is not "inside", so
+    // normal wall contact never triggers an escape and every existing slide case is unchanged.
+    let escapeX = 0;
+    let escapeZ = 0;
+    const slideBoxes = [];
     for (const box of nearby) {
+        const insideX = current[0] > box.minX && current[0] < box.maxX;
+        const insideZ = current[2] > box.minZ && current[2] < box.maxZ;
+        if (!insideX || !insideZ) {
+            slideBoxes.push(box);
+            continue;
+        }
+        const toMinX = current[0] - box.minX;
+        const toMaxX = box.maxX - current[0];
+        const toMinZ = current[2] - box.minZ;
+        const toMaxZ = box.maxZ - current[2];
+        const minPen = Math.min(toMinX, toMaxX, toMinZ, toMaxZ);
+        if (minPen === toMinX)
+            escapeX = Math.min(escapeX, -(toMinX + PENETRATION_EPSILON));
+        else if (minPen === toMaxX)
+            escapeX = Math.max(escapeX, toMaxX + PENETRATION_EPSILON);
+        else if (minPen === toMinZ)
+            escapeZ = Math.min(escapeZ, -(toMinZ + PENETRATION_EPSILON));
+        else
+            escapeZ = Math.max(escapeZ, toMaxZ + PENETRATION_EPSILON);
+    }
+    let resultX = stepX;
+    for (const box of slideBoxes) {
         if (current[2] <= box.minZ || current[2] >= box.maxZ)
             continue;
         resultX = clampAxisStep(current[0], resultX, box.minX, box.maxX);
     }
     const nextX = current[0] + resultX;
     let resultZ = stepZ;
-    for (const box of nearby) {
+    for (const box of slideBoxes) {
         if (nextX <= box.minX || nextX >= box.maxX)
             continue;
         resultZ = clampAxisStep(current[2], resultZ, box.minZ, box.maxZ);
     }
-    return { stepX: resultX, stepZ: resultZ };
+    return { stepX: resultX + escapeX, stepZ: resultZ + escapeZ };
+}
+/**
+ * Highest blocking-box top the player can stand on at `(x, z)`: among obstacles whose footprint
+ * (inflated by `playerRadius`, matching the blocking inflation so any horizontal contact that would
+ * block also supports) contains the point, the tallest top face at or below `feetY + maxClimb`.
+ * `null` when nothing supports. This is what turns a blocking collider into a walkable surface —
+ * step up a curb (`maxClimb` = step height while grounded), land a jump on a crate (`maxClimb` = 0
+ * while airborne, so only tops already below the feet catch), and stand on placed assets instead of
+ * sinking into them and being rubber-banded out by depenetration.
+ * @capability standing-on-objects a player steps up onto low ledges and lands ON a jumped-onto asset's top face instead of clipping inside it.
+ * @internal
+ */
+export function obstacleSupportHeight(x, z, feetY, maxClimb, obstacles, playerRadius = DEFAULT_OBSTACLE_PLAYER_RADIUS) {
+    const ceiling = feetY + maxClimb;
+    let best = null;
+    const considerTop = (minX, maxX, maxY, minZ, maxZ) => {
+        if (maxY > ceiling)
+            return;
+        if (best !== null && maxY <= best)
+            return;
+        if (x < minX - playerRadius || x > maxX + playerRadius)
+            return;
+        if (z < minZ - playerRadius || z > maxZ + playerRadius)
+            return;
+        best = maxY;
+    };
+    for (const obstacle of obstacles) {
+        const px = obstacle.position[0];
+        const py = obstacle.position[1];
+        const pz = obstacle.position[2];
+        if (obstacle.boxes !== undefined && obstacle.boxes.length > 0) {
+            for (const box of obstacle.boxes) {
+                considerTop(px + box.min[0], px + box.max[0], py + box.max[1], pz + box.min[2], pz + box.max[2]);
+            }
+            continue;
+        }
+        const halfExtents = obstacle.halfExtents ?? DEFAULT_OBSTACLE_HALF_EXTENTS;
+        const offset = obstacle.offset;
+        const cx = px + (offset !== undefined ? offset[0] : 0);
+        const cy = py + (offset !== undefined ? offset[1] : 0);
+        const cz = pz + (offset !== undefined ? offset[2] : 0);
+        considerTop(cx - halfExtents[0], cx + halfExtents[0], cy + halfExtents[1], cz - halfExtents[2], cz + halfExtents[2]);
+    }
+    return best;
 }
 const OBSTACLE_GATHER_RADIUS = 3;
 /** Placed objects within `radius` (XZ) of `center`, as {@link CollisionObstacle}s to pre-filter for {@link resolveObstacleStep}.

package/dist/movement/playerMovement.js

@@ -1,7 +1,7 @@
 import { applyHorizontalImpulses, applyMotionImpulses } from "../runtime/motionIntents.js";
 import { groundFieldFor, hasEnvironmentTerrain, sampleSlope } from "../world/terrain.js";
 import { resolveColliders } from "../scene/colliders.js";
-import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, DEFAULT_OBSTACLE_PLAYER_RADIUS, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, } from "./movementModel.js";
+import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, DEFAULT_OBSTACLE_PLAYER_RADIUS, obstacleSupportHeight, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, } from "./movementModel.js";
 import { approachYaw, steerYaw } from "./steering.js";
 import { advanceVoxelPlayer, createVoxelPlayerBody, } from "./voxelController.js";
 const DEFAULT_TURN_SPEED = 2.4;
@@ -11,6 +11,8 @@ const DEFAULT_SWIM_SPEED_MULTIPLIER = 0.65;
 const DEFAULT_MAX_CLIMB_NORMAL_Y = Math.cos((50 * Math.PI) / 180);
 /** Downhill slide speed (units/s) per unit of slope steepness while on too-steep ground. */
 const SLOPE_SLIDE_SPEED = 4;
+/** Tallest object ledge walked up (and largest ground drop still snapped down) without jumping/falling. */
+const DEFAULT_PLAYER_STEP_HEIGHT = 0.4;
 /**
  * Maps a game's declared `physics` onto the movement controllers' tuning. `PhysicsConfig.gravity` is a signed
  * world acceleration (negative points down), but the controllers integrate `velocityY -= gravityAcceleration * dt`
@@ -45,7 +47,14 @@ const stores = new WeakMap();
 function storeFor(ctx) {
     let store = stores.get(ctx);
     if (store === undefined) {
-        store = { players: new Map(), solids: { count: -1, set: new Set() } };
+        store = {
+            players: new Map(),
+            solids: { count: -1, set: new Set() },
+            obstacleReach: {
+                count: -1,
+                value: { horizontal: OBSTACLE_MAX_HALF_EXTENT, vertical: OBSTACLE_VERTICAL_FLOOR },
+            },
+        };
         stores.set(ctx, store);
     }
     return store;
@@ -98,6 +107,10 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
     const player = ctx.scene.entity.get(playerId);
     if (player === null)
         return;
+    // Seated / scripted freeze: skip the whole movement + obstacle gather. Without this, a driven car
+    // still paid city-scale collision every frame while the rider was frozen in place.
+    if (player.movement?.frozen === true)
+        return;
     const store = storeFor(ctx);
     const state = stateFor(store, userId);
     const held = new Set(input.held);
@@ -120,7 +133,16 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
     keys.d = isDown("moveRight");
     keys.shift = isDown("sprint") && (tuning.movement?.canSprint?.(ctx) ?? true);
     keys.space = isDown("jump");
-    const intent = resolveMovementIntent(keys, true);
+    // A frame carrying analog magnitudes (virtual joystick, gamepad stick) walks at its deflection
+    // instead of slamming digital ±1 axes — the fix for "a slight stick tilt reads as a full strafe".
+    const analog = input.analog ?? null;
+    const analogMove = analog === null
+        ? null
+        : {
+            forward: (analog.moveForward ?? 0) - (analog.moveBack ?? 0),
+            right: (analog.moveRight ?? 0) - (analog.moveLeft ?? 0),
+        };
+    const intent = resolveMovementIntent(keys, true, analogMove);
     const motionBatch = ctx.player.motionFor(userId).takePending();
     const walkSpeed = player.movement?.walkSpeed ?? DEFAULT_WALK_SPEED;
     if (tuning.collision?.voxel === true) {
@@ -172,7 +194,11 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
     const motionOptions = submerged
         ? { speedScale: swimSpeedMultiplier, floating: true }
         : undefined;
+    const prevJumpOffset = motion.jumpOffset;
     const step = advancePlayerMotion(motion, intent, forwardX, forwardZ, walkSpeed, dt, tuning.physics, motionOptions);
+    // Airborne means "not resting on the surface below": any jump/impulse height before or after this
+    // frame's integration. Grounded-only forgiveness (step-up) and airborne-only landing key off it.
+    const airborne = prevJumpOffset > 0 || motion.jumpOffset > 0;
     let stepX = step.stepX;
     let stepZ = step.stepZ;
     if (tuning.movement?.mode === "axis") {
@@ -180,9 +206,12 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
         stepX = constrained.stepX;
         stepZ = constrained.stepZ;
     }
-    if (tuning.movement?.collideObjects === true) {
-        const obstacles = gatherMovementObstacles(ctx, player.position, stepX, stepZ);
-        const resolved = resolveObstacleStep(player.position, stepX, stepZ, obstacles);
+    const stepHeight = tuning.movement?.stepHeight ?? DEFAULT_PLAYER_STEP_HEIGHT;
+    let obstacles = null;
+    if (tuning.movement?.collideObjects !== false) {
+        obstacles = gatherMovementObstacles(ctx, store, player.position, stepX, stepZ);
+        // While grounded, a box the player could simply step onto is a ledge, not a wall.
+        const resolved = resolveObstacleStep(player.position, stepX, stepZ, obstacles, DEFAULT_OBSTACLE_PLAYER_RADIUS, airborne ? 0 : stepHeight);
         stepX = resolved.stepX;
         stepZ = resolved.stepZ;
     }
@@ -206,12 +235,49 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
         }
     }
     const groundAtNext = tuning.ground.sampleHeight(nextX, nextZ);
-    let nextY = groundAtNext + motion.jumpOffset;
+    // Blocking colliders are walkable surfaces: the effective ground under the player is the higher of
+    // the terrain and the tallest object top the player can stand on here. While grounded a top within
+    // stepHeight above the feet is stepped onto (matching the obstruction's ledge forgiveness); while
+    // airborne only tops at/below the feet catch, so a jump lands ON a crate instead of sinking inside
+    // it and being rubber-banded out by depenetration.
+    const supportY = obstacles !== null
+        ? obstacleSupportHeight(nextX, nextZ, player.position[1], airborne ? 0 : stepHeight, obstacles)
+        : null;
+    const effectiveGround = supportY !== null && supportY > groundAtNext ? supportY : groundAtNext;
+    let nextY;
+    if (airborne) {
+        // Integrate the jump arc in absolute space (previous feet + this frame's offset delta) so the
+        // arc stays continuous when the ground under the player changes mid-flight, and land on the
+        // effective ground — terrain or object top — the moment the descending feet reach it.
+        const nextFeet = player.position[1] + (motion.jumpOffset - prevJumpOffset);
+        if (nextFeet <= effectiveGround && motion.verticalVelocity <= 0) {
+            nextY = effectiveGround;
+            motion.jumpOffset = 0;
+            motion.verticalVelocity = 0;
+            motion.grounded = true;
+        }
+        else {
+            nextY = Math.max(nextFeet, effectiveGround);
+            motion.jumpOffset = nextY - effectiveGround;
+            motion.grounded = false;
+        }
+    }
+    else if (!submerged && player.position[1] - effectiveGround > stepHeight) {
+        // Walked off a ledge taller than a step (a crate edge, a cliff): fall under gravity from here
+        // instead of teleporting the feet down to the ground in one frame.
+        nextY = player.position[1];
+        motion.jumpOffset = nextY - effectiveGround;
+        motion.verticalVelocity = 0;
+        motion.grounded = false;
+    }
+    else {
+        nextY = effectiveGround;
+    }
     if (motionBatch !== null && motionBatch.y !== null) {
         nextY = motionBatch.y;
-        motion.jumpOffset = motionBatch.y - groundAtNext;
+        motion.jumpOffset = motionBatch.y - effectiveGround;
     }
-    else if (swimEnabled && waterLevel !== undefined && groundAtNext < waterLevel) {
+    else if (swimEnabled && waterLevel !== undefined && effectiveGround < waterLevel) {
         nextY = waterLevel;
     }
     if (tuning.movement?.beforeCommit !== undefined) {
@@ -238,31 +304,95 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
 /** Feet-to-head span the obstruction test uses; matches `movementModel`'s `OBSTACLE_PLAYER_HEIGHT`. */
 const OBSTACLE_PLAYER_HEIGHT = 1.8;
 /**
- * Largest collider half-extent the bounded broadphase assumes, so an object whose blocking box reaches
- * the player still has its center inside the `inBox` query — a ~4m wall (half-extent ~2m) is caught. An
- * object wider than this on an axis could be missed at its far edge; raise it if a wider blocker exists.
+ * Broadphase reach floor (XZ): the `inBox` query indexes objects by their center *point*, so the query
+ * must extend past the player by at least the largest blocking-collider extent or a wide object's edge
+ * is missed. Floored so default unit boxes stay covered.
  */
 const OBSTACLE_MAX_HALF_EXTENT = 4;
+/**
+ * Hard cap on XZ broadphase reach. City lots ~12–17 m footprint need ~17–20 m after yaw expansion;
+ * beyond that we refuse to grow the query into a city-wide box (and rely on the outer AABB of each
+ * solid still blocking once its *center* is in range).
+ */
+const OBSTACLE_HORIZONTAL_CAP = 22;
+/**
+ * Vertical broadphase floor/cap. Player only needs nearby ground props / step-ups — never full tower
+ * height. Using building height for Y was the Vice Isle pose killer: a 50 m tower turned `inBox` into
+ * a 100³ empty cell walk every frame.
+ */
+const OBSTACLE_VERTICAL_FLOOR = 3;
+const OBSTACLE_VERTICAL_CAP = 8;
+/**
+ * Mesh compound `boxes` under this count are treated as intentional openings (archways). Above it we
+ * walk against the outer fitted AABB only — solid city buildings often ship dense box soups that
+ * multiply narrowphase cost without changing the blocked footprint.
+ */
+const MOVEMENT_MESH_BOX_BUDGET = 12;
+/**
+ * Largest blocking reach in the scene, split into horizontal vs vertical and hard-capped. Cached per
+ * ctx and recomputed when the object count changes.
+ */
+function obstacleReachFor(ctx, store) {
+    const objects = ctx.scene.object.list();
+    const cache = store.obstacleReach;
+    if (cache.count === objects.length)
+        return cache.value;
+    let horizontal = OBSTACLE_MAX_HALF_EXTENT;
+    let vertical = OBSTACLE_VERTICAL_FLOOR;
+    for (const object of objects) {
+        const set = ctx.scene.object.collidersOf(object.instanceId);
+        if (set === null)
+            continue;
+        for (const collider of resolveColliders(set)) {
+            if (!collider.blocks || collider.purpose !== "physical")
+                continue;
+            const shape = collider.shape;
+            const offset = shape.offset;
+            const ox = offset !== undefined ? Math.abs(offset[0]) : 0;
+            const oy = offset !== undefined ? Math.abs(offset[1]) : 0;
+            const oz = offset !== undefined ? Math.abs(offset[2]) : 0;
+            if (shape.kind === "sphere") {
+                horizontal = Math.max(horizontal, ox + oz + shape.radius);
+                vertical = Math.max(vertical, oy + shape.radius);
+            }
+            else {
+                // Horizontal bound sums both axes so any yaw of the box stays covered.
+                const h = shape.halfExtents;
+                horizontal = Math.max(horizontal, ox + oz + h[0] + h[2]);
+                vertical = Math.max(vertical, oy + h[1]);
+            }
+        }
+    }
+    const value = {
+        horizontal: Math.min(horizontal, OBSTACLE_HORIZONTAL_CAP),
+        vertical: Math.min(vertical, OBSTACLE_VERTICAL_CAP),
+    };
+    cache.count = objects.length;
+    cache.value = value;
+    return value;
+}
 /**
  * Gather the player's nearby blocking obstacles from resolved colliders — the mesh-accurate replacement
  * for the old `nearbyObstacles(list(), …)` which emitted a default 1×1×1 box per object. Bounded by an
- * `inBox` broadphase (reach ≥ player radius + max half-extent so wide walls can't be missed), then, per
- * candidate, keeps only blocking physical colliders and emits their real half-extents/offset (or, for a
- * mesh collider carrying `boxes`, the compound sub-boxes), conservatively yaw-rotated by the object's
- * `rotationY`. Objects with no resolved collider fall back to the default box; objects whose colliders
- * don't block stop obstructing. Runs for both the shell's local player and a host, so parity is automatic.
+ * `inBox` broadphase (reach ≥ player radius + the scene's max blocking extent so wide walls can't be
+ * missed), then, per candidate, keeps only blocking physical colliders and emits their real
+ * half-extents/offset (or, for a mesh collider carrying a small `boxes` set, the compound sub-boxes),
+ * conservatively yaw-rotated by the object's `rotationY`. Objects with no resolved collider fall back
+ * to the default box; objects whose colliders don't block stop obstructing. Runs for both the shell's
+ * local player and a host, so parity is automatic.
  */
-function gatherMovementObstacles(ctx, position, stepX, stepZ) {
-    const reachX = Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS + OBSTACLE_MAX_HALF_EXTENT;
-    const reachZ = Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS + OBSTACLE_MAX_HALF_EXTENT;
+function gatherMovementObstacles(ctx, store, position, stepX, stepZ) {
+    const reach = obstacleReachFor(ctx, store);
+    const reachX = Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS + reach.horizontal;
+    const reachZ = Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS + reach.horizontal;
     const min = [
         position[0] - reachX,
-        position[1] - OBSTACLE_MAX_HALF_EXTENT,
+        position[1] - reach.vertical,
         position[2] - reachZ,
     ];
     const max = [
         position[0] + reachX,
-        position[1] + OBSTACLE_PLAYER_HEIGHT + OBSTACLE_MAX_HALF_EXTENT,
+        position[1] + OBSTACLE_PLAYER_HEIGHT + reach.vertical,
         position[2] + reachZ,
     ];
     const obstacles = [];
@@ -282,13 +412,19 @@ function gatherMovementObstacles(ctx, position, stepX, stepZ) {
     return obstacles;
 }
 /** One blocking collider as a {@link CollisionObstacle}: a compound `boxes` obstacle for a mesh collider
- * carrying sub-boxes, else a single half-extents/offset AABB. Yaw is applied by conservatively expanding
- * each AABB to its rotated extent (mirroring `worldOffset`), so the obstruction never under-covers. */
+ * carrying a small sub-box set (openings), else a single half-extents/offset AABB. Yaw is applied by
+ * conservatively expanding each AABB to its rotated extent (mirroring `worldOffset`), so the obstruction
+ * never under-covers. */
 function obstacleFromCollider(collider, position, rotationY) {
     const cos = Math.cos(rotationY);
     const sin = Math.sin(rotationY);
     const shape = collider.shape;
-    if (shape.kind === "mesh" && shape.boxes !== undefined && shape.boxes.length > 0) {
+    // Dense compound soups (city buildings) collapse to the outer fitted AABB for movement — openings
+    // only stay mesh-box accurate when the box count is small (arches, doorways).
+    if (shape.kind === "mesh" &&
+        shape.boxes !== undefined &&
+        shape.boxes.length > 0 &&
+        shape.boxes.length <= MOVEMENT_MESH_BOX_BUDGET) {
         return {
             position,
             boxes: shape.boxes.map((b) => yawExpandLocalBox(b.min, b.max, cos, sin)),

package/dist/physics/drivableVehicle.js

@@ -8,7 +8,9 @@
 export function tickDrivableVehicle(vehicle, dt, axis, options = {}) {
     const step = vehicle.tick(dt, axis, options.modifiers);
     const [x, y, z] = step.position;
-    const resolvedY = options.groundHeight === undefined ? y : options.groundHeight(x, z);
+    // Ground-snap first, then lift by any hop in progress, so a jumping vehicle still follows the
+    // terrain beneath it instead of hanging at a fixed world height over a slope.
+    const resolvedY = (options.groundHeight === undefined ? y : options.groundHeight(x, z)) + step.airOffset;
     return {
         pose: { position: [x, resolvedY, z], rotationX: step.bodyPitch, rotationY: step.heading, rotationZ: step.bodyRoll, dt },
         step,

package/dist/physics/kinematicVehicle.d.ts

@@ -12,6 +12,28 @@ export interface KinematicVehicleTuning {
     handbrakeGrip: number;
     /** Forward-speed decay per second when coasting (sleds, boats); default `0`. */
     rollingResistance?: number;
+    /**
+     * Constant coast deceleration in world units/s², applied when the throttle is lifted and the brake
+     * is not driving reverse. Unlike `rollingResistance` (a proportional decay, so a fast car sheds
+     * speed quickly and a slow one crawls forever), this is the flat road-load feel karts and arcade
+     * racers want; it is capped at `|speed| / dt` so coasting can never push the vehicle backwards.
+     * The `chassis` block derives this from mass and gearing instead — set one or the other, not both.
+     * Default `0` (coast forever).
+     */
+    coastDeceleration?: number;
+    /**
+     * Reverse drive force as a fraction of `engineAccel`, for the arcade path. Reverse is intentionally
+     * softer than forward; raise it for karts that need a brisk backup, lower it for heavy vehicles.
+     * Default {@link DEFAULT_REVERSE_FORCE_SCALE}. With a `chassis` block, `chassis.reverseForceScale`
+     * takes precedence.
+     */
+    reverseForceScale?: number;
+    /**
+     * Downward acceleration in world units/s² applied to the vehicle's hop/air state, enabling
+     * {@link KinematicVehicle.hop}. Omit to disable vertical motion entirely, which keeps every
+     * existing ground vehicle on the flat path with no air state to integrate.
+     */
+    hopGravity?: number;
     /** Optional higher-fidelity powertrain. Omit to preserve the direct arcade acceleration model. */
     powertrain?: KinematicPowertrainTuning;
     /** Optional bicycle-model steering with speed-sensitive lock and smoothed rack response. */
@@ -49,6 +71,11 @@ export interface KinematicChassisTuning {
     comHeight: number;
     /** Lateral wheel spacing (track width), m; larger resists lateral weight transfer. */
     trackWidth: number;
+    /**
+     * Reverse drive force as a fraction of `engineForce` (default {@link DEFAULT_REVERSE_FORCE_SCALE}).
+     * Real gearboxes and games both keep reverse much softer than forward launch.
+     */
+    reverseForceScale?: number;
 }
 /** Data-first gearbox and torque-curve tuning for a kinematic ground vehicle. */
 export interface KinematicPowertrainTuning {
@@ -111,6 +138,11 @@ export interface KinematicVehicleModifiers {
     accelScale?: number;
     /** Scale turn rate this tick (brace penalty, heavy-load steering). */
     turnRateScale?: number;
+    /**
+     * Scale braking force this tick (worn pads, ice, a brace bonus that stiffens the whole drivetrain).
+     * Separate from `accelScale` because stronger drive and stronger brakes are not the same upgrade.
+     */
+    brakeScale?: number;
 }
 export interface KinematicVehicleStep {
     position: readonly [number, number, number];
@@ -138,6 +170,14 @@ export interface KinematicVehicleStep {
     wheelspin: boolean;
     bodyPitch: number;
     bodyRoll: number;
+    /**
+     * Height above the vehicle's ground plane from an in-progress hop, world units; `0` while grounded
+     * and always `0` without `hopGravity`. `tickDrivableVehicle` adds this on top of the sampled ground
+     * height, so a hopping vehicle still follows terrain underneath it.
+     */
+    airOffset: number;
+    /** `true` while `airOffset > 0` — gate landing effects, air control, and trick scoring off this. */
+    airborne: boolean;
 }
 /**
  * The pure-kinematic arcade car every racing game hand-rolled (#282.1): steer-yaw scaled by speed,
@@ -154,6 +194,21 @@ export interface KinematicVehicle {
     velocity(): readonly [number, number];
     /** Scale the current velocity (boost pads, hard collisions). */
     scaleVelocity(factor: number): void;
+    /**
+     * Launch the vehicle upward with the given vertical impulse (world units/s). Returns `false` — and
+     * changes nothing — when the vehicle is already airborne or the tuning has no `hopGravity`, so a
+     * held jump key cannot ratchet a vehicle into orbit.
+     */
+    hop(impulse: number): boolean;
+    /**
+     * Replace the tuning in place, keeping position, heading, velocity and gear state. This is the
+     * seam for vehicles whose stats change during play — an installed part, a damaged engine, a
+     * temporary debuff — which must NOT cost the vehicle its momentum the way rebuilding the sim
+     * would. For a change that lasts a single tick, pass {@link KinematicVehicleModifiers} instead.
+     */
+    retune(next: KinematicVehicleTuning): void;
     resetTo(position: readonly [number, number, number], heading: number): void;
 }
-export declare function createKinematicVehicle(tuning: KinematicVehicleTuning, options?: KinematicVehicleOptions): KinematicVehicle;
+export declare function createKinematicVehicle(initialTuning: KinematicVehicleTuning, options?: KinematicVehicleOptions): KinematicVehicle;
+/** Default reverse drive force as a fraction of forward `engineForce` / `engineAccel`. */
+export declare const DEFAULT_REVERSE_FORCE_SCALE = 0.48;