@jgengine/core 0.9.0 → 0.11.0

package/dist/movement/playerMovement.js

@@ -0,0 +1,236 @@
+import { applyHorizontalImpulses, applyMotionImpulses } from "../runtime/motionIntents.js";
+import { groundFieldFor, hasEnvironmentTerrain, sampleSlope } from "../world/terrain.js";
+import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, nearbyObstacles, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, } from "./movementModel.js";
+import { approachYaw, steerYaw } from "./steering.js";
+import { advanceVoxelPlayer, createVoxelPlayerBody, } from "./voxelController.js";
+const DEFAULT_TURN_SPEED = 2.4;
+const DEFAULT_WALK_SPEED = 2;
+const DEFAULT_SWIM_SPEED_MULTIPLIER = 0.65;
+/** Minimum ground-normal `y` the player can stand on before slope-slide kicks in — cos(50°) ≈ 0.643. */
+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;
+/**
+ * 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`
+ * and expect a positive downward magnitude — so gravity is negated here to keep down-pointing gravity pulling down.
+ */
+export function resolvePhysicsTuning(physics) {
+    if (physics === undefined)
+        return undefined;
+    return {
+        get gravityAcceleration() {
+            return physics.gravity === undefined ? undefined : -physics.gravity;
+        },
+        get jumpVelocity() {
+            return physics.jumpVelocity;
+        },
+    };
+}
+/** Gather a game's collision/movement/physics/world config into a {@link PlayerMovementTuning} — call once per world; both the shell and a host pass the result to {@link stepPlayerMovement}. */
+export function resolvePlayerMovementTuning(opts) {
+    const physics = resolvePhysicsTuning(opts.physics);
+    const backpedal = opts.movement?.backpedalMult;
+    const overrides = backpedal === undefined ? physics : { ...(physics ?? {}), backpedalSpeedMultiplier: backpedal };
+    return {
+        ...(opts.collision === undefined ? {} : { collision: opts.collision }),
+        ...(opts.movement === undefined ? {} : { movement: opts.movement }),
+        ...(overrides === undefined ? {} : { physics: overrides }),
+        ground: groundFieldFor(opts.world),
+        hasTerrain: hasEnvironmentTerrain(opts.world),
+    };
+}
+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() } };
+        stores.set(ctx, store);
+    }
+    return store;
+}
+function stateFor(store, userId) {
+    let state = store.players.get(userId);
+    if (state === undefined) {
+        state = { heading: 0, facing: null, voxelBody: null, motion: null };
+        store.players.set(userId, state);
+    }
+    return state;
+}
+/** One player's current heading (radians), integrated by {@link stepPlayerMovement} — the shell reads it back into its camera/aim yaw. */
+export function playerMovementHeading(ctx, userId) {
+    return stores.get(ctx)?.players.get(userId)?.heading ?? 0;
+}
+/** 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);
+}
+/**
+ * Rendered body yaw to commit this frame. With `turnSpeed` unset the body snaps
+ * to its movement heading exactly as before (no opt-in, no behavior change); with
+ * `turnSpeed` set it rotates toward that heading at `turnSpeed` rad/s along the
+ * shortest arc, so strafing and backpedalling read as a turning body rather than
+ * an instant flip. Retained per player so the smoothing is continuous across frames.
+ */
+function resolveBodyFacing(state, moving, velocityX, velocityZ, fallbackYaw, turnSpeed, dt) {
+    if (turnSpeed === undefined) {
+        const snapped = moving ? Math.atan2(velocityX, velocityZ) : fallbackYaw;
+        state.facing = snapped;
+        return snapped;
+    }
+    const from = state.facing ?? fallbackYaw;
+    const target = moving ? Math.atan2(velocityX, velocityZ) : from;
+    const next = approachYaw(from, target, turnSpeed, dt);
+    state.facing = next;
+    return next;
+}
+/**
+ * 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.
+ */
+export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
+    const playerId = ctx.player.possession.active(userId);
+    const player = ctx.scene.entity.get(playerId);
+    if (player === null)
+        return;
+    const store = storeFor(ctx);
+    const state = stateFor(store, userId);
+    const held = new Set(input.held);
+    const isDown = (action) => held.has(action);
+    if (heading !== undefined) {
+        state.heading = heading;
+    }
+    else {
+        const turnInput = (isDown("turnRight") ? 1 : 0) - (isDown("turnLeft") ? 1 : 0);
+        const turnSpeed = tuning.movement?.turnSpeed ?? DEFAULT_TURN_SPEED;
+        if (turnInput !== 0)
+            state.heading = steerYaw(state.heading, turnInput, turnSpeed, dt);
+    }
+    const forwardX = Math.sin(state.heading);
+    const forwardZ = Math.cos(state.heading);
+    const keys = createEmptyMovementKeys();
+    keys.w = isDown("moveForward");
+    keys.s = isDown("moveBack");
+    keys.a = isDown("moveLeft");
+    keys.d = isDown("moveRight");
+    keys.shift = isDown("sprint") && (tuning.movement?.canSprint?.(ctx) ?? true);
+    keys.space = isDown("jump");
+    const intent = resolveMovementIntent(keys, true);
+    const motionBatch = ctx.player.motionFor(userId).takePending();
+    const walkSpeed = player.movement?.walkSpeed ?? DEFAULT_WALK_SPEED;
+    if (tuning.collision?.voxel === true) {
+        let body = state.voxelBody;
+        if (body === null) {
+            body = createVoxelPlayerBody(player.position[0], player.position[1], player.position[2]);
+            state.voxelBody = body;
+        }
+        const objects = ctx.scene.object.list();
+        if (store.solids.count !== objects.length) {
+            store.solids.set = new Set(objects.map((o) => `${o.position[0]},${o.position[1]},${o.position[2]}`));
+            store.solids.count = objects.length;
+        }
+        const solids = store.solids.set;
+        const isSolid = (x, y, z) => solids.has(`${x},${y},${z}`);
+        const dims = {
+            halfWidth: tuning.collision.halfWidth ?? 0.3,
+            height: tuning.collision.height ?? 1.8,
+            stepHeight: tuning.collision.stepHeight ?? 0.6,
+        };
+        body.velocityY = applyMotionImpulses(body.velocityY, motionBatch);
+        [body.velocityX, body.velocityZ] = applyHorizontalImpulses(body.velocityX, body.velocityZ, motionBatch);
+        advanceVoxelPlayer(body, intent, forwardX, forwardZ, walkSpeed, dt, isSolid, dims, tuning.physics, tuning.hasTerrain ? (x, z) => tuning.ground.sampleHeight(x, z) : undefined);
+        if (motionBatch !== null && motionBatch.y !== null)
+            body.y = motionBatch.y;
+        ctx.scene.entity.setPose(playerId, {
+            position: [body.x, body.y, body.z],
+            rotationY: resolveBodyFacing(state, intent.moving, body.velocityX, body.velocityZ, player.rotationY, tuning.movement?.turnSpeed, dt),
+            dt,
+        });
+        return;
+    }
+    let motion = state.motion;
+    if (motion === null) {
+        motion = createPlayerMotionState();
+        state.motion = motion;
+    }
+    motion.verticalVelocity = applyMotionImpulses(motion.verticalVelocity, motionBatch);
+    [motion.horizontalVelocityX, motion.horizontalVelocityZ] = applyHorizontalImpulses(motion.horizontalVelocityX, motion.horizontalVelocityZ, motionBatch);
+    const swimCfg = tuning.movement?.swim;
+    const swimEnabled = swimCfg === true || (typeof swimCfg === "object" && swimCfg !== null);
+    const swimSpeedMultiplier = typeof swimCfg === "object" && swimCfg !== null
+        ? swimCfg.speedMultiplier ?? DEFAULT_SWIM_SPEED_MULTIPLIER
+        : DEFAULT_SWIM_SPEED_MULTIPLIER;
+    const waterLevel = tuning.ground.waterLevel;
+    const submerged = swimEnabled &&
+        waterLevel !== undefined &&
+        tuning.ground.sampleHeight(player.position[0], player.position[2]) < waterLevel;
+    const motionOptions = submerged
+        ? { speedScale: swimSpeedMultiplier, floating: true }
+        : undefined;
+    const step = advancePlayerMotion(motion, intent, forwardX, forwardZ, walkSpeed, dt, tuning.physics, motionOptions);
+    let stepX = step.stepX;
+    let stepZ = step.stepZ;
+    if (tuning.movement?.mode === "axis") {
+        const constrained = constrainStepToAxis(stepX, stepZ, tuning.movement.axis ?? "x");
+        stepX = constrained.stepX;
+        stepZ = constrained.stepZ;
+    }
+    if (tuning.movement?.collideObjects === true) {
+        const obstacles = nearbyObstacles(ctx.scene.object.list(), player.position);
+        const resolved = resolveObstacleStep(player.position, stepX, stepZ, obstacles);
+        stepX = resolved.stepX;
+        stepZ = resolved.stepZ;
+    }
+    let nextX = player.position[0] + stepX;
+    let nextZ = player.position[2] + stepZ;
+    if (tuning.movement?.mode === "grid") {
+        const snapped = snapPositionToGrid(nextX, nextZ, tuning.movement.cellSize ?? 1);
+        nextX = snapped[0];
+        nextZ = snapped[1];
+    }
+    const slideCfg = tuning.movement?.slopeSlide;
+    if (slideCfg === true || (typeof slideCfg === "object" && slideCfg !== null)) {
+        const maxClimbNormalY = typeof slideCfg === "object" && slideCfg.maxClimbSlope !== undefined
+            ? slideCfg.maxClimbSlope
+            : DEFAULT_MAX_CLIMB_NORMAL_Y;
+        if (tuning.ground.sampleNormal(nextX, nextZ)[1] < maxClimbNormalY) {
+            const slope = sampleSlope(tuning.ground, nextX, nextZ);
+            const slide = SLOPE_SLIDE_SPEED * slope.steepness * dt;
+            nextX += slope.downhill[0] * slide;
+            nextZ += slope.downhill[1] * slide;
+        }
+    }
+    const groundAtNext = tuning.ground.sampleHeight(nextX, nextZ);
+    let nextY = groundAtNext + motion.jumpOffset;
+    if (motionBatch !== null && motionBatch.y !== null) {
+        nextY = motionBatch.y;
+        motion.jumpOffset = motionBatch.y - groundAtNext;
+    }
+    else if (swimEnabled && waterLevel !== undefined && groundAtNext < waterLevel) {
+        nextY = waterLevel;
+    }
+    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, intent.moving, motion.horizontalVelocityX, motion.horizontalVelocityZ, player.rotationY, tuning.movement?.turnSpeed, dt),
+        dt,
+    });
+}

