@jgengine/core 0.7.0 → 0.8.0

package/dist/movement/voxelController.js

@@ -0,0 +1,229 @@
+/**
+ * Voxel character controller (pure model).
+ *
+ * The base first-person controller in `movementModel.ts` assumes flat ground at
+ * y=0 — it integrates gravity into a `jumpOffset` and never asks the world how
+ * tall the ground is. That is fine for a plaza demo but wrong for any game where
+ * the player walks on placed blocks and digs down into the world: they float on
+ * an invisible floor, clip through walls, and can never descend.
+ *
+ * This module resolves the player as an axis-aligned box against a set of solid
+ * unit cells (a `SolidQuery`), so the same held-keys → intent pipeline drives a
+ * body that stands on blocks, falls into holes, is stopped by walls, and steps
+ * up single-block ledges. Keeping it renderer-free means the shell can drive it
+ * from live scene objects while the descent/landing/step-up behaviour stays unit
+ * testable without three.js.
+ *
+ * Cell convention matches the shell's object rendering and the voxel raycast:
+ * cell (x,y,z) is the solid box X∈[x-0.5,x+0.5], Y∈[y,y+1], Z∈[z-0.5,z+0.5]. A
+ * block at cell y therefore has its top face at world y+1, so a player standing
+ * on the surface layer (cell y=-1) rests with their feet at y=0.
+ */
+import { MOVEMENT_TUNING } from "./movementModel.js";
+export const DEFAULT_VOXEL_DIMS = {
+    halfWidth: 0.3,
+    height: 1.8,
+    stepHeight: 0.6,
+};
+export function createVoxelPlayerBody(x, y, z) {
+    return { x, y, z, velocityX: 0, velocityY: 0, velocityZ: 0, grounded: true, jumpHeld: false };
+}
+const SUPPORT_EPSILON = 0.02;
+const PENETRATION_EPSILON = 1e-4;
+function cellX(worldX) {
+    return Math.floor(worldX + 0.5);
+}
+function cellZ(worldZ) {
+    return Math.floor(worldZ + 0.5);
+}
+/** True if the player box centred at (x, y, z) overlaps any solid cell. */
+function overlapsSolid(x, y, z, isSolid, dims) {
+    const minCellX = cellX(x - dims.halfWidth);
+    const maxCellX = cellX(x + dims.halfWidth);
+    const minCellZ = cellZ(z - dims.halfWidth);
+    const maxCellZ = cellZ(z + dims.halfWidth);
+    const minCellY = Math.floor(y + PENETRATION_EPSILON);
+    const maxCellY = Math.floor(y + dims.height - PENETRATION_EPSILON);
+    for (let cx = minCellX; cx <= maxCellX; cx += 1) {
+        for (let cz = minCellZ; cz <= maxCellZ; cz += 1) {
+            for (let cy = minCellY; cy <= maxCellY; cy += 1) {
+                if (isSolid(cx, cy, cz))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** True if a solid cell sits directly beneath the feet, or terrain supports them (i.e. the player is supported). */
+function hasSupport(x, z, y, isSolid, dims, groundHeight) {
+    const cy = Math.floor(y - SUPPORT_EPSILON);
+    const minCellX = cellX(x - dims.halfWidth);
+    const maxCellX = cellX(x + dims.halfWidth);
+    const minCellZ = cellZ(z - dims.halfWidth);
+    const maxCellZ = cellZ(z + dims.halfWidth);
+    for (let cx = minCellX; cx <= maxCellX; cx += 1) {
+        for (let cz = minCellZ; cz <= maxCellZ; cz += 1) {
+            if (isSolid(cx, cy, cz))
+                return true;
+        }
+    }
+    if (groundHeight !== undefined && y <= groundHeight(x, z) + SUPPORT_EPSILON)
+        return true;
+    return false;
+}
+/**
+ * Highest solid-cell top under the footprint at (x, z) within the vertical
+ * window [fromY, toY]. Returns null when nothing supports the feet there — used
+ * both to snap a fall onto a block and to raise a step-up.
+ */
+function supportTopWithin(x, z, fromY, toY, isSolid, dims) {
+    const minCellX = cellX(x - dims.halfWidth);
+    const maxCellX = cellX(x + dims.halfWidth);
+    const minCellZ = cellZ(z - dims.halfWidth);
+    const maxCellZ = cellZ(z + dims.halfWidth);
+    const lowCellY = Math.floor(fromY - PENETRATION_EPSILON);
+    const highCellY = Math.floor(toY - PENETRATION_EPSILON);
+    let best = null;
+    for (let cx = minCellX; cx <= maxCellX; cx += 1) {
+        for (let cz = minCellZ; cz <= maxCellZ; cz += 1) {
+            for (let cy = lowCellY; cy <= highCellY; cy += 1) {
+                if (!isSolid(cx, cy, cz))
+                    continue;
+                const top = cy + 1;
+                if (best === null || top > best)
+                    best = top;
+            }
+        }
+    }
+    return best;
+}
+function targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed) {
+    if (!intent.moving)
+        return { x: 0, z: 0 };
+    let fx = forwardX;
+    let fz = forwardZ;
+    const lengthSq = fx * fx + fz * fz;
+    if (lengthSq < 1e-6) {
+        fx = 0;
+        fz = -1;
+    }
+    else {
+        const inv = 1 / Math.sqrt(lengthSq);
+        fx *= inv;
+        fz *= inv;
+    }
+    const rightX = -fz;
+    const rightZ = fx;
+    let vx = fx * intent.forward + rightX * intent.right;
+    let vz = fz * intent.forward + rightZ * intent.right;
+    const magSq = vx * vx + vz * vz;
+    if (magSq < 1e-6)
+        return { x: 0, z: 0 };
+    const speedMultiplier = intent.crouching
+        ? MOVEMENT_TUNING.crouchSpeedMultiplier
+        : intent.running
+            ? MOVEMENT_TUNING.runSpeedMultiplier
+            : 1;
+    const targetSpeed = baseSpeed * MOVEMENT_TUNING.walkSpeedMultiplier * speedMultiplier;
+    const scale = targetSpeed / Math.sqrt(magSq);
+    vx *= scale;
+    vz *= scale;
+    return { x: vx, z: vz };
+}
+/**
+ * Move the body along one horizontal axis, resolving collisions. Returns the
+ * component of the step that survived (0 when a wall stopped the move). When the
+ * move is blocked but the obstacle is a short ledge, the body steps up onto it.
+ */
+function moveAxis(body, axis, delta, isSolid, dims) {
+    if (delta === 0)
+        return 0;
+    const nextX = axis === "x" ? body.x + delta : body.x;
+    const nextZ = axis === "z" ? body.z + delta : body.z;
+    if (!overlapsSolid(nextX, body.y, nextZ, isSolid, dims)) {
+        body.x = nextX;
+        body.z = nextZ;
+        return delta;
+    }
+    if (body.grounded) {
+        const raised = supportTopWithin(nextX, nextZ, body.y, body.y + dims.stepHeight, isSolid, dims);
+        if (raised !== null &&
+            raised - body.y <= dims.stepHeight + PENETRATION_EPSILON &&
+            raised >= body.y &&
+            !overlapsSolid(nextX, raised, nextZ, isSolid, dims)) {
+            body.x = nextX;
+            body.z = nextZ;
+            body.y = raised;
+            return delta;
+        }
+    }
+    return 0;
+}
+/**
+ * Advance one frame of voxel-collided player kinematics. Mutates `body`
+ * (position, velocity, grounded) in place.
+ *
+ * `forwardX`/`forwardZ` are the camera heading projected onto the ground plane
+ * (need not be normalized). Pulling this out of the render loop is what lets us
+ * assert "dig the block underfoot and the player drops a level" in a unit test.
+ *
+ * `groundHeight`, when supplied, is an additional solid floor sampled at the
+ * body's (x, z): the player never sinks below it and standing on it counts as
+ * supported (resets jump state like landing on a solid cell). Where terrain and
+ * a solid cell's top disagree, the higher of the two wins.
+ */
+export function advanceVoxelPlayer(body, intent, forwardX, forwardZ, baseSpeed, rawDeltaSeconds, isSolid, dims = DEFAULT_VOXEL_DIMS, tuning, groundHeight) {
+    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 acceleration = body.grounded
+        ? MOVEMENT_TUNING.groundAcceleration
+        : 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);
+        body.velocityX *= friction;
+        body.velocityZ *= friction;
+    }
+    if (moveAxis(body, "x", body.velocityX * dt, isSolid, dims) === 0)
+        body.velocityX = 0;
+    if (moveAxis(body, "z", body.velocityZ * dt, isSolid, dims) === 0)
+        body.velocityZ = 0;
+    const supported = body.grounded && hasSupport(body.x, body.z, body.y, isSolid, dims, groundHeight);
+    body.grounded = supported;
+    const jumpPressed = intent.jumping;
+    if (jumpPressed && !body.jumpHeld && body.grounded && !intent.crouching) {
+        body.velocityY = jumpVelocity;
+        body.grounded = false;
+    }
+    body.jumpHeld = jumpPressed;
+    if (!body.grounded) {
+        body.velocityY -= gravityAcceleration * dt;
+        const nextY = body.y + body.velocityY * dt;
+        if (body.velocityY <= 0) {
+            const terrainFloor = groundHeight?.(body.x, body.z);
+            const solidBlocked = overlapsSolid(body.x, nextY, body.z, isSolid, dims);
+            const terrainBlocked = terrainFloor !== undefined && nextY <= terrainFloor;
+            if (solidBlocked || terrainBlocked) {
+                const solidTop = solidBlocked
+                    ? (supportTopWithin(body.x, body.z, nextY, body.y + dims.height, isSolid, dims) ?? Math.floor(body.y))
+                    : undefined;
+                body.y = Math.max(solidTop ?? -Infinity, terrainFloor ?? -Infinity);
+                body.velocityY = 0;
+                body.grounded = true;
+            }
+            else {
+                body.y = nextY;
+            }
+        }
+        else if (overlapsSolid(body.x, nextY, body.z, isSolid, dims)) {
+            body.velocityY = 0;
+        }
+        else {
+            body.y = nextY;
+        }
+    }
+}

package/dist/multiplayer/chatContract.d.ts

@@ -0,0 +1,42 @@
+import type { ChatMessage } from "../game/chat.js";
+export interface ChatSendArgs {
+    channelId: string;
+    body: string;
+}
+export interface ChatSendOutcome {
+    ok: boolean;
+    reason?: string;
+}
+export interface ChatActions {
+    sendMessage(args: ChatSendArgs): Promise<ChatSendOutcome>;
+}
+/**
+ * Backend seam for remote text chat, mirroring PresenceTransport: the use*
+ * members are called as React hooks by consumers, so a mounted transport must
+ * never change identity — remount the subtree to switch backends. useMessages
+ * returns undefined while the subscription is loading and the channel's recent
+ * history once live.
+ */
+export interface ChatTransport {
+    useMessages(channelId: string | "skip"): readonly ChatMessage[] | undefined;
+    useActions(): ChatActions;
+}
+/**
+ * Callback seam for backends that cannot host React hooks (e.g. the ws
+ * client): subscribe delivers the channel's recent history on every change;
+ * send resolves with the host's verdict. @jgengine/react's chatTransportFromSync
+ * lifts a ChatSync into a ChatTransport.
+ */
+export interface ChatSync {
+    subscribe(channelId: string, onChange: (messages: readonly ChatMessage[]) => void): () => void;
+    send(channelId: string, body: string): Promise<ChatSendOutcome>;
+}
+export declare function createLocalChatTransport(options?: {
+    userId?: string;
+    historyLimit?: number;
+    now?: () => number;
+}): {
+    transport: ChatTransport;
+    sync: ChatSync;
+    actions: ChatActions;
+};

package/dist/multiplayer/chatContract.js

@@ -0,0 +1,57 @@
+export function createLocalChatTransport(options) {
+    const userId = options?.userId ?? "local";
+    const historyLimit = options?.historyLimit ?? 100;
+    const now = options?.now ?? Date.now;
+    const messagesByChannel = new Map();
+    const listeners = new Map();
+    let counter = 0;
+    function snapshot(channelId) {
+        return (messagesByChannel.get(channelId) ?? []).slice();
+    }
+    const sync = {
+        subscribe(channelId, onChange) {
+            let set = listeners.get(channelId);
+            if (set === undefined) {
+                set = new Set();
+                listeners.set(channelId, set);
+            }
+            set.add(onChange);
+            onChange(snapshot(channelId));
+            return () => {
+                set.delete(onChange);
+                if (set.size === 0)
+                    listeners.delete(channelId);
+            };
+        },
+        send(channelId, body) {
+            const trimmed = body.trim();
+            if (trimmed.length === 0)
+                return Promise.resolve({ ok: false, reason: "empty message" });
+            counter += 1;
+            const message = {
+                id: `local_${counter}`,
+                channelId,
+                fromUserId: userId,
+                body: trimmed,
+                at: now(),
+            };
+            const ring = messagesByChannel.get(channelId) ?? [];
+            ring.push(message);
+            if (ring.length > historyLimit)
+                ring.splice(0, ring.length - historyLimit);
+            messagesByChannel.set(channelId, ring);
+            const current = snapshot(channelId);
+            for (const listener of listeners.get(channelId) ?? [])
+                listener(current);
+            return Promise.resolve({ ok: true });
+        },
+    };
+    const actions = {
+        sendMessage: (args) => sync.send(args.channelId, args.body),
+    };
+    const transport = {
+        useMessages: (channelId) => (channelId === "skip" ? undefined : snapshot(channelId)),
+        useActions: () => actions,
+    };
+    return { transport, sync, actions };
+}

package/dist/multiplayer/identity.d.ts

@@ -0,0 +1,13 @@
+export interface AuthSession {
+    userId: string;
+    displayName?: string;
+    avatarUrl?: string;
+    email?: string;
+    isNew?: boolean;
+}
+export interface PlayerIdentity {
+    userId: string;
+    isNew: boolean;
+}
+export declare function sessionPlayer(session: AuthSession): PlayerIdentity;
+export declare function resolveGuestSession(seed?: string): AuthSession;

package/dist/multiplayer/identity.js

@@ -0,0 +1,20 @@
+export function sessionPlayer(session) {
+    return { userId: session.userId, isNew: session.isNew ?? false };
+}
+const DEFAULT_GUEST_SEED = "local";
+export function resolveGuestSession(seed) {
+    const normalized = seed === undefined || seed.trim().length === 0 ? DEFAULT_GUEST_SEED : seed.trim();
+    const hash = fnv1a(normalized);
+    return {
+        userId: `guest_${hash}`,
+        displayName: `Guest ${hash.slice(0, 4).toUpperCase()}`,
+    };
+}
+function fnv1a(input) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index += 1) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(36);
+}

