@jgengine/core 0.18.0 → 0.19.0

package/dist/movement/playerMovement.js

@@ -1,6 +1,9 @@
+import { createInputBuffer } from "../input/inputBuffer.js";
 import { applyHorizontalImpulses, applyMotionImpulses } from "../runtime/motionIntents.js";
+import { createCharacterController, } from "./characterController.js";
 import { groundFieldFor, hasEnvironmentTerrain, sampleSlope } from "../world/terrain.js";
-import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, DEFAULT_OBSTACLE_PLAYER_RADIUS, obstacleSupportHeight, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, } from "./movementModel.js";
+import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, DEFAULT_OBSTACLE_PLAYER_RADIUS, obstacleSupportHeight, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, MOVEMENT_TUNING, } from "./movementModel.js";
+import { advanceFreeFlight, createFreeFlightState, resolveFlightStep, resolveFreeFlightIntentFromInput, } from "./freeFlight.js";
 import { solidObstaclesNear } from "./solidObstacles.js";
 import { approachYaw, steerYaw } from "./steering.js";
 import { advanceVoxelPlayer, createVoxelPlayerBody, } from "./voxelController.js";
@@ -34,11 +37,40 @@ export function resolvePhysicsTuning(physics) {
 export function resolvePlayerMovementTuning(opts) {
     const physics = resolvePhysicsTuning(opts.physics);
     const backpedal = opts.movement?.backpedalMult;
-    const overrides = backpedal === undefined ? physics : { ...(physics ?? {}), backpedalSpeedMultiplier: backpedal };
+    const feel = opts.movement?.feel;
+    const feelOverrides = {
+        ...(backpedal === undefined ? {} : { backpedalSpeedMultiplier: backpedal }),
+        ...(feel?.groundAcceleration === undefined ? {} : { groundAcceleration: feel.groundAcceleration }),
+        ...(feel?.airAcceleration === undefined ? {} : { airAcceleration: feel.airAcceleration }),
+        ...(feel?.groundFriction === undefined ? {} : { groundFriction: feel.groundFriction }),
+        ...(feel?.runMultiplier === undefined ? {} : { runSpeedMultiplier: feel.runMultiplier }),
+        ...(feel?.crouchMultiplier === undefined ? {} : { crouchSpeedMultiplier: feel.crouchMultiplier }),
+        ...(feel?.jumpBufferMs === undefined ? {} : { jumpBufferMs: feel.jumpBufferMs }),
+        ...(feel?.coyoteMs === undefined ? {} : { coyoteMs: feel.coyoteMs }),
+        ...(feel?.jumpCutFactor === undefined ? {} : { jumpCutFactor: feel.jumpCutFactor }),
+        ...(feel?.apexGravityScale === undefined ? {} : { apexGravityScale: feel.apexGravityScale }),
+        ...(feel?.apexSpeed === undefined ? {} : { apexSpeed: feel.apexSpeed }),
+        ...(feel?.fallGravityScale === undefined ? {} : { fallGravityScale: feel.fallGravityScale }),
+        ...(feel?.landingRecoveryMs === undefined ? {} : { landingRecoveryMs: feel.landingRecoveryMs }),
+        ...(feel?.landingSpeedScale === undefined ? {} : { landingSpeedScale: feel.landingSpeedScale }),
+    };
+    const overrides = Object.keys(feelOverrides).length === 0 ? physics : { ...(physics ?? {}), ...feelOverrides };
     return {
         ...(opts.collision === undefined ? {} : { collision: opts.collision }),
         ...(opts.movement === undefined ? {} : { movement: opts.movement }),
         ...(overrides === undefined ? {} : { physics: overrides }),
+        ...(opts.physics?.backend === undefined
+            ? {}
+            : {
+                controller: {
+                    backend: opts.physics.backend,
+                    capsule: opts.physics.controller ?? {
+                        radius: DEFAULT_OBSTACLE_PLAYER_RADIUS,
+                        height: 1.8,
+                        stepHeight: DEFAULT_PLAYER_STEP_HEIGHT,
+                    },
+                },
+            }),
         ground: groundFieldFor(opts.world),
         hasTerrain: hasEnvironmentTerrain(opts.world),
     };
@@ -58,7 +90,17 @@ function storeFor(ctx) {
 function stateFor(store, userId) {
     let state = store.players.get(userId);
     if (state === undefined) {
-        state = { heading: 0, facing: null, voxelBody: null, motion: null };
+        state = {
+            heading: 0,
+            facing: null,
+            voxelBody: null,
+            motion: null,
+            flight: null,
+            controller: null,
+            controllerJumpHeld: false,
+            jumpBuffer: null,
+            pendingController: null,
+        };
         store.players.set(userId, state);
     }
     return state;
@@ -67,6 +109,54 @@ function stateFor(store, userId) {
 export function playerMovementHeading(ctx, userId) {
     return stores.get(ctx)?.players.get(userId)?.heading ?? 0;
 }
+function copyController(state) {
+    return { ...state, position: [...state.position], groundNormal: [...state.groundNormal] };
+}
+/** Copy one player's movement state for prediction, rollback or a save; `null` when the player has not moved yet. */
+export function snapshotPlayerMovement(ctx, userId) {
+    const state = stores.get(ctx)?.players.get(userId);
+    if (state === undefined)
+        return null;
+    const controller = state.controller?.snapshot() ?? state.pendingController;
+    return {
+        heading: state.heading,
+        facing: state.facing,
+        voxelBody: state.voxelBody === null ? null : { ...state.voxelBody },
+        motion: state.motion === null ? null : { ...state.motion },
+        flight: state.flight === null ? null : { ...state.flight },
+        controller: controller === null ? null : copyController(controller),
+        controllerJumpHeld: state.controllerJumpHeld,
+        jumpBuffer: state.jumpBuffer?.snapshot() ?? null,
+    };
+}
+/** Put a player's movement state back to a {@link snapshotPlayerMovement} copy, so the next {@link stepPlayerMovement} replays from there. */
+export function restorePlayerMovement(ctx, userId, snapshot) {
+    const state = stateFor(storeFor(ctx), userId);
+    state.heading = snapshot.heading;
+    state.facing = snapshot.facing;
+    state.voxelBody = snapshot.voxelBody === null ? null : { ...snapshot.voxelBody };
+    state.motion = snapshot.motion === null ? null : { ...snapshot.motion };
+    state.flight = snapshot.flight === null ? null : { ...snapshot.flight };
+    state.controllerJumpHeld = snapshot.controllerJumpHeld;
+    const jumpBuffer = snapshot.jumpBuffer ?? null;
+    if (jumpBuffer === null) {
+        state.jumpBuffer = null;
+    }
+    else {
+        state.jumpBuffer ??= createInputBuffer({ windowMs: jumpBuffer.windowMs });
+        state.jumpBuffer.restore(jumpBuffer);
+    }
+    const controller = snapshot.controller === null ? null : copyController(snapshot.controller);
+    if (state.controller !== null && controller !== null) {
+        state.controller.restore(controller);
+        state.pendingController = null;
+    }
+    else {
+        if (controller === null)
+            state.controller = null;
+        state.pendingController = controller;
+    }
+}
 /** Drop a player's retained movement state (heading + kinematic body) — call on leave so a rejoin starts fresh instead of resuming stale velocity. */
 export function forgetPlayerMovement(ctx, userId) {
     stores.get(ctx)?.players.delete(userId);
@@ -90,15 +180,41 @@ function resolveBodyFacing(state, moving, velocityX, velocityZ, fallbackYaw, tur
     state.facing = next;
     return next;
 }
+function flightTuningFor(movement, ctx) {
+    const cfg = movement?.flight;
+    if (cfg === undefined || cfg === false)
+        return null;
+    if (cfg === true)
+        return { mode: "creative" };
+    if (typeof cfg === "object") {
+        if (cfg.canFly !== undefined && !cfg.canFly(ctx))
+            return null;
+        return {
+            mode: cfg.mode ?? "creative",
+            speed: cfg.speed,
+            verticalSpeed: cfg.verticalSpeed,
+            sprintMultiplier: cfg.sprintMultiplier,
+            acceleration: cfg.acceleration,
+            gravity: cfg.gravity,
+            thrust: cfg.thrust,
+            alignWithLook: cfg.alignWithLook,
+            collide: cfg.collide,
+            bindings: cfg.bindings,
+            camera: cfg.camera ?? null,
+        };
+    }
+    return null;
+}
 /**
  * Integrate one player's movement for a tick from their held-input frame and commit the pose — the single
  * genre-agnostic controller both the shell (its local player) and a host (each connected player in `onTick`) call,
  * so single-player and server-authoritative movement are identical. Reads the player's controlled entity, terrain,
  * scene solids, and pending motion impulses; writes the entity pose via `setPose`. Retains heading + kinematic body
  * per `userId` on the `ctx`. Pass `heading` to override the internally-integrated yaw (the shell owns yaw for its
- * camera); omit it and the controller turns from the frame's `turnLeft`/`turnRight` actions.
+ * camera); omit it and the controller turns from the frame's `turnLeft`/`turnRight` actions. Pass `pitch` for
+ * 6DOF spectator flight when `alignWithLook` is set.
  */
-export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
+export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitch) {
     const playerId = ctx.player.possession.active(userId);
     const player = ctx.scene.entity.get(playerId);
     if (player === null)
@@ -141,6 +257,181 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
     const intent = resolveMovementIntent(keys, true, analogMove);
     const motionBatch = ctx.player.motionFor(userId).takePending();
     const walkSpeed = player.movement?.walkSpeed ?? DEFAULT_WALK_SPEED;
+    const flightTuning = flightTuningFor(tuning.movement, ctx);
+    if (flightTuning !== null) {
+        const value = (action) => input.analog?.[action] ?? (isDown(action) ? 1 : 0);
+        let flightIntent = resolveFreeFlightIntentFromInput(isDown, value, input.pointer, flightTuning.bindings);
+        if (tuning.movement?.canSprint !== undefined && !tuning.movement.canSprint(ctx)) {
+            flightIntent = { ...flightIntent, sprint: false };
+        }
+        let flightState = state.flight;
+        if (flightState === null) {
+            flightState = createFreeFlightState();
+            state.flight = flightState;
+        }
+        if (motionBatch !== null) {
+            flightState.vy = applyMotionImpulses(flightState.vy, motionBatch);
+            const [hx, hz] = applyHorizontalImpulses(flightState.vx, flightState.vz, motionBatch);
+            flightState.vx = hx;
+            flightState.vz = hz;
+        }
+        const normalizedFlightTuning = {
+            mode: flightTuning.mode,
+            speed: flightTuning.speed,
+            verticalSpeed: flightTuning.verticalSpeed,
+            sprintMultiplier: flightTuning.sprintMultiplier,
+            acceleration: flightTuning.acceleration,
+            gravity: flightTuning.gravity,
+            thrust: flightTuning.thrust,
+            alignWithLook: flightTuning.alignWithLook,
+            collide: flightTuning.collide,
+            bindings: flightTuning.bindings,
+            camera: flightTuning.camera,
+        };
+        if (normalizedFlightTuning.collide === undefined) {
+            normalizedFlightTuning.collide = normalizedFlightTuning.mode === "creative" || normalizedFlightTuning.mode === "hover";
+        }
+        if (normalizedFlightTuning.camera !== undefined) {
+            const cam = ctx.camera;
+            cam?.setChaseTuning(normalizedFlightTuning.camera ?? null);
+        }
+        const step = advanceFreeFlight(flightState, flightIntent, state.heading, pitch, dt, normalizedFlightTuning);
+        let stepX = step.stepX;
+        let stepY = step.stepY;
+        let stepZ = step.stepZ;
+        if (normalizedFlightTuning.collide !== false && tuning.movement?.collideObjects !== false) {
+            const obstacles = gatherMovementObstacles(ctx, player.position, stepX, stepZ);
+            const verticalResolved = resolveFlightStep(player.position, stepX, stepY, stepZ, obstacles, DEFAULT_OBSTACLE_PLAYER_RADIUS);
+            stepY = verticalResolved.stepY;
+            const xzResolved = resolveObstacleStep(player.position, stepX, stepZ, obstacles, DEFAULT_OBSTACLE_PLAYER_RADIUS, 0);
+            stepX = xzResolved.stepX;
+            stepZ = xzResolved.stepZ;
+            const ground = tuning.ground.sampleHeight(player.position[0] + stepX, player.position[2] + stepZ);
+            const nextY = player.position[1] + stepY;
+            if (nextY < ground + 0.2) {
+                stepY = ground + 0.2 - player.position[1];
+                if (flightState.vy < 0)
+                    flightState.vy = 0;
+            }
+        }
+        let nextX = player.position[0] + stepX;
+        let nextY = player.position[1] + stepY;
+        let nextZ = player.position[2] + stepZ;
+        if (motionBatch !== null && motionBatch.y !== null) {
+            nextY = motionBatch.y;
+        }
+        if (tuning.movement?.beforeCommit !== undefined) {
+            const frame = {
+                entityId: playerId,
+                current: player.position,
+                next: [nextX, nextY, nextZ],
+                dt,
+                ctx,
+            };
+            const replacement = tuning.movement.beforeCommit(frame);
+            if (replacement !== undefined) {
+                nextX = replacement[0];
+                nextY = replacement[1];
+                nextZ = replacement[2];
+            }
+        }
+        ctx.scene.entity.setPose(playerId, {
+            position: [nextX, nextY, nextZ],
+            rotationY: resolveBodyFacing(state, flightIntent.moving, flightState.vx, flightState.vz, player.rotationY, tuning.movement?.turnSpeed, dt),
+            dt,
+        });
+        return;
+    }
+    if (flightTuning === null && state.flight !== null) {
+        const cam = ctx.camera;
+        cam?.setChaseTuning(null);
+    }
+    if (tuning.controller !== undefined) {
+        let controller = state.controller;
+        if (controller === null) {
+            controller = createCharacterController(tuning.controller.capsule);
+            state.controller = controller;
+            controller.restore(state.pendingController ?? {
+                position: [player.position[0], player.position[1], player.position[2]],
+                verticalVelocity: 0,
+                grounded: true,
+                groundNormal: [0, 1, 0],
+                groundBody: null,
+                crouching: false,
+            });
+            state.pendingController = null;
+        }
+        const controllerState = controller.state();
+        if (Math.hypot(controllerState.position[0] - player.position[0], controllerState.position[1] - player.position[1], controllerState.position[2] - player.position[2]) > 1e-6) {
+            controller.restore({
+                ...controllerState,
+                position: [player.position[0], player.position[1], player.position[2]],
+                grounded: false,
+                groundBody: null,
+            });
+        }
+        // Keep the existing input feel and horizontal impulse seam; the capsule owns vertical motion and collision.
+        let horizontal = state.motion;
+        if (horizontal === null) {
+            horizontal = createPlayerMotionState();
+            state.motion = horizontal;
+        }
+        const grounded = controller.state().grounded;
+        horizontal.grounded = grounded;
+        horizontal.verticalVelocity = 0;
+        horizontal.jumpOffset = 0;
+        [horizontal.horizontalVelocityX, horizontal.horizontalVelocityZ] = applyHorizontalImpulses(horizontal.horizontalVelocityX, horizontal.horizontalVelocityZ, motionBatch);
+        const jumpPressed = intent.jumping && !state.controllerJumpHeld;
+        const horizontalStep = advancePlayerMotion(horizontal, { ...intent, jumping: false }, forwardX, forwardZ, walkSpeed, dt, tuning.physics);
+        horizontal.grounded = grounded;
+        horizontal.verticalVelocity = 0;
+        horizontal.jumpOffset = 0;
+        state.controllerJumpHeld = intent.jumping;
+        const current = controller.state();
+        controller.restore({
+            ...current,
+            verticalVelocity: applyMotionImpulses(current.verticalVelocity, motionBatch),
+        });
+        const result = controller.move(tuning.controller.backend, {
+            motion: [horizontalStep.stepX, 0, horizontalStep.stepZ],
+            dt,
+            gravity: tuning.physics?.gravityAcceleration ?? MOVEMENT_TUNING.gravityAcceleration,
+            ...(jumpPressed && !intent.crouching
+                ? { jumpVelocity: tuning.physics?.jumpVelocity ?? MOVEMENT_TUNING.jumpVelocity }
+                : {}),
+            crouch: intent.crouching,
+        });
+        let nextPosition = [
+            controller.state().position[0],
+            controller.state().position[1],
+            controller.state().position[2],
+        ];
+        if (motionBatch !== null && motionBatch.y !== null) {
+            nextPosition[1] = motionBatch.y;
+            controller.restore({ ...controller.state(), position: nextPosition });
+        }
+        if (tuning.movement?.beforeCommit !== undefined) {
+            const frame = {
+                entityId: playerId,
+                current: player.position,
+                next: nextPosition,
+                dt,
+                ctx,
+            };
+            const replacement = tuning.movement.beforeCommit(frame);
+            if (replacement !== undefined) {
+                nextPosition = [replacement[0], replacement[1], replacement[2]];
+                controller.restore({ ...controller.state(), position: nextPosition });
+            }
+        }
+        horizontal.grounded = result.grounded;
+        ctx.scene.entity.setPose(playerId, {
+            position: nextPosition,
+            rotationY: resolveBodyFacing(state, intent.moving, horizontal.horizontalVelocityX, horizontal.horizontalVelocityZ, player.rotationY, tuning.movement?.turnSpeed, dt),
+            dt,
+        });
+        return;
+    }
     if (tuning.collision?.voxel === true) {
         let body = state.voxelBody;
         if (body === null) {
@@ -187,9 +478,15 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
     const submerged = swimEnabled &&
         waterLevel !== undefined &&
         tuning.ground.sampleHeight(player.position[0], player.position[2]) < waterLevel;
+    const jumpBufferMs = tuning.physics?.jumpBufferMs ?? 0;
+    let jumpBuffer = state.jumpBuffer;
+    if (jumpBuffer === null) {
+        jumpBuffer = createInputBuffer({ windowMs: jumpBufferMs });
+        state.jumpBuffer = jumpBuffer;
+    }
     const motionOptions = submerged
-        ? { speedScale: swimSpeedMultiplier, floating: true }
-        : undefined;
+        ? { speedScale: swimSpeedMultiplier, floating: true, buffer: jumpBuffer }
+        : { buffer: jumpBuffer };
     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

package/dist/movement/serverStep.d.ts

@@ -0,0 +1,5 @@
+import type { GameContext } from "../runtime/gameContext.js";
+import type { InputFrame } from "../runtime/inputSnapshot.js";
+import { type PlayerMovementTuning } from "./playerMovement.js";
+/** Advance one authoritative player's movement using the same controller as the shell. */
+export declare function serverStep(ctx: GameContext, userId: string, frame: InputFrame, dt: number, tuning?: PlayerMovementTuning): void;

package/dist/movement/serverStep.js

@@ -0,0 +1,6 @@
+import { groundFieldFor } from "../world/terrain.js";
+import { stepPlayerMovement } from "./playerMovement.js";
+/** Advance one authoritative player's movement using the same controller as the shell. */
+export function serverStep(ctx, userId, frame, dt, tuning) {
+    stepPlayerMovement(ctx, userId, frame, dt, tuning ?? { ground: groundFieldFor(), hasTerrain: false });
+}

package/dist/movement/solidObstacles.d.ts

@@ -1,6 +1,7 @@
 import type { GameContext } from "../runtime/gameContext.js";
 import { resolveColliders, type ResolvedCollider } from "../scene/colliders.js";
 import type { EntityPosition } from "../scene/entityStore.js";
+import type { WorldSolid } from "../world/worldSolids.js";
 import { type CollisionObstacle } from "./movementModel.js";
 /** Largest blocking-collider extent in the scene, split so tower height cannot inflate the XZ query. */
 export interface ObstacleReach {
@@ -11,8 +12,8 @@ export interface ObstacleReach {
 }
 /**
  * The slice of the scene's object store this query needs. Narrow on purpose: the scene context wires
- * its own store here while it is still being constructed, and `ctx.scene.object` satisfies it as-is.
- * @internal
+ * its own store here while it is still being constructed, `ctx.scene.object` satisfies it as-is, and a
+ * pure rules package with no `GameContext` to import can satisfy it from its own object list.
  */
 export interface SolidObstacleSource {
     list(): readonly {
@@ -27,12 +28,12 @@ export interface SolidObstacleSource {
     }[];
     collidersOf(instanceId: string): Parameters<typeof resolveColliders>[0] | null;
 }
-/** Mutable reach cache; one per source, invalidated by object count. @internal */
+/** Mutable reach cache; one per source, invalidated by object count. */
 export interface ObstacleReachCache {
     count: number;
     value: ObstacleReach;
 }
-/** A fresh {@link ObstacleReachCache} for a caller that owns its own source. @internal */
+/** A fresh {@link ObstacleReachCache} for a caller that owns its own source. */
 export declare function createObstacleReachCache(): ObstacleReachCache;
 /**
  * Largest blocking reach in the scene, split into horizontal vs vertical and hard-capped. Cached per
@@ -41,7 +42,7 @@ export declare function createObstacleReachCache(): ObstacleReachCache;
  * @internal
  */
 export declare function solidObstacleReach(ctx: GameContext): ObstacleReach;
-/** {@link solidObstacleReach} against a bare source and caller-owned cache. @internal */
+/** {@link solidObstacleReach} against a bare source and caller-owned cache. */
 export declare function sourceObstacleReach(source: SolidObstacleSource, cache: ObstacleReachCache): ObstacleReach;
 /** One blocking collider as a {@link CollisionObstacle}: a compound `boxes` obstacle for a mesh collider
  * carrying a small sub-box set (openings), else a single half-extents/offset AABB. Yaw is applied by
@@ -49,9 +50,16 @@ export declare function sourceObstacleReach(source: SolidObstacleSource, cache:
  * never under-covers.
  * @internal */
 export declare function obstacleFromCollider(collider: ResolvedCollider, position: EntityPosition, rotationY: number): CollisionObstacle;
+/**
+ * A {@link WorldSolid} as a {@link CollisionObstacle}. Axis-aligned solids are one box; a yawed solid is
+ * cut into strips along its long axis, each fitted with an AABB, so a turned building does not block
+ * the street beside it the way a single enclosing box would.
+ * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
+ */
+export declare function obstacleFromSolid(solid: WorldSolid): CollisionObstacle;
 /**
  * Every blocking physical obstacle overlapping the box `position` ± `reachX`/`reachZ`, read from the
- * scene's resolved colliders.
+ * scene's resolved colliders and `ctx.world.solids`.
  *
  * This is the engine's single answer to "what is solid here". The player resolver, a walking NPC, and
  * anything else that has to stop at a wall read it rather than deriving their own set — three
@@ -61,7 +69,7 @@ export declare function obstacleFromCollider(collider: ResolvedCollider, positio
  * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
  */
 export declare function solidObstaclesNear(ctx: GameContext, position: EntityPosition, reachX: number, reachZ: number, height?: number): CollisionObstacle[];
-/** {@link solidObstaclesNear} against a bare source and an already-resolved reach. @internal */
+/** {@link solidObstaclesNear} against a bare source and an already-resolved reach. */
 export declare function sourceObstaclesNear(source: SolidObstacleSource, reach: ObstacleReach, position: EntityPosition, reachX: number, reachZ: number, height?: number): CollisionObstacle[];
 /**
  * Slide a walker's horizontal step against the same solid geometry that stops the player, returning the
@@ -71,6 +79,11 @@ export declare function sourceObstaclesNear(source: SolidObstacleSource, reach:
  * Bounded by the same broadphase as the player's gather: one `inBox` query sized to this step, never a
  * full-world scan, so it stays affordable per NPC per tick.
  *
+ * The sliding is already axis-separated: X and Z are resolved independently inside, so a caller that
+ * also splits its own movement by axis must hand this exactly one axis per call (`stepZ: 0`, then
+ * `stepX: 0`). Running an axis-split pass over a step this function already resolved double-cuts it,
+ * and the composition is wrong in either order.
+ *
  * @capability walker-solid-step slide an NPC's step against the geometry that blocks the player
  */
 export declare function resolveWalkerStep(ctx: GameContext, position: EntityPosition, stepX: number, stepZ: number, options?: {
@@ -80,7 +93,25 @@ export declare function resolveWalkerStep(ctx: GameContext, position: EntityPosi
     stepX: number;
     stepZ: number;
 };
-/** {@link resolveWalkerStep} against an already-gathered obstacle set. @internal */
+/**
+ * {@link resolveWalkerStep} with no `GameContext`: gather plus slide against a bare
+ * {@link SolidObstacleSource} and a caller-owned {@link ObstacleReachCache}.
+ *
+ * This is the entry point for rules that live in a pure package — no React, no three.js, no engine
+ * context to import. Hold one cache per source for the life of that source (`createObstacleReachCache()`)
+ * rather than making a fresh one per step; it is what keeps the reach scan off the per-step path.
+ * The same axis-separation note as {@link resolveWalkerStep} applies.
+ *
+ * @capability walker-solid-step-source slide a step against solid geometry from a pure rules package
+ */
+export declare function resolveSourceWalkerStep(source: SolidObstacleSource, cache: ObstacleReachCache, position: EntityPosition, stepX: number, stepZ: number, options?: {
+    radius?: number;
+    stepUpHeight?: number;
+}): {
+    stepX: number;
+    stepZ: number;
+};
+/** {@link resolveWalkerStep} against an already-gathered obstacle set. */
 export declare function slideStep(position: EntityPosition, stepX: number, stepZ: number, obstacles: readonly CollisionObstacle[], radius?: number, stepUpHeight?: number): {
     stepX: number;
     stepZ: number;

package/dist/movement/solidObstacles.js

@@ -26,9 +26,13 @@ const OBSTACLE_VERTICAL_CAP = 8;
  * multiply narrowphase cost without changing the blocked footprint.
  */
 const MOVEMENT_MESH_BOX_BUDGET = 12;
+/** Most AABB strips an oriented world solid is sliced into, bounding the corner overhang a yawed box leaves. */
+const SOLID_MAX_STRIPS = 8;
+/** Yaw within this of a quarter turn is treated as axis-aligned (radians). */
+const AXIS_ALIGNED_EPSILON = 1e-4;
 /** Feet-to-head span a walker is tested over — matches the player's, so both agree on what a wall is. */
 const WALKER_HEIGHT = 1.8;
-/** A fresh {@link ObstacleReachCache} for a caller that owns its own source. @internal */
+/** A fresh {@link ObstacleReachCache} for a caller that owns its own source. */
 export function createObstacleReachCache() {
     return { count: -1, value: { horizontal: OBSTACLE_MAX_HALF_EXTENT, vertical: OBSTACLE_VERTICAL_FLOOR } };
 }
@@ -42,7 +46,7 @@ const reachCache = perContext(() => createObstacleReachCache());
 export function solidObstacleReach(ctx) {
     return sourceObstacleReach(ctx.scene.object, reachCache(ctx));
 }
-/** {@link solidObstacleReach} against a bare source and caller-owned cache. @internal */
+/** {@link solidObstacleReach} against a bare source and caller-owned cache. */
 export function sourceObstacleReach(source, cache) {
     const objects = source.list();
     if (cache.count === objects.length)
@@ -141,9 +145,40 @@ export function obstacleFromCollider(collider, position, rotationY) {
         halfExtents: [Math.abs(hx * cos) + Math.abs(hz * sin), hy, Math.abs(hx * sin) + Math.abs(hz * cos)],
     };
 }
+/**
+ * A {@link WorldSolid} as a {@link CollisionObstacle}. Axis-aligned solids are one box; a yawed solid is
+ * cut into strips along its long axis, each fitted with an AABB, so a turned building does not block
+ * the street beside it the way a single enclosing box would.
+ * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
+ */
+export function obstacleFromSolid(solid) {
+    const [hx, hy, hz] = solid.halfExtents;
+    const yaw = solid.rotationY ?? 0;
+    const quarter = yaw / (Math.PI / 2);
+    const nearest = Math.round(quarter);
+    if (Math.abs(quarter - nearest) < AXIS_ALIGNED_EPSILON) {
+        const swapped = Math.abs(nearest) % 2 === 1;
+        return { position: solid.center, halfExtents: swapped ? [hz, hy, hx] : [hx, hy, hz] };
+    }
+    const alongX = hx >= hz;
+    const long = alongX ? hx : hz;
+    const short = Math.max(alongX ? hz : hx, 1e-6);
+    const strips = Math.min(SOLID_MAX_STRIPS, Math.max(1, Math.ceil(long / short)));
+    const cos = Math.cos(yaw);
+    const sin = Math.sin(yaw);
+    const boxes = [];
+    for (let i = 0; i < strips; i += 1) {
+        const from = -long + (2 * long * i) / strips;
+        const to = from + (2 * long) / strips;
+        const boxMin = alongX ? [from, -hy, -hz] : [-hx, -hy, from];
+        const boxMax = alongX ? [to, hy, hz] : [hx, hy, to];
+        boxes.push(yawExpandLocalBox(boxMin, boxMax, cos, sin));
+    }
+    return { position: solid.center, boxes };
+}
 /**
  * Every blocking physical obstacle overlapping the box `position` ± `reachX`/`reachZ`, read from the
- * scene's resolved colliders.
+ * scene's resolved colliders and `ctx.world.solids`.
  *
  * This is the engine's single answer to "what is solid here". The player resolver, a walking NPC, and
  * anything else that has to stop at a wall read it rather than deriving their own set — three
@@ -153,9 +188,16 @@ export function obstacleFromCollider(collider, position, rotationY) {
  * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
  */
 export function solidObstaclesNear(ctx, position, reachX, reachZ, height = WALKER_HEIGHT) {
-    return sourceObstaclesNear(ctx.scene.object, solidObstacleReach(ctx), position, reachX, reachZ, height);
+    const obstacles = sourceObstaclesNear(ctx.scene.object, solidObstacleReach(ctx), position, reachX, reachZ, height);
+    const solids = ctx.world.solids;
+    if (solids.count() === 0)
+        return obstacles;
+    for (const solid of solids.inBox([position[0] - reachX, position[1] - height, position[2] - reachZ], [position[0] + reachX, position[1] + 2 * height, position[2] + reachZ])) {
+        obstacles.push(obstacleFromSolid(solid));
+    }
+    return obstacles;
 }
-/** {@link solidObstaclesNear} against a bare source and an already-resolved reach. @internal */
+/** {@link solidObstaclesNear} against a bare source and an already-resolved reach. */
 export function sourceObstaclesNear(source, reach, position, reachX, reachZ, height = WALKER_HEIGHT) {
     const min = [
         position[0] - reachX - reach.horizontal,
@@ -191,6 +233,11 @@ export function sourceObstaclesNear(source, reach, position, reachX, reachZ, hei
  * Bounded by the same broadphase as the player's gather: one `inBox` query sized to this step, never a
  * full-world scan, so it stays affordable per NPC per tick.
  *
+ * The sliding is already axis-separated: X and Z are resolved independently inside, so a caller that
+ * also splits its own movement by axis must hand this exactly one axis per call (`stepZ: 0`, then
+ * `stepX: 0`). Running an axis-split pass over a step this function already resolved double-cuts it,
+ * and the composition is wrong in either order.
+ *
  * @capability walker-solid-step slide an NPC's step against the geometry that blocks the player
  */
 export function resolveWalkerStep(ctx, position, stepX, stepZ, options = {}) {
@@ -200,7 +247,25 @@ export function resolveWalkerStep(ctx, position, stepX, stepZ, options = {}) {
     const obstacles = solidObstaclesNear(ctx, position, Math.abs(stepX) + radius, Math.abs(stepZ) + radius);
     return slideStep(position, stepX, stepZ, obstacles, radius, options.stepUpHeight ?? 0);
 }
-/** {@link resolveWalkerStep} against an already-gathered obstacle set. @internal */
+/**
+ * {@link resolveWalkerStep} with no `GameContext`: gather plus slide against a bare
+ * {@link SolidObstacleSource} and a caller-owned {@link ObstacleReachCache}.
+ *
+ * This is the entry point for rules that live in a pure package — no React, no three.js, no engine
+ * context to import. Hold one cache per source for the life of that source (`createObstacleReachCache()`)
+ * rather than making a fresh one per step; it is what keeps the reach scan off the per-step path.
+ * The same axis-separation note as {@link resolveWalkerStep} applies.
+ *
+ * @capability walker-solid-step-source slide a step against solid geometry from a pure rules package
+ */
+export function resolveSourceWalkerStep(source, cache, position, stepX, stepZ, options = {}) {
+    if (stepX === 0 && stepZ === 0)
+        return { stepX, stepZ };
+    const radius = options.radius ?? DEFAULT_OBSTACLE_PLAYER_RADIUS;
+    const obstacles = sourceObstaclesNear(source, sourceObstacleReach(source, cache), position, Math.abs(stepX) + radius, Math.abs(stepZ) + radius);
+    return slideStep(position, stepX, stepZ, obstacles, radius, options.stepUpHeight ?? 0);
+}
+/** {@link resolveWalkerStep} against an already-gathered obstacle set. */
 export function slideStep(position, stepX, stepZ, obstacles, radius = DEFAULT_OBSTACLE_PLAYER_RADIUS, stepUpHeight = 0) {
     if (obstacles.length === 0)
         return { stepX, stepZ };

package/dist/movement/voxelController.js

@@ -97,7 +97,7 @@ function supportTopWithin(x, z, fromY, toY, isSolid, dims) {
     }
     return best;
 }
-function targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed) {
+function targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed, tuning) {
     if (!intent.moving)
         return { x: 0, z: 0 };
     let fx = forwardX;
@@ -120,9 +120,9 @@ function targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed) {
     if (magSq < 1e-6)
         return { x: 0, z: 0 };
     const speedMultiplier = intent.crouching
-        ? MOVEMENT_TUNING.crouchSpeedMultiplier
+        ? (tuning?.crouchSpeedMultiplier ?? MOVEMENT_TUNING.crouchSpeedMultiplier)
         : intent.running
-            ? MOVEMENT_TUNING.runSpeedMultiplier
+            ? (tuning?.runSpeedMultiplier ?? MOVEMENT_TUNING.runSpeedMultiplier)
             : 1;
     const targetSpeed = baseSpeed * MOVEMENT_TUNING.walkSpeedMultiplier * speedMultiplier;
     const scale = targetSpeed / Math.sqrt(magSq);
@@ -176,15 +176,15 @@ export function advanceVoxelPlayer(body, intent, forwardX, forwardZ, baseSpeed,
     const dt = Math.min(rawDeltaSeconds, MOVEMENT_TUNING.maxFrameSeconds);
     const gravityAcceleration = tuning?.gravityAcceleration ?? MOVEMENT_TUNING.gravityAcceleration;
     const jumpVelocity = tuning?.jumpVelocity ?? MOVEMENT_TUNING.jumpVelocity;
-    const target = targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed);
+    const target = targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed, tuning);
     const acceleration = body.grounded
-        ? MOVEMENT_TUNING.groundAcceleration
-        : MOVEMENT_TUNING.airAcceleration;
+        ? (tuning?.groundAcceleration ?? MOVEMENT_TUNING.groundAcceleration)
+        : (tuning?.airAcceleration ?? MOVEMENT_TUNING.airAcceleration);
     const accelerationBlend = 1 - Math.exp(-acceleration * dt);
     body.velocityX += (target.x - body.velocityX) * accelerationBlend;
     body.velocityZ += (target.z - body.velocityZ) * accelerationBlend;
     if (!intent.moving && body.grounded) {
-        const friction = Math.exp(-MOVEMENT_TUNING.groundFriction * dt);
+        const friction = Math.exp(-(tuning?.groundFriction ?? MOVEMENT_TUNING.groundFriction) * dt);
         body.velocityX *= friction;
         body.velocityZ *= friction;
     }

package/dist/multiplayer/poseSyncGate.d.ts

@@ -16,4 +16,6 @@ export interface PoseSyncTuning {
 export interface PoseSyncGate {
     evaluate(pose: PlayerPose, nowMs: number): boolean;
 }
-export declare function createPoseSyncGate(tuning: PoseSyncTuning): PoseSyncGate;
+/** Default ten-hertz client pose gate with a five-second heartbeat. */
+export declare const DEFAULT_POSE_SYNC_TUNING: PoseSyncTuning;
+export declare function createPoseSyncGate(tuning?: PoseSyncTuning): PoseSyncGate;