package/dist/movement/poseState.d.ts

@@ -13,11 +13,24 @@ export interface PoseAllowedStates {
 export interface PoseRejection {
     reason: string;
 }
+export interface PoseSnapshot {
+    poses: Record<string, MovementPose>;
+    aims: Record<string, AimMode>;
+}
 export interface PoseState {
     getPose(instanceId: string): MovementPose;
     setPose(instanceId: string, pose: MovementPose): PoseRejection | null;
     getAim(instanceId: string): AimMode;
     setAim(instanceId: string, mode: AimMode): PoseRejection | null;
     clear(instanceId: string): void;
+    /** Snapshot every entity's pose and aim for a whole-world save. */
+    snapshotAll(): PoseSnapshot;
+    /** Restore every entity's pose and aim from a {@link snapshotAll} payload. */
+    hydrateAll(state: PoseSnapshot): void;
 }
+/**
+ * Stance/pose transitions — stand, crouch, prone — that change the hitbox and movement.
+ *
+ * @capability crouch-prone stance/pose transitions that change the hitbox
+ */
 export declare function createPoseState(resolveAllowed: (instanceId: string) => PoseAllowedStates | null | undefined): PoseState;

package/dist/movement/poseState.js

@@ -23,6 +23,11 @@ export const POSE_HITBOX = {
         speedMultiplier: MOVEMENT_TUNING.runSpeedMultiplier,
     },
 };
