@jgengine/core 0.18.0 → 0.18.1

package/dist/movement/playerMovement.js

@@ -1,6 +1,8 @@
 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";
@@ -39,6 +41,18 @@ export function resolvePlayerMovementTuning(opts) {
         ...(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 +72,7 @@ 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 };
         store.players.set(userId, state);
     }
     return state;
@@ -90,15 +104,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 +181,180 @@ 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({
+                position: [player.position[0], player.position[1], player.position[2]],
+                verticalVelocity: 0,
+                grounded: true,
+                groundNormal: [0, 1, 0],
+                groundBody: null,
+                crouching: false,
+            });
+        }
+        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) {

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

@@ -11,8 +11,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 +27,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 +41,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
@@ -61,7 +61,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 +71,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 +85,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

@@ -28,7 +28,7 @@ const OBSTACLE_VERTICAL_CAP = 8;
 const MOVEMENT_MESH_BOX_BUDGET = 12;
 /** 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 +42,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)
@@ -155,7 +155,7 @@ export function obstacleFromCollider(collider, position, rotationY) {
 export function solidObstaclesNear(ctx, position, reachX, reachZ, height = WALKER_HEIGHT) {
     return sourceObstaclesNear(ctx.scene.object, solidObstacleReach(ctx), position, reachX, reachZ, height);
 }
-/** {@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 +191,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 +205,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/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;

package/dist/multiplayer/poseSyncGate.js

@@ -17,7 +17,15 @@ function poseChanged(a, b, tuning) {
         || Math.abs(a.rotationPitch - b.rotationPitch) > tuning.rotationEpsilon
         || appearanceChanged(a.appearance, b.appearance));
 }
-export function createPoseSyncGate(tuning) {
+/** Default ten-hertz client pose gate with a five-second heartbeat. */
+export const DEFAULT_POSE_SYNC_TUNING = {
+    minIntervalMs: 100,
+    heartbeatMs: 5_000,
+    positionEpsilon: 0.01,
+    verticalEpsilon: 0.01,
+    rotationEpsilon: 0.01,
+};
+export function createPoseSyncGate(tuning = DEFAULT_POSE_SYNC_TUNING) {
     let lastSentPose = null;
     let lastSentAt = 0;
     return {

package/dist/multiplayer/presenceContract.d.ts

@@ -16,6 +16,12 @@ export interface PresencePose {
 export interface PresenceSession<TGameId extends string = string> {
     homeGameId: TGameId;
     externalId: string;
+    viewerChunkKey?: string;
+}
+/** Resident identity used to suppress offline actors while their owner is online. */
+export interface PresenceResidentRow {
+    actorExternalId: string;
+    ownerActorId?: string;
 }
 export interface EnsurePresenceArgs<TGameId extends string = string> {
     gameId: TGameId;

package/dist/multiplayer/presenceModel.d.ts

@@ -22,6 +22,8 @@ export interface IncomingPose {
 export interface PoseSyncRules {
     /** Speed cap (units/sec) for client-authoritative movement. */
     maxSpeed: number;
+    /** Minimum time between accepted pose writes. Defaults to 100 ms. */
+    minIntervalMs?: number;
     /** Vertical offset clamp above floorY (e.g. peak jump height). */
     maxVerticalOffset: number;
     /** World-floor Y used as the base of the jump band. Defaults to 0. */

package/dist/multiplayer/presenceModel.js

@@ -1,6 +1,7 @@
 /** Canonical client-authoritative pose-sync tuning shared by every host transport (WS, Convex). */
 export const DEFAULT_POSE_SYNC_RULES = {
     maxSpeed: 12,
+    minIntervalMs: 100,
     maxVerticalOffset: 3,
     minElapsedSec: 0.05,
     maxElapsedSec: 0.5,
@@ -29,6 +30,16 @@ export function spawnPresenceState(origin = DEFAULT_SPAWN_ORIGIN, nowMs, rules)
 }
 /** @internal */
 export function decidePoseSync(current, incoming, rules, nowMs, floorY) {
+    if (current.lastSeenAtMs !== undefined && nowMs - current.lastSeenAtMs < (rules.minIntervalMs ?? 100)) {
+        return {
+            position: { ...current.position },
+            rotationY: current.rotationY,
+            rotationPitch: current.rotationPitch ?? 0,
+            appearance: current.appearance,
+            changed: false,
+            refreshKeepAlive: false,
+        };
+    }
     const rawElapsedSec = Math.max(0, (nowMs - (current.lastSeenAtMs ?? nowMs)) / 1000);
     const elapsedSec = Math.min(rules.maxElapsedSec, rawElapsedSec);
     const maxDist = rules.maxSpeed * elapsedSec;

package/dist/nav/navMesh.d.ts

@@ -0,0 +1,33 @@
+import type { Vec3 } from "../world/geometry.js";
+/** Explicit traversable connection between two navigation polygons. */
+export interface NavMeshLink {
+    from: number;
+    to: number;
+    cost?: number;
+}
+/** Serializable polygon navigation mesh data. */
+export interface NavMeshData {
+    /** Flat xyz vertex coordinates. Polygon indices refer to triples in this array. */
+    verts: number[];
+    polys: number[][];
+    links: NavMeshLink[];
+    areas?: number[];
+}
+/** Neighbor relationship for one navigation polygon. */
+export interface NavMeshAdjacency {
+    neighbors: number[];
+    cost: number;
+}
+/** Route points and polygons selected through a navigation mesh. */
+export interface NavMeshPath {
+    points: Vec3[];
+    polys: number[];
+}
+/** Build polygon adjacency from shared edges and explicit off-mesh links. */
+export declare function buildNavAdjacency(mesh: NavMeshData): NavMeshAdjacency[];
+/** Return the closest point on the mesh surface, or null for an empty mesh. */
+export declare function closestPoint(mesh: NavMeshData, point: Vec3): Vec3 | null;
+/** A* over polygon centers, followed by deterministic visibility string-pulling. */
+export declare function findPath(mesh: NavMeshData, from: Vec3, to: Vec3): NavMeshPath | null;
+/** True when the segment remains over walkable polygons. */
+export declare function raycastNav(mesh: NavMeshData, from: Vec3, to: Vec3): boolean;