@jgengine/core 0.15.0 → 0.17.0

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);
@@ -147,17 +175,25 @@ export function planServerPersist(server, snapshot, save, now) {
     const leaderboard = drained.increments.map((entry) => entry.scope === "server" && entry.serverId === undefined
         ? { ...entry, serverId: server.serverId }
         : 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 (isSaveEnabled(save) &&
-            saveScopeIncludesPlayer(save.scope) &&
-            snapshot.dirty.players.includes(userId)) {
+        if (roster.has(userId))
+            sessionPlayers[userId] = { ...persistent, session };
+        if (canWritePlayers && snapshot.dirty.players.includes(userId)) {
             profiles.push({
                 userId,
                 gameId: server.gameId,
@@ -169,7 +205,7 @@ export function planServerPersist(server, snapshot, save, now) {
     }
     const chunks = [];
     const deletedChunks = [];
-    if (isSaveEnabled(save) && saveScopeIncludesChunks(save.scope)) {
+    if (canWriteChunks) {
         for (const chunkKey of snapshot.dirty.chunks) {
             const chunk = snapshot.chunks[chunkKey];
             if (chunk) {
@@ -180,13 +216,20 @@ export function planServerPersist(server, snapshot, save, now) {
             }
         }
     }
+    // Server state is written unconditionally, so only unwritable player/chunk dirt keeps the row dirty;
+    // 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,
             serverState,
             sessionPlayers,
             revision: snapshot.revision,
-            dirtyAt: snapshot.dirty.server || snapshot.dirty.players.length > 0 ? now : server.dirtyAt,
+            dirtyAt: unwritten ? (server.dirtyAt ?? now) : undefined,
             updatedAt: now,
             lastSavedAt: now,
         },
@@ -194,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/objectRows.d.ts

@@ -0,0 +1,17 @@
+import type { SceneObject } from "../scene/objectStore.js";
+import type { RuntimeObjectRow } from "./snapshot.js";
+/**
+ * Convert a live placed object into its persisted row — the bridge between `ctx.scene.object` and
+ * `GameRuntimeSnapshot.server.objects`/`chunks[].objects`. Per-instance `state` is carried as
+ * `flags`. Presentation overrides (`visual`, `animation`) are catalog- and authoring-resolved and
+ * deliberately stay off the persisted row — put anything a command must own in `state`.
+ *
+ * @capability placed-object-rows a placed object's per-instance state and container contents convert to and from the persisted snapshot row a host stores
+ */
+export declare function toRuntimeObjectRow(object: SceneObject): RuntimeObjectRow;
+/**
+ * Inverse of {@link toRuntimeObjectRow}: rebuild the live placed object a host persisted.
+ *
+ * @capability placed-object-rehydrate rebuild live placed objects, with their state and slot contents, from persisted snapshot rows
+ */
+export declare function fromRuntimeObjectRow(row: RuntimeObjectRow): SceneObject;

package/dist/runtime/objectRows.js

@@ -0,0 +1,35 @@
+/**
+ * Convert a live placed object into its persisted row — the bridge between `ctx.scene.object` and
+ * `GameRuntimeSnapshot.server.objects`/`chunks[].objects`. Per-instance `state` is carried as
+ * `flags`. Presentation overrides (`visual`, `animation`) are catalog- and authoring-resolved and
+ * deliberately stay off the persisted row — put anything a command must own in `state`.
+ *
+ * @capability placed-object-rows a placed object's per-instance state and container contents convert to and from the persisted snapshot row a host stores
+ */
+export function toRuntimeObjectRow(object) {
+    return {
+        instanceId: object.instanceId,
+        catalogId: object.catalogId,
+        position: [object.position[0], object.position[1], object.position[2]],
+        rotationY: object.rotationY,
+        ...(object.parentSpace !== undefined ? { parentSpace: object.parentSpace } : {}),
+        ...(object.state !== undefined ? { flags: object.state } : {}),
+        ...(object.slots !== undefined ? { slots: object.slots } : {}),
+    };
+}
+/**
+ * Inverse of {@link toRuntimeObjectRow}: rebuild the live placed object a host persisted.
+ *
+ * @capability placed-object-rehydrate rebuild live placed objects, with their state and slot contents, from persisted snapshot rows
+ */
+export function fromRuntimeObjectRow(row) {
+    return {
+        instanceId: row.instanceId,
+        catalogId: row.catalogId,
+        position: [row.position[0], row.position[1], row.position[2]],
+        rotationY: row.rotationY ?? 0,
+        ...(row.parentSpace !== undefined ? { parentSpace: row.parentSpace } : {}),
+        ...(row.flags !== undefined ? { state: row.flags } : {}),
+        ...(row.slots !== undefined ? { slots: row.slots } : {}),
+    };
+}

package/dist/runtime/snapshot.d.ts

@@ -1,3 +1,4 @@
+import type { InventoryState } from "../inventory/inventoryModel.js";
 export declare const RUNTIME_SNAPSHOT_VERSION = 1;
 export type RuntimeEntityRow = {
     instanceId: string;
@@ -14,13 +15,20 @@ export type RuntimeEntityRow = {
     targetInstanceId?: string | null;
     userId?: string;
 };
+/**
+ * The persisted form of a placed `SceneObject`: identity, placement, per-instance state, and slot
+ * contents. Convert with `toRuntimeObjectRow`/`fromRuntimeObjectRow` (`runtime/objectRows`).
+ */
 export type RuntimeObjectRow = {
     instanceId: string;
     catalogId: string;
     position: [number, number, number];
     rotationY?: number;
     parentSpace?: string;
+    /** Opaque per-instance state; the persisted name for `SceneObject.state`. */
     flags?: Record<string, unknown>;
+    /** Container contents for a catalog `slotInventory` object. */
+    slots?: InventoryState;
 };
 export type RuntimeInventorySlot = {
     item: string;
@@ -93,3 +101,10 @@ export declare function splitProfilePlayer(player: RuntimePlayerRow): {
     persistent: RuntimePlayerRow;
     session: Record<string, unknown>;
 };
+/**
+ * Mark every player plus the server row dirty without bumping `revision` — the "write everything now"
+ * preparation a flush needs, because hydrating a snapshot from storage resets the dirty set to empty.
+ * Revision stays put so a flush cannot look like a mutation to the revision CAS.
+ * @internal
+ */
+export declare function markAllPlayersDirty(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot;

package/dist/runtime/snapshot.js

@@ -80,3 +80,15 @@ export function splitProfilePlayer(player) {
         session,
     };
 }
+/**
+ * Mark every player plus the server row dirty without bumping `revision` — the "write everything now"
+ * preparation a flush needs, because hydrating a snapshot from storage resets the dirty set to empty.
+ * Revision stays put so a flush cannot look like a mutation to the revision CAS.
+ * @internal
+ */
+export function markAllPlayersDirty(snapshot) {
+    return {
+        ...snapshot,
+        dirty: { ...snapshot.dirty, server: true, players: Object.keys(snapshot.players) },
+    };
+}

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,
     });