@jgengine/core 0.16.0 → 0.18.0

package/dist/runtime/commandRunner.d.ts

@@ -1,10 +1,46 @@
 export type CommandValidationError = {
     reason: string;
 };
+/**
+ * Which slice of a server has to be hydrated before some work runs against it. Both fields default to
+ * "everything", which costs a read per member plus one per chunk — the cost that makes a large shared
+ * world unaffordable per mutation. Narrow them when the caller knows what it will touch.
+ */
+export type CommandScope = {
+    /** Member ids to hydrate; omit for the whole roster. */
+    players?: readonly string[];
+    /** Chunk keys to hydrate; omit for every chunk of the server, `[]` for none. */
+    chunkKeys?: readonly string[];
+};
 export type CommandDef<TInput = unknown> = {
+    /**
+     * What this command reads and writes, derived from its own input. A host that hydrates through a
+     * scope loads only this slice instead of the whole world, and refuses the command if `apply` then
+     * dirties a player or chunk the scope did not name — writing an unhydrated chunk would overwrite
+     * the stored one with a blank. Omit it to keep the whole-world default.
+     */
+    scope?: (input: TInput, actorUserId: string) => CommandScope;
     validate: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string) => CommandValidationError | null;
     apply: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string) => import("./snapshot.js").GameRuntimeSnapshot;
 };