+/**
+ * Stance/pose transitions — stand, crouch, prone — that change the hitbox and movement.
+ *
+ * @capability crouch-prone stance/pose transitions that change the hitbox
+ */
 export function createPoseState(resolveAllowed) {
     const poses = new Map();
     const aims = new Map();
@@ -57,5 +62,16 @@ export function createPoseState(resolveAllowed) {
             poses.delete(instanceId);
             aims.delete(instanceId);
         },
+        snapshotAll() {
+            return { poses: Object.fromEntries(poses), aims: Object.fromEntries(aims) };
+        },
+        hydrateAll(state) {
+            poses.clear();
+            for (const [id, pose] of Object.entries(state.poses))
+                poses.set(id, pose);
+            aims.clear();
+            for (const [id, aim] of Object.entries(state.aims))
+                aims.set(id, aim);
+        },
     };
 }

package/dist/movement/steering.d.ts

@@ -25,3 +25,11 @@ export declare function steerYaw(yaw: number, steerRight: number, turnRatePerSec
  * it into [-1, 1] at the call site.
  */
 export declare function steerToward(yaw: number, desiredYaw: number): number;
+/**
+ * @internal Rotate `yaw` toward `targetYaw` by at most `turnRatePerSecond * dt`
+ * radians, always along the shortest arc, snapping exactly onto the target once
+ * within a single step so it converges without overshoot or jitter — the
+ * smoothing behind a rendered body-turn (`PlayerMovementConfig.turnSpeed`). A
+ * large enough rate (or `dt`) reaches the target in one call, matching a snap.
+ */
+export declare function approachYaw(yaw: number, targetYaw: number, turnRatePerSecond: number, dt: number): number;

package/dist/movement/steering.js

@@ -37,4 +37,22 @@ export function steerToward(yaw, desiredYaw) {
         delta += TWO_PI;
     return -delta;
 }
+/**
+ * @internal Rotate `yaw` toward `targetYaw` by at most `turnRatePerSecond * dt`
+ * radians, always along the shortest arc, snapping exactly onto the target once
+ * within a single step so it converges without overshoot or jitter — the
+ * smoothing behind a rendered body-turn (`PlayerMovementConfig.turnSpeed`). A
+ * large enough rate (or `dt`) reaches the target in one call, matching a snap.
+ */
+export function approachYaw(yaw, targetYaw, turnRatePerSecond, dt) {
+    let delta = (targetYaw - yaw) % TWO_PI;
+    if (delta > Math.PI)
+        delta -= TWO_PI;
+    if (delta <= -Math.PI)
+        delta += TWO_PI;
+    const maxStep = turnRatePerSecond * dt;
+    if (maxStep <= 0 || Math.abs(delta) <= maxStep)
+        return targetYaw;
+    return yaw + Math.sign(delta) * maxStep;
+}
 const TWO_PI = Math.PI * 2;

package/dist/multiplayer/combatSnapshot.d.ts

@@ -16,7 +16,9 @@ export interface SerializeBoardArgs {
     seed?: number;
     capturedAt?: number;
 }
+/** @internal */
 export declare function serializeBoard(args: SerializeBoardArgs): BoardSnapshot;
+/** @internal */
 export declare function cloneSnapshot(snapshot: BoardSnapshot): BoardSnapshot;
 export interface CombatRules {
     attackStat: string;
@@ -42,4 +44,5 @@ export interface ReplayResult {
     survivorsA: readonly string[];
     survivorsB: readonly string[];
 }
+/** @internal */
 export declare function replayCombat(a: BoardSnapshot, b: BoardSnapshot, rules: CombatRules): ReplayResult;

package/dist/multiplayer/combatSnapshot.js

@@ -1,6 +1,7 @@
 function cloneStats(stats) {
     return { ...stats };
 }
+/** @internal */
 export function serializeBoard(args) {
     return {
         ownerId: args.ownerId,
@@ -10,6 +11,7 @@ export function serializeBoard(args) {
         capturedAt: args.capturedAt ?? 0,
     };
 }
+/** @internal */
 export function cloneSnapshot(snapshot) {
     return serializeBoard({
         ownerId: snapshot.ownerId,
@@ -36,6 +38,7 @@ function toLive(snapshot, rules) {
         health: unit.stats[rules.healthStat] ?? 0,
     }));
 }
+/** @internal */
 export function replayCombat(a, b, rules) {
     const maxRounds = rules.maxRounds ?? 100;
     const critChance = rules.critChance ?? 0;

package/dist/multiplayer/lagCompensation.d.ts

@@ -10,6 +10,7 @@ export interface PositionHistoryConfig {
     historyMs: number;
     maxSamples?: number;
 }
+/** @internal */
 export declare class PositionHistory {
     private readonly historyMs;
     private readonly maxSamples;
@@ -23,7 +24,9 @@ export declare class PositionHistory {
     prune(now: number): void;
     forget(entityId: string): void;
 }
+/** @internal */
 export declare function createPositionHistory(config: PositionHistoryConfig): PositionHistory;
+/** @internal */
 export declare function rewindTimestamp(nowMs: number, rttMs: number, interpDelayMs: number): number;
 export interface HitscanRay {
     origin: Vec3;
@@ -39,5 +42,7 @@ export interface HitscanHit {
     distance: number;
     point: Vec3;
 }
+/** @internal */
 export declare function raySphereDistance(ray: HitscanRay, center: Vec3, radius: number): number | null;
+/** @internal */
 export declare function resolveHitscan(history: PositionHistory, targets: readonly HitscanTarget[], ray: HitscanRay, atMs: number): HitscanHit | null;

package/dist/multiplayer/lagCompensation.js

@@ -1,4 +1,5 @@
 const DEFAULT_MAX_SAMPLES = 256;
+/** @internal */
 export class PositionHistory {
     historyMs;
     maxSamples;
@@ -90,9 +91,11 @@ export class PositionHistory {
         this.tracks.delete(entityId);
     }
 }
+/** @internal */
 export function createPositionHistory(config) {
     return new PositionHistory(config);
 }
+/** @internal */
 export function rewindTimestamp(nowMs, rttMs, interpDelayMs) {
     return nowMs - rttMs / 2 - interpDelayMs;
 }
@@ -102,6 +105,7 @@ function normalize(v) {
         return null;
     return { x: v.x / len, y: v.y / len, z: v.z / len };
 }
+/** @internal */
 export function raySphereDistance(ray, center, radius) {
     const dir = normalize(ray.direction);
     if (dir === null)
@@ -126,6 +130,7 @@ export function raySphereDistance(ray, center, radius) {
         return null;
     return t;
 }
+/** @internal */
 export function resolveHitscan(history, targets, ray, atMs) {
     const dir = normalize(ray.direction);
     if (dir === null)

package/dist/multiplayer/presenceModel.d.ts

@@ -51,25 +51,33 @@ export declare const DEFAULT_SPAWN_ORIGIN: {
     readonly y: 0;
     readonly z: 0;
 };
+/** @internal */
 export declare function spawnPresenceState(origin: {
     x: number;
     y: number;
     z: number;
 } | undefined, nowMs: number, rules: Pick<PoseSyncRules, "maxElapsedSec">): PresencePoseState;
+/** @internal */
 export declare function decidePoseSync(current: PresencePoseState, incoming: IncomingPose, rules: PoseSyncRules, nowMs: number, floorY?: number): PoseSyncDecision;
+/** @internal */
 export declare function shouldRefreshKeepAlive(lastSeenAtMs: number | undefined, nowMs: number, rules: Pick<PoseSyncRules, "keepAliveRefreshMs">): boolean;
+/** @internal */
 export declare function shouldPersistWorldSnapshot(lastSavedAtMs: number | undefined, nowMs: number, intervalMs: number): boolean;
 export interface ActivePresenceResolution<T> {
     active: T | null;
     /** Other unrevoked rows for the same actor — a session may only have one. */
     extras: T[];
 }
+/** @internal */
 export declare function resolveActivePresence<T extends {
     revokedAt?: number;
     lastSeenAt?: number;
 }>(rows: readonly T[]): ActivePresenceResolution<T>;
+/** @internal */
 export declare function isPresenceExpired(lastSeenAtMs: number, nowMs: number, idleCutoffMs: number): boolean;
-/** Most-recently-seen row across an actor's rows, to reuse instead of inserting a new one. */
+/** Most-recently-seen row across an actor's rows, to reuse instead of inserting a new one.
+ * @internal
+ */
 export declare function pickReusablePresence<T extends {
     lastSeenAt?: number;
 }>(rows: readonly T[]): T | undefined;

package/dist/multiplayer/presenceModel.js

@@ -10,6 +10,7 @@ function appearanceEqual(a, b) {
     return aKeys.every((key) => a[key] === b[key]);
 }
 export const DEFAULT_SPAWN_ORIGIN = { x: 0, y: 0, z: 0 };
+/** @internal */
 export function spawnPresenceState(origin = DEFAULT_SPAWN_ORIGIN, nowMs, rules) {
     return {
         position: { x: origin.x, y: origin.y, z: origin.z },
@@ -18,6 +19,7 @@ export function spawnPresenceState(origin = DEFAULT_SPAWN_ORIGIN, nowMs, rules)
         lastSeenAtMs: nowMs - rules.maxElapsedSec * 1000,
     };
 }
+/** @internal */
 export function decidePoseSync(current, incoming, rules, nowMs, floorY) {
     const rawElapsedSec = Math.max(0, (nowMs - (current.lastSeenAtMs ?? nowMs)) / 1000);
     const elapsedSec = Math.min(rules.maxElapsedSec, rawElapsedSec);
@@ -55,12 +57,15 @@ export function decidePoseSync(current, incoming, rules, nowMs, floorY) {
         refreshKeepAlive: !changed && shouldRefreshKeepAlive(current.lastSeenAtMs, nowMs, rules),
     };
 }
+/** @internal */
 export function shouldRefreshKeepAlive(lastSeenAtMs, nowMs, rules) {
     return nowMs - (lastSeenAtMs ?? 0) >= rules.keepAliveRefreshMs;
 }
+/** @internal */
 export function shouldPersistWorldSnapshot(lastSavedAtMs, nowMs, intervalMs) {
     return lastSavedAtMs === undefined || nowMs - lastSavedAtMs >= intervalMs;
 }
+/** @internal */
 export function resolveActivePresence(rows) {
     const actives = rows.filter((row) => row.revokedAt === undefined);
     if (actives.length === 0)
@@ -68,10 +73,13 @@ export function resolveActivePresence(rows) {
     const sorted = [...actives].sort((a, b) => (b.lastSeenAt ?? 0) - (a.lastSeenAt ?? 0));
     return { active: sorted[0] ?? null, extras: sorted.slice(1) };
 }
+/** @internal */
 export function isPresenceExpired(lastSeenAtMs, nowMs, idleCutoffMs) {
     return nowMs - lastSeenAtMs >= idleCutoffMs;
 }
-/** Most-recently-seen row across an actor's rows, to reuse instead of inserting a new one. */
+/** Most-recently-seen row across an actor's rows, to reuse instead of inserting a new one.
+ * @internal
+ */
 export function pickReusablePresence(rows) {
     return [...rows].sort((a, b) => (b.lastSeenAt ?? 0) - (a.lastSeenAt ?? 0))[0];
 }

package/dist/multiplayer/simultaneousCommit.d.ts

@@ -15,6 +15,7 @@ export type SealResult = {
     ok: false;
     reason: "unknown_participant" | "already_sealed" | "already_revealed";
 };
+/** @internal */
 export declare class CommitRound<TAction> {
     private readonly order;
     private readonly participants;
@@ -30,5 +31,7 @@ export declare class CommitRound<TAction> {
     get phase(): CommitPhase;
     reveal(): readonly SealedCommit<TAction>[] | null;
 }
+/** @internal */
 export declare function createCommitRound<TAction>(config: CommitRoundConfig): CommitRound<TAction>;
+/** @internal */
 export declare function resolveCommits<TAction, TResult>(reveals: readonly SealedCommit<TAction>[], resolver: (ordered: readonly SealedCommit<TAction>[]) => TResult): TResult;

package/dist/multiplayer/simultaneousCommit.js

@@ -1,3 +1,4 @@
+/** @internal */
 export class CommitRound {
     order;
     participants;
@@ -45,9 +46,11 @@ export class CommitRound {
         return this.order.map((id) => this.sealed.get(id));
     }
 }
+/** @internal */
 export function createCommitRound(config) {
     return new CommitRound(config);
 }
+/** @internal */
 export function resolveCommits(reveals, resolver) {
     return resolver(reveals);
 }

package/dist/multiplayer.d.ts

@@ -0,0 +1,11 @@
+export { type ChatActions, type ChatSendOutcome, type ChatSync, type ChatTransport, } from "./multiplayer/chatContract.js";
+export { type BoardSnapshot } from "./multiplayer/combatSnapshot.js";
+export { createFeedWriteGate, validateFeedWrite, type FeedWriteGate } from "./multiplayer/feedWriteGate.js";
+export { resolveGuestSession, sessionPlayer, type AuthSession, type PlayerIdentity } from "./multiplayer/identity.js";
+export { type Vec3 } from "./multiplayer/lagCompensation.js";
+export { browseSessions, findByJoinCode, normalizeJoinCode, quickMatch, type MatchFilter, type SessionListing, type SessionVisibility, } from "./multiplayer/matchmaking.js";
+export { createPoseSyncGate, type PlayerPose, type PoseSyncTuning } from "./multiplayer/poseSyncGate.js";
+export { type EnsurePresenceResult, type PresenceActions, type PresenceFeeds, type PresenceSession, type PresenceTransport, } from "./multiplayer/presenceContract.js";
+export { type PoseSyncRules, type PresencePoseState } from "./multiplayer/presenceModel.js";
+export { createLocalVoiceTransport, createPushToTalk, type PushToTalkMode, type PushToTalkStatus, type VoiceParticipant, type VoiceRoute, type VoiceTransport, } from "./multiplayer/voiceContract.js";
+export { type ReplicationPolicy } from "./runtime/worldProjection.js";

package/dist/multiplayer.js

@@ -0,0 +1,11 @@
+export {} from "./multiplayer/chatContract.js";
+export {} from "./multiplayer/combatSnapshot.js";
+export { createFeedWriteGate, validateFeedWrite } from "./multiplayer/feedWriteGate.js";
+export { resolveGuestSession, sessionPlayer } from "./multiplayer/identity.js";
+export {} from "./multiplayer/lagCompensation.js";
+export { browseSessions, findByJoinCode, normalizeJoinCode, quickMatch, } from "./multiplayer/matchmaking.js";
+export { createPoseSyncGate } from "./multiplayer/poseSyncGate.js";
+export {} from "./multiplayer/presenceContract.js";
+export {} from "./multiplayer/presenceModel.js";
+export { createLocalVoiceTransport, createPushToTalk, } from "./multiplayer/voiceContract.js";
+export {} from "./runtime/worldProjection.js";

package/dist/nav/pathFollow.d.ts

@@ -21,6 +21,63 @@ export interface HeightSampler {
     sampleHeight(x: number, z: number): number;
 }
 export declare function pathFromNav(points: readonly NavPoint[], elevation?: number | HeightSampler, offset?: number): Waypoint[];
+/**
+ * Semantic seek target for {@link pathFollowSeek} — the caller-facing progress vocabulary a
+ * stateful path behavior restores from, so a follower can start at a distributed phase or resume
+ * a serialized route without knowing waypoint internals. `direction` (forward heading) falls out of
+ * the resulting {@link PathFollowState.heading}, so it is an output rather than a seek input.
+ */
+export type PathProgress = 
+/** Fraction `0..1` of total path length (looping paths wrap; clamped otherwise). */
+{
+    readonly kind: "normalized";
+    readonly value: number;
+}
+/** World-distance travelled from the first waypoint (looping paths wrap; clamped otherwise). */
+ | {
+    readonly kind: "distance";
+    readonly value: number;
+}
+/** Segment `index` (0-based) plus `fraction` `0..1` along that segment. */
+ | {
+    readonly kind: "segment";
+    readonly index: number;
+    readonly fraction: number;
+};
+/** Read-only progress readout for inspection/debug tooling, produced by {@link pathFollowProgress}. */
+export interface PathFollowProgress {
+    /** Cumulative world-distance travelled (matches {@link PathFollowState.distanceTravelled}). */
+    distance: number;
+    /** Fraction `0..1` of total path length at the current position. */
+    normalized: number;
+    /** 0-based index of the segment the mover is currently on. */
+    segment: number;
+    /** Fraction `0..1` along the current segment. */
+    fraction: number;
+}
+/**
+ * Total world-distance of a path — sum of every segment, including the wrap segment back to the
+ * first waypoint when `loop` is set. Zero for a degenerate (0- or 1-waypoint) path.
+ *
+ * @capability path-length total polyline distance for progress math and seeding
+ */
+export declare function pathLength(config: PathFollowConfig): number;
+/**
+ * Place a follower at a semantic {@link PathProgress} without simulating from the start — the seek
+ * adapter behavior lifecycles use to seed distributed phases and restore serialized routes. Pure;
+ * returns a fresh {@link PathFollowState} whose `heading` gives travel direction. Looping paths wrap
+ * the distance; non-looping paths clamp to `[0, pathLength]` and report `done` at the end.
+ *
+ * @capability path-follow-seek jump a path-follower to normalized/distance/segment progress
+ */
+export declare function pathFollowSeek(config: PathFollowConfig, target: PathProgress): PathFollowState;
+/**
+ * Read a follower's current progress in every semantic form — the inverse of {@link pathFollowSeek},
+ * for editor/debug inspection and progress HUDs. Pure and allocation-light.
+ *
+ * @capability path-follow-progress read normalized/distance/segment progress from follow state
+ */
+export declare function pathFollowProgress(config: PathFollowConfig, state: PathFollowState): PathFollowProgress;
 export declare function createPathFollow(config: PathFollowConfig): PathFollowState;
 /**
  * Advance a path-follower by `speed * dt` along its authored polyline. Pure — returns