package/dist/multiplayer/poseSyncGate.d.ts

@@ -4,6 +4,7 @@ export interface PlayerPose {
     z: number;
     rotationY: number;
     rotationPitch: number;
+    appearance?: Record<string, string>;
 }
 export interface PoseSyncTuning {
     minIntervalMs: number;

package/dist/multiplayer/poseSyncGate.js

@@ -1,9 +1,21 @@
+function appearanceChanged(a, b) {
+    if (a === b)
+        return false;
+    if (a === undefined || b === undefined)
+        return true;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return true;
+    return aKeys.some((key) => a[key] !== b[key]);
+}
 function poseChanged(a, b, tuning) {
     return (Math.abs(a.x - b.x) > tuning.positionEpsilon
         || Math.abs(a.y - b.y) > tuning.verticalEpsilon
         || Math.abs(a.z - b.z) > tuning.positionEpsilon
         || Math.abs(a.rotationY - b.rotationY) > tuning.rotationEpsilon
-        || Math.abs(a.rotationPitch - b.rotationPitch) > tuning.rotationEpsilon);
+        || Math.abs(a.rotationPitch - b.rotationPitch) > tuning.rotationEpsilon
+        || appearanceChanged(a.appearance, b.appearance));
 }
 export function createPoseSyncGate(tuning) {
     let lastSentPose = null;

package/dist/multiplayer/presenceModel.d.ts

@@ -7,6 +7,7 @@ export interface PresencePoseState {
     rotationY: number;
     rotationPitch?: number;
     lastSeenAtMs?: number;
+    appearance?: Record<string, string>;
 }
 export interface IncomingPose {
     position: {
@@ -16,6 +17,7 @@ export interface IncomingPose {
     };
     rotationY?: number;
     rotationPitch?: number;
+    appearance?: Record<string, string>;
 }
 export interface PoseSyncRules {
     /** Speed cap (units/sec) for client-authoritative movement. */
@@ -36,6 +38,7 @@ export interface PoseSyncDecision {
     };
     rotationY: number;
     rotationPitch: number;
+    appearance?: Record<string, string>;
     /** True when the pose differs and a pose write is needed. */
     changed: boolean;
     /** True when only the keep-alive stamp should be written. */

package/dist/multiplayer/presenceModel.js

@@ -1,3 +1,14 @@
+function appearanceEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((key) => a[key] === b[key]);
+}
 export function decidePoseSync(current, incoming, rules, nowMs) {
     const elapsedSec = Math.max(rules.minElapsedSec, Math.min(rules.maxElapsedSec, (nowMs - (current.lastSeenAtMs ?? nowMs)) / 1000));
     const maxDist = rules.maxSpeed * elapsedSec;
@@ -17,14 +28,17 @@ export function decidePoseSync(current, incoming, rules, nowMs) {
         : Math.max(0, Math.min(rules.maxVerticalOffset, incoming.position.y));
     const nextRotationY = incoming.rotationY ?? current.rotationY;
     const nextRotationPitch = incoming.rotationPitch ?? current.rotationPitch ?? 0;
+    const nextAppearance = incoming.appearance ?? current.appearance;
+    const appearanceChanged = incoming.appearance !== undefined && !appearanceEqual(incoming.appearance, current.appearance);
     const moved = targetX !== current.position.x || targetZ !== current.position.z;
     const jumped = nextY !== current.position.y;
     const rotated = nextRotationY !== current.rotationY || nextRotationPitch !== (current.rotationPitch ?? 0);
-    const changed = moved || jumped || rotated;
+    const changed = moved || jumped || rotated || appearanceChanged;
     return {
         position: { x: targetX, y: nextY, z: targetZ },
         rotationY: nextRotationY,
         rotationPitch: nextRotationPitch,
+        appearance: nextAppearance,
         changed,
         refreshKeepAlive: !changed && shouldRefreshKeepAlive(current.lastSeenAtMs, nowMs, rules),
     };

package/dist/multiplayer/voiceContract.d.ts

@@ -0,0 +1,44 @@
+export interface VoiceParticipant {
+    userId: string;
+    streamId?: string;
+}
+export interface VoiceRoute {
+    fromUserId: string;
+    channelId: string;
+    gain: number;
+}
+/**
+ * Signaling seam for voice: who is in a channel and which media stream
+ * descriptor they published. The media plane (WebRTC, SFU, or anything else
+ * that moves audio bytes) stays behind this seam, host-supplied — the engine
+ * never touches it. subscribers delivers the channel roster on every change,
+ * starting with the current roster.
+ */
+export interface VoiceTransport {
+    join(channelId: string, streamId?: string): Promise<void>;
+    leave(channelId: string): Promise<void>;
+    publish(channelId: string, streamId: string): Promise<void>;
+    subscribers(channelId: string, onChange: (participants: readonly VoiceParticipant[]) => void): () => void;
+}
+export declare function createLocalVoiceTransport(options?: {
+    userId?: string;
+}): {
+    transport: VoiceTransport;
+    participants(channelId: string): readonly VoiceParticipant[];
+};
+export type PushToTalkMode = "hold" | "toggle" | "openMic";
+export type PushToTalkStatus = "idle" | "keyed" | "open";
+export interface PushToTalk {
+    mode(): PushToTalkMode;
+    setMode(mode: PushToTalkMode): void;
+    keyDown(): void;
+    keyUp(): void;
+    muted(): boolean;
+    setMuted(muted: boolean): void;
+    status(): PushToTalkStatus;
+    transmitting(): boolean;
+}
+export declare function createPushToTalk(config?: {
+    mode?: PushToTalkMode;
+    onChange?: (transmitting: boolean) => void;
+}): PushToTalk;

package/dist/multiplayer/voiceContract.js

@@ -0,0 +1,108 @@
+export function createLocalVoiceTransport(options) {
+    const userId = options?.userId ?? "local";
+    const rosters = new Map();
+    const listeners = new Map();
+    function roster(channelId) {
+        let entries = rosters.get(channelId);
+        if (entries === undefined) {
+            entries = new Map();
+            rosters.set(channelId, entries);
+        }
+        return entries;
+    }
+    function snapshot(channelId) {
+        return [...roster(channelId).values()].map((participant) => ({ ...participant }));
+    }
+    function notify(channelId) {
+        const current = snapshot(channelId);
+        for (const listener of listeners.get(channelId) ?? [])
+            listener(current);
+    }
+    const transport = {
+        join(channelId, streamId) {
+            const participant = { userId };
+            if (streamId !== undefined)
+                participant.streamId = streamId;
+            roster(channelId).set(userId, participant);
+            notify(channelId);
+            return Promise.resolve();
+        },
+        leave(channelId) {
+            if (roster(channelId).delete(userId))
+                notify(channelId);
+            return Promise.resolve();
+        },
+        publish(channelId, streamId) {
+            const participant = roster(channelId).get(userId);
+            if (participant !== undefined) {
+                participant.streamId = streamId;
+                notify(channelId);
+            }
+            return Promise.resolve();
+        },
+        subscribers(channelId, onChange) {
+            let set = listeners.get(channelId);
+            if (set === undefined) {
+                set = new Set();
+                listeners.set(channelId, set);
+            }
+            set.add(onChange);
+            onChange(snapshot(channelId));
+            return () => {
+                set.delete(onChange);
+                if (set.size === 0)
+                    listeners.delete(channelId);
+            };
+        },
+    };
+    return { transport, participants: snapshot };
+}
+export function createPushToTalk(config) {
+    let mode = config?.mode ?? "hold";
+    let keyed = false;
+    let muted = false;
+    let lastTransmitting = false;
+    function transmitting() {
+        if (muted)
+            return false;
+        return mode === "openMic" ? true : keyed;
+    }
+    function emit() {
+        const current = transmitting();
+        if (current === lastTransmitting)
+            return;
+        lastTransmitting = current;
+        config?.onChange?.(current);
+    }
+    return {
+        mode: () => mode,
+        setMode(next) {
+            mode = next;
+            keyed = false;
+            emit();
+        },
+        keyDown() {
+            if (mode === "hold")
+                keyed = true;
+            else if (mode === "toggle")
+                keyed = !keyed;
+            emit();
+        },
+        keyUp() {
+            if (mode === "hold")
+                keyed = false;
+            emit();
+        },
+        muted: () => muted,
+        setMuted(next) {
+            muted = next;
+            emit();
+        },
+        status() {
+            if (mode === "openMic")
+                return "open";
+            return keyed ? "keyed" : "idle";
+        },
+        transmitting,
+    };
+}

package/dist/nav/navConstrain.d.ts

@@ -0,0 +1,14 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+import type { NavGrid, NavPoint } from "./navGrid.js";
+export interface NavConstrainProposed {
+    position: EntityPosition;
+    rotationY: number;
+    grounded: boolean;
+}
+export interface NavConstrainEntity {
+    position: EntityPosition;
+}
+export interface NavConstrainOptions {
+    y?: (point: NavPoint) => number;
+}
+export declare function constrainToNavGrid(grid: NavGrid, options?: NavConstrainOptions): (proposed: NavConstrainProposed, entity: NavConstrainEntity) => NavConstrainProposed | null;

package/dist/nav/navConstrain.js

@@ -0,0 +1,26 @@
+function withYRemap(proposed, options) {
+    if (options?.y === undefined)
+        return proposed;
+    const y = options.y([proposed.position[0], proposed.position[2]]);
+    return { ...proposed, position: [proposed.position[0], y, proposed.position[2]] };
+}
+function walkable(grid, point) {
+    const cell = grid.cellAt(point);
+    return grid.isWalkable(cell.col, cell.row);
+}
+export function constrainToNavGrid(grid, options) {
+    return (proposed, entity) => {
+        const target = [proposed.position[0], proposed.position[2]];
+        if (walkable(grid, target))
+            return withYRemap(proposed, options);
+        const slideX = [entity.position[0], proposed.position[2]];
+        if (walkable(grid, slideX)) {
+            return withYRemap({ ...proposed, position: [entity.position[0], proposed.position[1], proposed.position[2]] }, options);
+        }
+        const slideZ = [proposed.position[0], entity.position[2]];
+        if (walkable(grid, slideZ)) {
+            return withYRemap({ ...proposed, position: [proposed.position[0], proposed.position[1], entity.position[2]] }, options);
+        }
+        return null;
+    };
+}

package/dist/nav/navFromEnvironment.d.ts

@@ -0,0 +1,11 @@
+import type { EnvironmentWorldFeature } from "../world/features.js";
+import type { Aabb } from "../world/geometry.js";
+export interface NavObstacleGrid {
+    blockAabb(aabb: Aabb): void;
+}
+/**
+ * Expands every structure descriptor on an environment world feature into its
+ * generated buildings and blocks their footprints on `grid`. Returns the
+ * number of buildings blocked.
+ */
+export declare function populateNavGridFromEnvironment(grid: NavObstacleGrid, world: EnvironmentWorldFeature): number;

package/dist/nav/navFromEnvironment.js

@@ -0,0 +1,16 @@
+import { resolveStructureBuildings } from "../world/environmentSummary.js";
+/**
+ * Expands every structure descriptor on an environment world feature into its
+ * generated buildings and blocks their footprints on `grid`. Returns the
+ * number of buildings blocked.
+ */
+export function populateNavGridFromEnvironment(grid, world) {
+    let blocked = 0;
+    for (const descriptor of world.structures ?? []) {
+        for (const building of resolveStructureBuildings(descriptor)) {
+            grid.blockAabb(building.bounds);
+            blocked += 1;
+        }
+    }
+    return blocked;
+}