@jgengine/core 0.16.0 → 0.17.0

package/dist/runtime/gameRuntime.d.ts

@@ -37,6 +37,12 @@ export type HydrateInput = {
 export type GameRuntime = {
     gameId: string;
     save: SaveConfig;
+    /**
+     * Whether this runtime declares `loop.onTick`. A host's tick cron reads it to skip hydrating and
+     * persisting a server whose `tick` is a no-op by construction — the difference between a world that
+     * costs a full read/write every second while idle and one that costs nothing.
+     */
+    hasTick: boolean;
     hydrate: (input: HydrateInput) => GameRuntimeSnapshot;
     runCommand: (snapshot: GameRuntimeSnapshot, actorUserId: string, commandName: string, input: unknown) => ReturnType<typeof runCommand>;
     tick: (snapshot: GameRuntimeSnapshot, dtSeconds: number) => GameRuntimeSnapshot;

package/dist/runtime/gameRuntime.js

@@ -7,6 +7,7 @@ export function createGameRuntime(definition) {
     return {
         gameId: definition.gameId,
         save: definition.save,
+        hasTick: loop?.onTick !== undefined,
         hydrate(input) {
             let current = createRuntimeSnapshot({
                 gameId: input.gameId,

package/dist/runtime/hostPersistence.d.ts

@@ -151,14 +151,39 @@ export type HostPersistence = {
         userId: string;
     }) => Promise<Record<string, number>>;
 };
-/** @internal */
-export declare function buildHydratePlayers(server: GameServerRecord, profiles: Record<string, PlayerProfileRecord | null>): Record<string, RuntimePlayerRow>;
+/**
+ * Hydrate the runtime's player map from the server row plus whatever profiles were loaded.
+ *
+ * `userIds` narrows the work to a subset of the roster (partial hydration); omit it for the whole
+ * roster. A member with a loaded profile takes it as authoritative and keeps its session blob from
+ * the server row.
+ *
+ * A member with no profile row resolves by save scope, not by falling back to the blob: when the game
+ * persists players, a missing profile means the profile was deleted, so the member hydrates empty and
+ * the deletion sticks. Only a game that never writes profiles (`save: "none"`, or a scope without
+ * `player`) treats the server row's session copy as the player's state.
+ * @internal
+ */
+export declare function buildHydratePlayers(server: GameServerRecord, profiles: Record<string, PlayerProfileRecord | null>, userIds?: readonly string[]): Record<string, RuntimePlayerRow>;
+/** True when a snapshot carries no unwritten mutation — nothing for a persist to do. */
+export declare function isSnapshotClean(snapshot: GameRuntimeSnapshot): boolean;
 export type ServerPersistPlan = {
     server: GameServerRecord;
     profiles: PlayerProfileRecord[];
     chunks: WorldChunkRecord[];
     deletedChunks: string[];
     leaderboard: LeaderboardIncrement[];
+    /**
+     * Which fields of the server row the plan actually moved. A store that pays per written field —
+     * or whose subscribers re-push a whole document on any change — writes only what changed and skips
+     * the row entirely when `changed.any` is false.
+     */
+    changed: {
+        serverState: boolean;
+        sessionPlayers: boolean;
+        revision: boolean;
+        any: boolean;
+    };
 };
 /** @internal */
 export declare function planServerPersist(server: GameServerRecord, snapshot: GameRuntimeSnapshot, save: SaveConfig, now: number): ServerPersistPlan;

package/dist/runtime/hostPersistence.js

@@ -119,27 +119,55 @@ export function toOpenServerListings(listings, limit = OPEN_SERVER_LISTING_LIMIT
         .sort((a, b) => b.updatedAt - a.updatedAt)
         .slice(0, clampLimit(limit, OPEN_SERVER_LISTING_LIMIT, OPEN_SERVER_LISTING_MAX));
 }
-/** @internal */
-export function buildHydratePlayers(server, profiles) {
+/**
+ * Hydrate the runtime's player map from the server row plus whatever profiles were loaded.
+ *
+ * `userIds` narrows the work to a subset of the roster (partial hydration); omit it for the whole
+ * roster. A member with a loaded profile takes it as authoritative and keeps its session blob from
+ * the server row.
+ *
+ * A member with no profile row resolves by save scope, not by falling back to the blob: when the game
+ * persists players, a missing profile means the profile was deleted, so the member hydrates empty and
+ * the deletion sticks. Only a game that never writes profiles (`save: "none"`, or a scope without
+ * `player`) treats the server row's session copy as the player's state.
+ * @internal
+ */
+export function buildHydratePlayers(server, profiles, userIds) {
+    const persistsPlayers = isSaveEnabled(server.save) && saveScopeIncludesPlayer(server.save.scope);
     const players = {};
-    for (const userId of server.memberUserIds) {
+    for (const userId of userIds ?? server.memberUserIds) {
         const profile = profiles[userId] ?? null;
         const sessionPlayer = server.sessionPlayers[userId];
+        const session = sessionPlayer?.session;
         if (profile) {
             players[userId] = {
                 ...profile.playerState,
-                ...(sessionPlayer?.session ? { session: sessionPlayer.session } : {}),
+                ...(session ? { session } : {}),
             };
         }
-        else if (sessionPlayer) {
+        else if (sessionPlayer && !persistsPlayers) {
             players[userId] = sessionPlayer;
         }
         else {
-            players[userId] = createEmptyPlayerRow(userId);
+            players[userId] = {
+                ...createEmptyPlayerRow(userId),
+                ...(session ? { session } : {}),
+            };
         }
     }
     return players;
 }
+/** True when a snapshot carries no unwritten mutation — nothing for a persist to do. */
+export function isSnapshotClean(snapshot) {
+    return (!snapshot.dirty.server &&
+        snapshot.dirty.players.length === 0 &&
+        snapshot.dirty.chunks.length === 0);
+}
+function sameJson(a, b) {
+    if (a === b)
+        return true;
+    return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
 /** @internal */
 export function planServerPersist(server, snapshot, save, now) {
     const drained = drainPendingLeaderboardIncrements(snapshot.server.session);
@@ -149,14 +177,22 @@ export function planServerPersist(server, snapshot, save, now) {
         : entry);
     const canWritePlayers = isSaveEnabled(save) && saveScopeIncludesPlayer(save.scope);
     const canWriteChunks = isSaveEnabled(save) && saveScopeIncludesChunks(save.scope);
+    // Merged over the stored map rather than rebuilt from `snapshot.players`, so a partially hydrated
+    // snapshot cannot drop the session state of members it never loaded.
     const sessionPlayers = {};
+    const roster = new Set(server.memberUserIds);
+    for (const [userId, stored] of Object.entries(server.sessionPlayers ?? {})) {
+        if (roster.has(userId))
+            sessionPlayers[userId] = stored;
+    }
     const profiles = [];
     for (const userId of Object.keys(snapshot.players)) {
         const player = snapshot.players[userId];
         if (!player)
             continue;
         const { persistent, session } = splitProfilePlayer(player);
-        sessionPlayers[userId] = { ...persistent, session };
+        if (roster.has(userId))
+            sessionPlayers[userId] = { ...persistent, session };
         if (canWritePlayers && snapshot.dirty.players.includes(userId)) {
             profiles.push({
                 userId,
@@ -184,6 +220,9 @@ export function planServerPersist(server, snapshot, save, now) {
     // anything else would make shouldAutoSave re-fire forever after a successful full flush.
     const unwritten = (snapshot.dirty.players.length > 0 && !canWritePlayers) ||
         (snapshot.dirty.chunks.length > 0 && !canWriteChunks);
+    const serverStateChanged = !sameJson(serverState, server.serverState);
+    const sessionPlayersChanged = !sameJson(sessionPlayers, server.sessionPlayers);
+    const revisionChanged = snapshot.revision !== server.revision;
     return {
         server: {
             ...server,
@@ -198,5 +237,18 @@ export function planServerPersist(server, snapshot, save, now) {
         chunks,
         deletedChunks,
         leaderboard,
+        changed: {
+            serverState: serverStateChanged,
+            sessionPlayers: sessionPlayersChanged,
+            revision: revisionChanged,
+            any: serverStateChanged ||
+                sessionPlayersChanged ||
+                revisionChanged ||
+                profiles.length > 0 ||
+                chunks.length > 0 ||
+                deletedChunks.length > 0 ||
+                leaderboard.length > 0 ||
+                (server.dirtyAt !== undefined) !== unwritten,
+        },
     };
 }

package/dist/runtime/hostPolicy.d.ts

@@ -1,4 +1,58 @@
 import type { GameServerStatus, SessionVisibility } from "./hostPersistence.js";
+/**
+ * Hard ceiling on `slotsPerServer` for a single hosted server row.
+ *
+ * A hosted server keeps its whole roster, every member's session state, and the world row in one
+ * backing document. On Convex that document caps at 1 MiB with at most 1024 entries in an object, and
+ * the host rewrites the session map on every persist — so member count is a per-transaction cost, not
+ * just a number in a config. 256 leaves room for a real world row and a real session blob per member
+ * inside those limits. A world that needs more concurrent players needs more than one server row.
+ */
+export declare const JG_MAX_MEMBERS_PER_SERVER = 256;
+/** Whether a `slotsPerServer` value is a capacity a single hosted server row can actually hold. */
+export declare function validateSlotsPerServer(slotsPerServer: number): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * How auto-match behaves when no `serverId` is supplied.
+ *
+ * - `"auto"` — fill open public rooms, create a new one when none has capacity (many parallel rooms).
+ * - `"singleton"` — one shared world per game: always match the existing room, and refuse the join
+ *   when it is full rather than silently starting a second world the player would be alone in.
+ */
+export type MatchmakingMode = "auto" | "singleton";
+/** A row `selectJoinTarget` can choose between — the matchmaking-relevant fields of a server record. */
+export type JoinCandidate = {
+    memberUserIds: readonly string[];
+    slotsPerServer: number;
+    visibility?: SessionVisibility | undefined;
+    createdAt: number;
+};
+/** What a join should do with the candidate rows it found. */
+export type JoinTarget<T extends JoinCandidate> = {
+    kind: "join";
+    row: T;
+} | {
+    kind: "create";
+} | {
+    kind: "refuse";
+    reason: string;
+};
+/**
+ * Resolve an auto-match join against the game's joinable rows under a {@link MatchmakingMode}.
+ * Reach for it instead of hand-rolling the "find a room with space, else make one" scan, which is
+ * where a singleton world silently shards into per-player copies.
+ * @capability host-join-target choose or refuse an auto-matched server under a matchmaking mode
+ */
+export declare function selectJoinTarget<T extends JoinCandidate>(rows: readonly T[], args: {
+    userId: string;
+    mode?: MatchmakingMode;
+    /** Capacity to judge rows against — the host's current option, when it supersedes the stored value. */
+    slotsPerServer?: number;
+}): JoinTarget<T>;
 /**
  * True when a server's `visibility` should surface in public listings / browse results.
  * @capability host-listing-filter exclude private sessions from public browse results

package/dist/runtime/hostPolicy.js

@@ -1,4 +1,57 @@
 import { normalizeJoinCode } from "../multiplayer/matchmaking.js";
+/**
+ * Hard ceiling on `slotsPerServer` for a single hosted server row.
+ *
+ * A hosted server keeps its whole roster, every member's session state, and the world row in one
+ * backing document. On Convex that document caps at 1 MiB with at most 1024 entries in an object, and
+ * the host rewrites the session map on every persist — so member count is a per-transaction cost, not
+ * just a number in a config. 256 leaves room for a real world row and a real session blob per member
+ * inside those limits. A world that needs more concurrent players needs more than one server row.
+ */
+export const JG_MAX_MEMBERS_PER_SERVER = 256;
+/** Whether a `slotsPerServer` value is a capacity a single hosted server row can actually hold. */
+export function validateSlotsPerServer(slotsPerServer) {
+    if (!Number.isInteger(slotsPerServer) || slotsPerServer < 1) {
+        return { ok: false, reason: `slotsPerServer must be a positive integer, got ${slotsPerServer}` };
+    }
+    if (slotsPerServer > JG_MAX_MEMBERS_PER_SERVER) {
+        return {
+            ok: false,
+            reason: `slotsPerServer ${slotsPerServer} exceeds JG_MAX_MEMBERS_PER_SERVER (${JG_MAX_MEMBERS_PER_SERVER}). ` +
+                "One hosted server row holds its roster, every member's session state, and the world row in a " +
+                "single document; past this the host cannot guarantee the write fits. Shard across servers instead.",
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Resolve an auto-match join against the game's joinable rows under a {@link MatchmakingMode}.
+ * Reach for it instead of hand-rolling the "find a room with space, else make one" scan, which is
+ * where a singleton world silently shards into per-player copies.
+ * @capability host-join-target choose or refuse an auto-matched server under a matchmaking mode
+ */
+export function selectJoinTarget(rows, args) {
+    const capacityOf = (row) => args.slotsPerServer ?? row.slotsPerServer;
+    const member = rows.find((row) => isServerMember(row.memberUserIds, args.userId));
+    if (member)
+        return { kind: "join", row: member };
+    if ((args.mode ?? "auto") === "singleton") {
+        const oldest = rows.reduce((best, row) => (best === null || row.createdAt < best.createdAt ? row : best), null);
+        if (oldest === null)
+            return { kind: "create" };
+        if (oldest.memberUserIds.length >= capacityOf(oldest)) {
+            return { kind: "refuse", reason: "Server is full" };
+        }
+        return { kind: "join", row: oldest };
+    }
+    const open = rows.find((row) => isAutoJoinCandidate({
+        memberUserIds: row.memberUserIds,
+        slotsPerServer: capacityOf(row),
+        visibility: row.visibility,
+        userId: args.userId,
+    }));
+    return open === undefined ? { kind: "create" } : { kind: "join", row: open };
+}
 /**
  * True when a server's `visibility` should surface in public listings / browse results.
  * @capability host-listing-filter exclude private sessions from public browse results

package/dist/runtime/worldChunks.d.ts

@@ -0,0 +1,39 @@
+import type { GameRuntimeSnapshot, RuntimeChunkRow } from "./snapshot.js";
+/** Default edge length, in world units, of one persisted world chunk. */
+export declare const DEFAULT_CHUNK_SIZE = 64;
+/** Integer cell coordinates of a chunk on the ground plane. */
+export type ChunkCoord = {
+    cx: number;
+    cz: number;
+};
+/**
+ * Chunk key for a cell — the canonical `"cx,cz"` string a `jgWorldChunks` row is stored under.
+ * Games used to invent this mapping each time, which made two systems in one game disagree about
+ * which row a position belongs to.
+ * @capability world-chunk-key map world positions to persisted chunk keys at a declared cell size
+ */
+export declare function chunkKeyOf(coord: ChunkCoord): string;
+/** Chunk coordinates containing a world position at `size` units per cell. */
+export declare function chunkCoordAt(position: readonly [number, number, number], size?: number): ChunkCoord;
+/** Chunk key containing a world position at `size` units per cell. */
+export declare function chunkKeyAt(position: readonly [number, number, number], size?: number): string;
+/** Parse a `chunkKeyOf` string back to coordinates; `null` for anything not in that form. */
+export declare function parseChunkKey(key: string): ChunkCoord | null;
+/**
+ * Every chunk key whose cell intersects a radius around a world position — the key list a viewer's
+ * bounded hydration or client chunk query asks for, instead of loading a whole world.
+ */
+export declare function chunkKeysInRadius(center: readonly [number, number, number], radius: number, size?: number): string[];
+/** An empty chunk row for `chunkKey` — the starting value for a cell nothing has been placed in yet. */
+export declare function createEmptyChunkRow(chunkKey: string): RuntimeChunkRow;
+/**
+ * Write a chunk into a snapshot and mark it dirty, so the next persist actually stores it.
+ * The engine never writes `dirty.chunks` for a raw `snapshot.chunks[key] = …` assignment, so a command
+ * that mutated the map by hand silently never saved that chunk.
+ * @capability world-chunk-write mutate a snapshot's chunk and have the host persist it
+ */
+export declare function setChunk(snapshot: GameRuntimeSnapshot, chunkKey: string, chunk: RuntimeChunkRow): GameRuntimeSnapshot;
+/** Read-modify-write a chunk (creating it empty when absent), marking it dirty. */
+export declare function updateChunk(snapshot: GameRuntimeSnapshot, chunkKey: string, update: (chunk: RuntimeChunkRow) => RuntimeChunkRow): GameRuntimeSnapshot;
+/** Drop a chunk from a snapshot and mark the key dirty so the host deletes its stored row. */
+export declare function deleteChunk(snapshot: GameRuntimeSnapshot, chunkKey: string): GameRuntimeSnapshot;

package/dist/runtime/worldChunks.js

@@ -0,0 +1,83 @@
+/** Default edge length, in world units, of one persisted world chunk. */
+export const DEFAULT_CHUNK_SIZE = 64;
+/**
+ * Chunk key for a cell — the canonical `"cx,cz"` string a `jgWorldChunks` row is stored under.
+ * Games used to invent this mapping each time, which made two systems in one game disagree about
+ * which row a position belongs to.
+ * @capability world-chunk-key map world positions to persisted chunk keys at a declared cell size
+ */
+export function chunkKeyOf(coord) {
+    return `${coord.cx},${coord.cz}`;
+}
+/** Chunk coordinates containing a world position at `size` units per cell. */
+export function chunkCoordAt(position, size = DEFAULT_CHUNK_SIZE) {
+    return { cx: Math.floor(position[0] / size), cz: Math.floor(position[2] / size) };
+}
+/** Chunk key containing a world position at `size` units per cell. */
+export function chunkKeyAt(position, size = DEFAULT_CHUNK_SIZE) {
+    return chunkKeyOf(chunkCoordAt(position, size));
+}
+/** Parse a `chunkKeyOf` string back to coordinates; `null` for anything not in that form. */
+export function parseChunkKey(key) {
+    const [rawX, rawZ, ...rest] = key.split(",");
+    if (rest.length > 0 || rawX === undefined || rawZ === undefined)
+        return null;
+    const cx = Number(rawX);
+    const cz = Number(rawZ);
+    if (!Number.isInteger(cx) || !Number.isInteger(cz))
+        return null;
+    return { cx, cz };
+}
+/**
+ * Every chunk key whose cell intersects a radius around a world position — the key list a viewer's
+ * bounded hydration or client chunk query asks for, instead of loading a whole world.
+ */
+export function chunkKeysInRadius(center, radius, size = DEFAULT_CHUNK_SIZE) {
+    const min = chunkCoordAt([center[0] - radius, center[1], center[2] - radius], size);
+    const max = chunkCoordAt([center[0] + radius, center[1], center[2] + radius], size);
+    const keys = [];
+    for (let cx = min.cx; cx <= max.cx; cx += 1) {
+        for (let cz = min.cz; cz <= max.cz; cz += 1)
+            keys.push(chunkKeyOf({ cx, cz }));
+    }
+    return keys;
+}
+/** An empty chunk row for `chunkKey` — the starting value for a cell nothing has been placed in yet. */
+export function createEmptyChunkRow(chunkKey) {
+    return { chunkKey, objects: [], entities: [] };
+}
+function withChunkDirty(snapshot, chunkKey) {
+    return snapshot.dirty.chunks.includes(chunkKey)
+        ? snapshot.dirty.chunks
+        : [...snapshot.dirty.chunks, chunkKey];
+}
+/**
+ * Write a chunk into a snapshot and mark it dirty, so the next persist actually stores it.
+ * The engine never writes `dirty.chunks` for a raw `snapshot.chunks[key] = …` assignment, so a command
+ * that mutated the map by hand silently never saved that chunk.
+ * @capability world-chunk-write mutate a snapshot's chunk and have the host persist it
+ */
+export function setChunk(snapshot, chunkKey, chunk) {
+    return {
+        ...snapshot,
+        chunks: { ...snapshot.chunks, [chunkKey]: { ...chunk, chunkKey } },
+        revision: snapshot.revision + 1,
+        dirty: { ...snapshot.dirty, server: true, chunks: withChunkDirty(snapshot, chunkKey) },
+    };
+}
+/** Read-modify-write a chunk (creating it empty when absent), marking it dirty. */
+export function updateChunk(snapshot, chunkKey, update) {
+    const current = snapshot.chunks[chunkKey] ?? createEmptyChunkRow(chunkKey);
+    return setChunk(snapshot, chunkKey, update(current));
+}
+/** Drop a chunk from a snapshot and mark the key dirty so the host deletes its stored row. */
+export function deleteChunk(snapshot, chunkKey) {
+    const chunks = { ...snapshot.chunks };
+    delete chunks[chunkKey];
+    return {
+        ...snapshot,
+        chunks,
+        revision: snapshot.revision + 1,
+        dirty: { ...snapshot.dirty, server: true, chunks: withChunkDirty(snapshot, chunkKey) },
+    };
+}

package/dist/runtime/worldProjection.d.ts

@@ -1,5 +1,5 @@
-import type { SceneEntity } from "../scene/entityStore.js";
-import type { SnapshotViewer } from "./worldSnapshot.js";
+import type { EntityPosition, SceneEntity } from "../scene/entityStore.js";
+import type { SnapshotViewer, WorldSnapshot } from "./worldSnapshot.js";
 /**
  * Host-side interest/privacy policy — how the authoritative world projects to each viewer over the
  * wire. Unset (the default) means every client receives the whole world, exactly as before. Enabling a
@@ -39,6 +39,20 @@ export declare function visibleEntityIds(entities: readonly SceneEntity[], viewe
  * @internal host projection plumbing
  */
 export declare function projectByVisibleIds<T>(byId: Record<string, T>, visible: Set<string>): Record<string, T>;
+/** Where a viewer is standing, read off the replicated entity set; `undefined` when it has no entity yet.
+ * @internal host projection plumbing
+ */
+export declare function viewerOrigin(world: WorldSnapshot, viewer: SnapshotViewer): EntityPosition | undefined;
+/**
+ * Cull placed objects to a viewer's area of interest. Placed objects are the one large spatial set a
+ * world grows without bound — a datacenter of racks, a city of props — so without this every viewer
+ * downloads every placement. Fails open (full list) when the viewer has no locatable entity, matching
+ * {@link projectEntitiesForViewer}.
+ * @internal host projection plumbing
+ */
+export declare function projectObjectsForViewer<T extends {
+    position: EntityPosition;
+}>(objects: readonly T[], origin: EntityPosition | undefined, radius: number): readonly T[];
 /**
  * Narrow a `userId → state` record to only the viewer's own entry — the projection for private
  * per-user state (inventory, wallets) so one client never receives another player's private data.

package/dist/runtime/worldProjection.js

@@ -41,6 +41,26 @@ export function projectByVisibleIds(byId, visible) {
             out[id] = value;
     return out;
 }
+/** Where a viewer is standing, read off the replicated entity set; `undefined` when it has no entity yet.
+ * @internal host projection plumbing
+ */
+export function viewerOrigin(world, viewer) {
+    const entities = (world["entities"] ?? []);
+    return entities.find((entity) => entity.id === viewer.userId)?.position;
+}
+/**
+ * Cull placed objects to a viewer's area of interest. Placed objects are the one large spatial set a
+ * world grows without bound — a datacenter of racks, a city of props — so without this every viewer
+ * downloads every placement. Fails open (full list) when the viewer has no locatable entity, matching
+ * {@link projectEntitiesForViewer}.
+ * @internal host projection plumbing
+ */
+export function projectObjectsForViewer(objects, origin, radius) {
+    if (origin === undefined)
+        return objects;
+    const radiusSquared = radius * radius;
+    return objects.filter((object) => distanceSquared(object.position, origin) <= radiusSquared);
+}
 /**
  * Narrow a `userId → state` record to only the viewer's own entry — the projection for private
  * per-user state (inventory, wallets) so one client never receives another player's private data.

package/dist/scene/behaviorRuntime.js

@@ -1,8 +1,11 @@
 import { seededRng } from "../random/rng.js";
 import { advancePathFollow, createPathFollow, pathFollowSeek, } from "../nav/pathFollow.js";
+import { resolveWalkerStep } from "../movement/solidObstacles.js";
 import { perContext } from "../runtime/perContext.js";
 const DEFAULT_WANDER_SPEED = 1.5;
 const WANDER_ARRIVAL = 0.6;
+/** Below this share of its intended step a wanderer counts as blocked and re-rolls its target. */
+const WANDER_BLOCKED_FRACTION = 0.25;
 function patrolOf(entity) {
     return entity.behaviors.find((b) => b.kind === "patrol") ?? null;
 }
@@ -72,18 +75,37 @@ function stepWander(ctx, id, nav, dt) {
     if (dist < 1e-6)
         return;
     const step = Math.min(dist, speed * dt);
-    const nx = px + (dx / dist) * step;
-    const nz = pz + (dz / dist) * step;
+    const desired = resolveWalkerStep(ctx, entity.position, (dx / dist) * step, (dz / dist) * step);
+    const nx = px + desired.stepX;
+    const nz = pz + desired.stepZ;
+    // A wanderer pinned against a solid picks a fresh target next tick instead of grinding into it.
+    if (Math.hypot(desired.stepX, desired.stepZ) < step * WANDER_BLOCKED_FRACTION)
+        nav.target = null;
     ctx.scene.entity.setPose(id, {
         position: [nx, ctx.world.groundHeightAt(nx, nz), nz],
         rotationY: Math.atan2(dx, dz),
         dt,
     });
 }
+/**
+ * Pose a patroller at its path point, with the *move* to that point slid against solids. The path state
+ * still advances on its own clock — the route is authored, and rewinding it on contact would stall the
+ * whole patrol behind one prop — but the entity can no longer end a tick inside geometry the player
+ * cannot walk through. A route drawn through a building shows up as an NPC pressed against its wall,
+ * which is the authoring bug made visible rather than hidden.
+ */
 function posePatrol(ctx, id, nav, dt) {
     const [x, y, z] = nav.state.position;
+    const entity = ctx.scene.entity.get(id);
+    let px = x;
+    let pz = z;
+    if (entity !== null) {
+        const step = resolveWalkerStep(ctx, entity.position, x - entity.position[0], z - entity.position[2]);
+        px = entity.position[0] + step.stepX;
+        pz = entity.position[2] + step.stepZ;
+    }
     ctx.scene.entity.setPose(id, {
-        position: nav.groundClamp ? [x, ctx.world.groundHeightAt(x, z), z] : [x, y, z],
+        position: nav.groundClamp ? [px, ctx.world.groundHeightAt(px, pz), pz] : [px, y, pz],
         rotationY: nav.state.heading,
         dt,
     });

package/dist/scene/spatial.d.ts

@@ -17,6 +17,12 @@ export interface MoveTowardOptions {
     speed: number;
     stopDistance?: number;
     dt: number;
+    /**
+     * Slide the step against the solid geometry that blocks the player instead of lerping through it
+     * (default `true` wherever the runtime wires a resolver). Set `false` for a mover that is meant to
+     * ignore the world — a flier, a camera rig, a decorative drift.
+     */
+    avoidSolids?: boolean;
 }
 export interface SpatialGridOptions {
     cellSize: number;
@@ -37,6 +43,16 @@ export interface SpatialApiOptions {
     grid?: SpatialGridOptions | false;
     /** When this number changes between queries, the grid rebuilds without an explicit `invalidate()`. */
     getVersion?: () => number;
+    /**
+     * Slide a horizontal step against the scene's solid geometry, returning the step actually allowed.
+     * Wired by the runtime to the same blocking-collider query the player resolver reads, so a chaser
+     * calling `moveToward` stops at the wall the player stops at. Omitted (tests, bare indexes) leaves
+     * `moveToward` a pure lerp.
+     */
+    resolveStep?: (position: EntityPosition, stepX: number, stepZ: number) => {
+        stepX: number;
+        stepZ: number;
+    };
 }
 export interface SpatialApi {
     distance(aInstanceId: string, bInstanceId: string): number | null;

package/dist/scene/spatial.js

@@ -23,7 +23,7 @@ function packCell(cx, cz) {
 }
 const DEFAULT_CELL_SIZE = 8;
 export function createSpatialApi(options) {
-    const { resolvePosition, candidates, occluder, getVersion } = options;
+    const { resolvePosition, candidates, occluder, getVersion, resolveStep } = options;
     const gridConfig = options.grid === false ? undefined : (options.grid ?? { cellSize: DEFAULT_CELL_SIZE });
     const cellSize = gridConfig?.cellSize;
     let gridIndex = null;
@@ -198,7 +198,7 @@ export function createSpatialApi(options) {
         invalidate() {
             gridDirty = true;
         },
-        moveToward(instanceId, target, { speed, stopDistance = 0, dt }) {
+        moveToward(instanceId, target, { speed, stopDistance = 0, dt, avoidSolids = true }) {
             const current = resolvePosition(instanceId);
             const destination = resolveTarget(target);
             if (current === undefined || destination === undefined)
@@ -209,10 +209,13 @@ export function createSpatialApi(options) {
                 return current;
             const step = Math.min(speed * dt, remaining);
             const scale = step / total;
+            const stepX = (destination[0] - current[0]) * scale;
+            const stepZ = (destination[2] - current[2]) * scale;
+            const slid = avoidSolids && resolveStep !== undefined ? resolveStep(current, stepX, stepZ) : { stepX, stepZ };
             return [
-                current[0] + (destination[0] - current[0]) * scale,
+                current[0] + slid.stepX,
                 current[1] + (destination[1] - current[1]) * scale,
-                current[2] + (destination[2] - current[2]) * scale,
+                current[2] + slid.stepZ,
             ];
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",