+/**
+ * The scope a command declares for this input, or `undefined` when it declares none (hydrate everything).
+ * Evaluate it before hydration: the actor and the command's own input are both known by then.
+ * @internal
+ */
+export declare function resolveCommandScope<TInput>(commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string): CommandScope | undefined;
+/**
+ * Widen a scope so the actor is always hydrated. A command's own player row is dirtied by
+ * {@link runCommand} whatever the command did, and an unhydrated player is dropped from the persist.
+ * @internal
+ */
+export declare function scopeWithActor(scope: CommandScope | undefined, actorUserId: string): CommandScope | undefined;
+/**
+ * Why a command's writes escaped the scope it was hydrated under, or `null` when they did not.
+ * A write outside the scope is a silent overwrite of unread state, so the host refuses it.
+ * @internal
+ */
+export declare function commandScopeEscape(scope: CommandScope | undefined, dirty: import("./snapshot.js").GameRuntimeSnapshot["dirty"], commandName: string): string | null;
 export type RunCommandResult = {
     ok: true;
     snapshot: import("./snapshot.js").GameRuntimeSnapshot;

package/dist/runtime/commandRunner.js

@@ -1,3 +1,39 @@
+/**
+ * The scope a command declares for this input, or `undefined` when it declares none (hydrate everything).
+ * Evaluate it before hydration: the actor and the command's own input are both known by then.
+ * @internal
+ */
+export function resolveCommandScope(commands, commandName, input, actorUserId) {
+    return commands[commandName]?.scope?.(input, actorUserId);
+}
+/**
+ * Widen a scope so the actor is always hydrated. A command's own player row is dirtied by
+ * {@link runCommand} whatever the command did, and an unhydrated player is dropped from the persist.
+ * @internal
+ */
+export function scopeWithActor(scope, actorUserId) {
+    if (!scope || scope.players === undefined || scope.players.includes(actorUserId))
+        return scope;
+    return { ...scope, players: [...scope.players, actorUserId] };
+}
+/**
+ * Why a command's writes escaped the scope it was hydrated under, or `null` when they did not.
+ * A write outside the scope is a silent overwrite of unread state, so the host refuses it.
+ * @internal
+ */
+export function commandScopeEscape(scope, dirty, commandName) {
+    if (!scope)
+        return null;
+    const strayPlayers = scope.players === undefined ? [] : dirty.players.filter((id) => !scope.players?.includes(id));
+    const strayChunks = scope.chunkKeys === undefined ? [] : dirty.chunks.filter((key) => !scope.chunkKeys?.includes(key));
+    if (strayPlayers.length === 0 && strayChunks.length === 0)
+        return null;
+    const parts = [
+        strayPlayers.length > 0 ? `players ${strayPlayers.join(", ")}` : null,
+        strayChunks.length > 0 ? `chunks ${strayChunks.join(", ")}` : null,
+    ].filter((part) => part !== null);
+    return `Command "${commandName}" wrote outside its declared scope: ${parts.join("; ")}`;
+}
 /** @internal */
 export function runCommand(snapshot, commands, commandName, input, actorUserId) {
     const command = commands[commandName];

package/dist/runtime/context/scene.js

@@ -11,6 +11,8 @@ import { createPaintLayer } from "../../scene/paintLayer.js";
 import { createSelectionSet } from "../../scene/selection.js";
 import { createSceneRaycast, } from "../../scene/sceneRaycast.js";
 import { createSpatialApi } from "../../scene/spatial.js";
+import { DEFAULT_OBSTACLE_PLAYER_RADIUS } from "../../movement/movementModel.js";
+import { createObstacleReachCache, slideStep, sourceObstacleReach, sourceObstaclesNear, } from "../../movement/solidObstacles.js";
 import { createTargeting } from "../../scene/targeting.js";
 import { notifyAfter } from "../../store/changeSignal.js";
 /** @internal */
@@ -50,11 +52,20 @@ export function createSceneSubsystem(d) {
         candidateIdsDirty = false;
         return candidateIds;
     }
+    // `moveToward` reads the same blocking colliders the player resolver does, so a chaser stops at the
+    // wall that stops the player rather than lerping through it.
+    const walkerReach = createObstacleReachCache();
+    const solidSource = {
+        list: () => objects.list(),
+        inBox: (min, max) => objects.inBox(min, max),
+        collidersOf: (instanceId) => objectCollidersOf(instanceId),
+    };
     const spatial = createSpatialApi({
         resolvePosition: (instanceId) => entities.get(instanceId)?.position,
         candidates: refreshCandidateIds,
         grid: { cellSize: 8 },
         getVersion: () => spatialGeneration,
+        resolveStep: (position, stepX, stepZ) => slideStep(position, stepX, stepZ, sourceObstaclesNear(solidSource, sourceObstacleReach(solidSource, walkerReach), position, Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS, Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS)),
         ...(occluder !== undefined ? { occluder } : {}),
     });
     entities.subscribe(() => {

package/dist/runtime/gameContext.js

@@ -14,7 +14,7 @@ import {} from "../scene/entityStore.js";
 import { createChangeSignal, notifyAfter } from "../store/changeSignal.js";
 import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
 import { applyWorldSnapshot, composeWorldSnapshot, } from "./worldSnapshot.js";
-import { policyProjectsViewers, projectByVisibleIds, projectEntitiesForViewer, projectPerUserForViewer, visibleEntityIds, } from "./worldProjection.js";
+import { policyProjectsViewers, projectByVisibleIds, projectEntitiesForViewer, projectObjectsForViewer, projectPerUserForViewer, viewerOrigin, visibleEntityIds, } from "./worldProjection.js";
 import { createRuntimeSave } from "./runtimeSave.js";
 import { isOffline } from "./adapter.js";
 import { localSaveBackend, memorySaveBackend } from "../game/saveStore.js";
@@ -299,6 +299,9 @@ export function createGameContext(options) {
         if (aoiRadius !== undefined && key === "stats") {
             return typedProject((data, viewer, world) => projectByVisibleIds(data, visibleEntityIds((world["entities"] ?? []), viewer, aoiRadius)));
         }
+        if (aoiRadius !== undefined && key === "objects") {
+            return typedProject((data, viewer, world) => projectObjectsForViewer(data, viewerOrigin(world, viewer), aoiRadius));
+        }
         if (replication?.privatePerUser === true && key === "inventory") {
             return typedProject((data, viewer) => projectPerUserForViewer(data, viewer));
         }

package/dist/runtime/gameRuntime.d.ts

@@ -1,11 +1,17 @@
 import type { SaveConfig } from "./save.js";
-import type { CommandDef } from "./commandRunner.js";
+import type { CommandDef, CommandScope } from "./commandRunner.js";
 import { runCommand } from "./commandRunner.js";
 import { type GameRuntimeSnapshot, type RuntimeChunkRow, type RuntimePlayerRow, type RuntimeProfileRow, type RuntimeServerRow } from "./snapshot.js";
 export type ServerLoopHooks = {
     onInit?: (ctx: RuntimeInitContext) => void;
     onNewPlayer?: (ctx: RuntimeLoopContext) => void;
     onTick?: (ctx: RuntimeWorldContext, dtSeconds: number) => void;
+    /**
+     * What `onNewPlayer` touches, so a join hydrates that instead of the whole world. Only consulted
+     * when `onNewPlayer` exists — without the hook a join provably needs the joining member and nothing
+     * else. Omit it and a join keeps hydrating everything.
+     */
+    joinScope?: (userId: string, isNew: boolean) => CommandScope;
 };
 export type RuntimeInitContext = {
     snapshot: GameRuntimeSnapshot;
@@ -37,8 +43,21 @@ 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>;
+    /**
+     * What a command declares it will touch, evaluated before hydration so a host can load that slice
+     * and nothing else. `undefined` means the command declared no scope — hydrate everything.
+     */
+    commandScope: (commandName: string, input: unknown, actorUserId: string) => CommandScope | undefined;
+    /** What a join has to hydrate. `undefined` means the whole world, as when `onNewPlayer` is unscoped. */
+    joinScope: (userId: string, isNew: boolean) => CommandScope | undefined;
     tick: (snapshot: GameRuntimeSnapshot, dtSeconds: number) => GameRuntimeSnapshot;
     joinPlayer: (snapshot: GameRuntimeSnapshot, userId: string, isNew: boolean) => GameRuntimeSnapshot;
     toProfileRow: (snapshot: GameRuntimeSnapshot, userId: string) => RuntimeProfileRow | null;

package/dist/runtime/gameRuntime.js

@@ -1,4 +1,4 @@
-import { runCommand } from "./commandRunner.js";
+import { resolveCommandScope, runCommand } from "./commandRunner.js";
 import { createEmptyPlayerRow, createRuntimeSnapshot, } from "./snapshot.js";
 /** @internal */
 export function createGameRuntime(definition) {
@@ -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,
@@ -32,6 +33,14 @@ export function createGameRuntime(definition) {
         runCommand(snapshot, actorUserId, commandName, input) {
             return runCommand(snapshot, definition.commands, commandName, input, actorUserId);
         },
+        commandScope(commandName, input, actorUserId) {
+            return resolveCommandScope(definition.commands, commandName, input, actorUserId);
+        },
+        joinScope(userId, isNew) {
+            if (!loop?.onNewPlayer)
+                return { players: [userId], chunkKeys: [] };
+            return loop.joinScope?.(userId, isNew);
+        },
         tick(snapshot, dtSeconds) {
             if (!loop?.onTick)
                 return snapshot;

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/transport.d.ts

@@ -62,6 +62,12 @@ export type GameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGa
 };
 export type PresencePoseRow = {
     userId: string;
+    /** Set when the host tracks presence per session, so one user can hold two rows. */
+    sessionId?: string;
+    /** Actor class, e.g. `"player"` / `"agent"` — a host may clamp each differently. */
+    kind?: string;
+    /** Display name carried on the row, so a nameplate needs no second lookup. */
+    label?: string;
     position: {
         x: number;
         y: number;

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.