@jgengine/convex 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -34,6 +34,68 @@ At publish, rename this heading to the new version and mirror the entries into
 
 ### Fixed
 
+## 0.17.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.17.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.14.0`; `@jgengine/github` is `0.4.0`.
+- **A deleted player profile stays deleted.** When a game persists players (`save.scope` includes `player`), hydrating a member with no `jgPlayerProfiles` row no longer falls back to the copy of their state kept on the server row — that copy was resurrected and then written back as authoritative, so a world reset that cleared profiles but not servers silently restored every player's old balance. A game whose save scope excludes players (`"none"`, `"chunks"`) is unchanged: the server-row copy is still their state. If you seed members onto a server row without going through `joinServer`, write their profile row too.
+- **`slotsPerServer` is capped at 256** (`JG_MAX_MEMBERS_PER_SERVER`). `createGameServerFunctions` now throws at wiring time on a larger value instead of accepting it and failing at the write that overflows the document. One server is one Convex document holding the world row, the roster, and every member's session state; a bigger number was never a bigger world. Shard across servers, or move world state into `jgWorldChunks`.
+- **The tick cron only sweeps games that declare `loop.onTick`.** A game with no tick hook used to pay a full hydrate plus a full persist every second per running server, for a snapshot `runtime.tick` returned unchanged; it now costs nothing while idle. If you relied on the tick cron to autosave a hookless game, the 60s `flushDirtyServers` cron and the `flushSave` mutation still do it.
+
+### Changed
+
+- **Walking NPCs now stop at the geometry that stops the player.** `wander`, `patrol`, and `ctx.scene.entity.moveToward` consulted no obstacles at all, so a pedestrian walked through the building the player cannot enter. All three now slide their step against the scene's blocking physical colliders — the same query `stepPlayerMovement` reads. A patrol's path state still advances on its own clock (an authored route is not rewound by contact), but the entity can no longer end a tick inside a solid. Pass `avoidSolids: false` to `moveToward` for a mover meant to ignore the world (a flier, a camera rig).
+- **`@jgengine/assets` verify fails a model source that contributes no index entries.** A model pack that has never been pulled is a pin nothing has ever checked — that is how a Street Pack archive sat in the catalogue titled "Downtown City MegaKit". Record why a pack is not pulled in the new `AssetSource.unpulled` string; materials and sprites pull on demand and are exempt.
+- **`persistServerSnapshot` returns `boolean` and skips a write that would change nothing.** Every subscriber of a query that read a server row re-receives the whole result when that document changes, so an unconditional write on the 1 Hz tick re-pushed the entire world to every client once a second whether or not anything moved. `ServerPersistPlan` gains `changed` (`serverState` / `sessionPlayers` / `revision` / `any`) for hosts that write field-by-field.
+- **`sessionPlayers` is merged over the stored map, not rebuilt from the snapshot**, and entries for non-members are pruned. This is what makes a partially hydrated snapshot safe to persist.
+- **`tickActiveServers` is bounded** to `maxServersPerTick` (default 32) servers per transaction, oldest tick anchor first, instead of pulling every running server of every game into one transaction. `flushDirtyServers` is bounded the same way.
+
+### Added
+
+- **`solidObstaclesNear` / `resolveWalkerStep` (`@jgengine/core/movement/solidObstacles`)** — the engine's single answer to "what is solid here", now shared rather than re-derived per consumer. `solidObstaclesNear(ctx, position, reachX, reachZ)` returns the blocking physical colliders near a point through a bounded `inBox` broadphase; `resolveWalkerStep(ctx, position, stepX, stepZ)` slides a horizontal step against them with the player's axis-separated sliding. Reach for these instead of deriving obstacles from a game catalog's own solidity flags.
+- **Bounded hydration and a client chunk read** — `loadServerSnapshot(ctx, server, runtime, { players, chunkKeys })` hydrates only the members and chunks a mutation will touch instead of a document read per member plus one per chunk, and the generated `getChunks` query lets a client read chunk state by key (capped at `MAX_CHUNKS_PER_QUERY`). Chunks were the documented escape hatch for world state too large for one row, but reads were unbounded and clients could not see them at all, so moving geometry there made things worse. `getServerMeta` returns lobby state (status, member count, revision) without the world payload.
+- **`@jgengine/core/runtime/worldChunks`** — `chunkKeyAt` / `chunkCoordAt` / `chunkKeyOf` / `parseChunkKey` / `chunkKeysInRadius` at a declared cell size, plus `setChunk` / `updateChunk` / `deleteChunk`, which mark the key dirty so the host actually persists it. `chunkKey` was an opaque game-chosen string and the engine never wrote `dirty.chunks`, so every game reimplemented the coordinate mapping and a game that forgot to push a key silently never saved that chunk.
+- **Placed objects cull to `replication.aoiRadius`.** `objects` is the one large spatial replicated set and had no projector, so a world with a few thousand placements sent all of them to every viewer. It now joins the same area-of-interest policy as `entities` and `stats`. Unset `aoiRadius` still replicates everything.
+- **`createGameServerFunctions({ matchmaking: "singleton" })`** — one shared world per game: auto-match always targets the existing world and a join past capacity fails loudly, instead of quietly creating a second world the player would be alone in. `joinServer` also reconciles a stored `slotsPerServer`/`save` that has drifted from the host options, which previously made raising the option a no-op on worlds that already existed. `selectJoinTarget` (`@jgengine/core/runtime/hostPolicy`) is the pure decision behind it.
+- **`GameRuntime.hasTick`** reports whether a runtime declares `loop.onTick`, so any host's scheduler can skip a server whose tick is a no-op by construction.
+
+### Removed
+
+- **Asset source `quaternius-downtown-city`.** It was titled "Downtown City MegaKit" but pinned at the Street Pack archive, which ships Blends/FBX/OBJ only — a pull found no models. Nothing referenced it.
+
+## 0.16.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.16.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.13.0`; `@jgengine/github` is `0.3.0`.
+- **Placed objects now replicate.** `objects` joined the always-on baseline snapshot modules, so `ctx.hydrate` replaces the client's placed object set with the host's, the way `entities` already did. A game whose peers all run the same authored placement is unaffected; a game that places props on the client only, after hydrate, must move that placement to the host or keep it out of `ctx.scene.object`.
+
+### Changed
+
+- **`GeneratedBuilding`'s `kit` prop is now the `BuildingKit`**; the per-part React escape hatch it used to name moved to `partRenderer`, so `kit` means the same thing on `GeneratedBuilding` and `InstancedBuildings`. Rename the prop if you passed a `BuildingKitRenderer`.
+
+### Added
+
+- **`modelLoadFallbacks()` from `@jgengine/shell/render/modelLoad`** lists every model the shared loader diagnosed as broken and replaced with a magenta placeholder. A placeholder was only ever a console warning, so a shipped game could render one in its starting area and nobody found out until someone looked at a screenshot; a capture host or smoke test can now require the list to be empty. `clearModelLoadFallbacks()` resets it between runs.
+- **`worldHealthBars.occlude` / `WorldHealthBars`+`WorldNameplates` `occlude` prop.** World bars and nameplates are a screen-space overlay drawn outside the WebGL depth buffer, so nothing in the scene can hide them and an enemy's health bar reads straight through the building it stands behind. Set `occlude: true` to drop a bar when world geometry blocks the line from the player to the entity. Default `false` preserves the always-visible behaviour every shipped game currently relies on.
+
+- **`DustField` + `WeatherLayer` mode `"dust"` (`@jgengine/shell/weather`) — wind-borne particulate.** `WeatherLayer` could only do `clear`/`rain`/`snow`/`mixed`, so an arid, volcanic, ashen, or blown-out world had no way to put anything in the air. Dust drifts on horizontal wind with a slow vertical bob rather than falling; `groundBias` packs density toward the surface, motes fade near the top of the volume so recycled ones do not pop against the sky, and faster motes ride higher. Set `dustAlways` to keep it in the air alongside rain or snow instead of replacing them. Defaults `DEFAULT_DUST_COUNT`/`DEFAULT_DUST_DENSITY` sit beside the rain and snow pair.
+
+- **Authored `city` volumes render their near-LOD facades with a `BuildingKit`.** `CityRules.buildingKit` names a kit; a game registers the bound art with `registerBuildingKit(kit)` from `@jgengine/shell/structures/buildingKitRegistry` and the scene document carries only the name, so a city stays portable and free of model paths. Unset or unknown names keep the palette blocks. This puts the whole `city` primitive — not just the `building()` feature — on the kit path.
+- **`BuildingKit` from `@jgengine/core/world/buildingKit`** binds a generated building's facade part slots to real models, so procedural buildings render as an instanced asset kit instead of untextured blocks. `defineBuildingKit({ parts: { wall: ["Wall_A.glb", …] } })` maps a part kind — or a `${facade}.${kind}` slot — to ordered variants that `kit.variant` indexes, with `fit`/`offset`/`rotation`/`scale`/`tint`/`autoOrient` per variant. Kinds a kit leaves unbound keep rendering the palette block, so a partial kit is a valid kit, and `omit` drops a kind entirely. Pass one through `building({ kit })` or straight to `InstancedBuildings`; `buildingKitVariantCounts(kit)` feeds `generateBuilding` so its seeded picks span exactly the models the kit binds.
+- **`generateBuilding`, `generateBuildingDistrict`, and `createBuildingConfig` are now documented public API** (`@jgengine/core/world/buildings`) and appear in `capabilities.md` under `building-generator`.
+- **`capture.views` on `defineGame`** — named framings (`GameCaptureView`: `look`, `lookFrom`, `spawn`, `state`, `run`, `settleMs`) that `shoot <game> --view <name>` and `drive --view <name>` replay exactly, so a before/after pair is the same view by construction. `shoot <game> --list-views` prints what a game declares; an unknown name fails listing them, and any explicit capture flag still wins over the view's value.
+- **`modelLoadIdleMs()` from `@jgengine/shell/render/modelLoad`** reports how long the shared GLB loader has been idle (`0` while a model is in flight). Capture hosts wait on it instead of guessing a settle delay, so an establishing shot no longer races streaming models.
+- **Per-instance state on placed objects** — `SceneObject.state` (opaque `Record`), set through `ctx.scene.object.setState`/`patchState`/`place({ state })`. It survives move/rotate/setVisual, replicates and saves with the object, and round-trips as `RuntimeObjectRow.flags` via `toRuntimeObjectRow`/`fromRuntimeObjectRow` (`@jgengine/core/multiplayer`). A chest's locked flag or a machine's fill level no longer needs a game-owned map keyed by `instanceId`.
+- **`slotInventory` is a working feature** — `ctx.scene.object.slots` gives objects whose catalog entry declares it real per-instance container contents: `layout`/`state`/`count`, `put`/`take`, and `transferIn`/`transferOut` between a player inventory and the object, all validated against the declared slot count, `accepts` kind filter, and stack limits, with neither side mutated on a rejection. Contents live on `SceneObject.slots`, so they replicate and save with the placement.
+- **`loadServerSnapshot` and `persistServerSnapshot` are public** (`@jgengine/convex/server`), and `createGameServerFunctions` also returns `helpers` (`loadSnapshot`, `applyCommand`, `persistSnapshot`, `runCommand`) bound to the same runtimes and auth mode. A host mutation can now pair snapshot work with its own table writes in one transaction; the registered `runCommand` mutation delegates to `helpers.runCommand`, so there is one implementation.
+
+### Fixed
+
+- **Open storefronts are no longer holes through the building.** `generateBuilding` emitted an open ground-floor store as a lone `storefront` panel with no wall behind it, while every upper-floor window was correctly backed by one. Storefront and window materials render at 0.56 opacity and a generated building is a hollow shell, so those bays let you see straight through the building to the world beyond — and open stores only land on the street-facing facade, so a row of shops along a road was the worst case. The bay now emits its wall first, exactly as an upper floor does.
+- **`joinServer`, `flushSave`, `flushDirtyServers`, and the `auto` autosave can write player profiles again.** All four cleared the snapshot's dirty set before handing it to the persist plan, which gates profile writes on exactly that set — so the functions named "flush" flushed the server row and chunks only, and an `onNewPlayer` grant (starting money, starting items) never reached `jgPlayerProfiles`. `joinServer` now persists the snapshot it just marked; the flush paths mark every player dirty first, since hydrating from storage resets the dirty set. `planServerPersist` also clears `dirtyAt` once everything outstanding is written, so a successful flush stops autosave from re-firing forever, and a profile patch no longer clobbers a host-maintained `dirtyAt`.
+
 ## 0.15.0
 
 ### Migrate

package/README.md

@@ -42,6 +42,19 @@ export const { joinServer, leaveServer, runCommand, flushSave, getServer, getPla
 
 No game-specific code lives there — any JGengine game can point at the same deployment. Games without a registered `GameRuntime` fall back to a no-save runtime that only understands `engine.ping`; pass `createGameServerFunctions({ runtimes: [createGameRuntime({ gameId, commands, loop, save })] })` to make `runCommand`/tick/save actually do something.
 
+The same factory also returns `helpers` — `loadSnapshot`, `applyCommand`, `persistSnapshot`, `runCommand` — bound to the same runtimes and auth mode, for a host mutation that must pair snapshot work with its own table writes in one transaction. `loadServerSnapshot` / `persistServerSnapshot` are exported standalone for the same reason:
+
+```ts
+export const buyWithReceipt = mutation({
+  args: { serverId: v.id("jgGameServers"), input: v.any() },
+  handler: async (ctx, args) => {
+    const outcome = await helpers.runCommand(ctx, { ...args, command: "shop.buy" });
+    if (outcome.ok) await ctx.db.insert("receipts", { serverId: args.serverId, at: Date.now() });
+    return outcome;
+  },
+});
+```
+
 Every factory defaults to `auth: "anonymous"` — the client's `externalId` is trusted as claimed, fine for local dev but spoofable. Pass `{ auth: "required" }` to every factory for production; the resolved actor becomes `ctx.auth.getUserIdentity()`'s `subject`, and `externalId` is only cross-checked against it, never trusted alone.
 
 See `examples/convex-host` for the reference thin consumer (`bunx convex dev` codegens `convex/_generated/` and prints the dev URL). Point any game that declares `multiplayer: convexPresence({ topology: "shared" })` (or `convex({ topology: "shared", authority: "server" })` for a shared sim) at the same deployment. No Convex Cloud account is needed — `examples/convex-host/docker-compose.yml` runs the open-source backend anywhere Docker runs, with `CONVEX_SELF_HOSTED_URL`/`CONVEX_SELF_HOSTED_ADMIN_KEY` pointing the same CLI at it.

package/dist/server.d.ts

@@ -1,12 +1,15 @@
-import type { Auth, DataModelFromSchemaDefinition, GenericMutationCtx } from "convex/server";
+import type { Auth, DataModelFromSchemaDefinition, DocumentByName, GenericMutationCtx } from "convex/server";
 import type { GenericId } from "convex/values";
 import type { ChatMessage } from "@jgengine/core/game/chat";
 import type { ChatSendOutcome } from "@jgengine/core/multiplayer/chatContract";
 import { type PoseSyncRules } from "@jgengine/core/multiplayer/presenceModel";
 import type { GameRuntime } from "@jgengine/core/runtime/gameRuntime";
 import type { LeaderboardIncrement } from "@jgengine/core/runtime/hostPersistence";
+import { type MatchmakingMode } from "@jgengine/core/runtime/hostPolicy";
+import type { SaveConfig } from "@jgengine/core/runtime/save";
+import type { GameRuntimeSnapshot } from "@jgengine/core/runtime/snapshot";
 /** @internal Re-export shared host-policy pure helpers so existing convex imports keep working. */
-export { canJoinPrivateServer, isListablePublicly, } from "@jgengine/core/runtime/hostPolicy";
+export { JG_MAX_MEMBERS_PER_SERVER, canJoinPrivateServer, isListablePublicly, validateSlotsPerServer, type MatchmakingMode, } from "@jgengine/core/runtime/hostPolicy";
 /** @internal */
 export declare function jgengineTables(): {
     jgGameServers: import("convex/server").TableDefinition<import("convex/values").VObject<{
@@ -60,6 +63,7 @@ export declare function jgengineTables(): {
     }, "required", "createdAt" | "dirtyAt" | "gameId" | "joinCode" | "lastSavedAt" | "memberUserIds" | "mode" | "modeConfig" | "revision" | "save" | "save.auto" | "save.scope" | "serverState" | "sessionPlayers" | "slotsPerServer" | "status" | "tickAnchorMs" | "updatedAt" | "visibility" | `modeConfig.${string}` | `serverState.${string}` | `sessionPlayers.${string}`>, {
         by_dirty: ["dirtyAt", "_creationTime"];
         by_game_and_status: ["gameId", "status", "_creationTime"];
+        by_game_status_tick: ["gameId", "status", "tickAnchorMs", "_creationTime"];
         by_status: ["status", "_creationTime"];
     }, {}, {}>;
     jgPlayerProfiles: import("convex/server").TableDefinition<import("convex/values").VObject<{
@@ -252,6 +256,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     }, "required", "createdAt" | "dirtyAt" | "gameId" | "joinCode" | "lastSavedAt" | "memberUserIds" | "mode" | "modeConfig" | "revision" | "save" | "save.auto" | "save.scope" | "serverState" | "sessionPlayers" | "slotsPerServer" | "status" | "tickAnchorMs" | "updatedAt" | "visibility" | `modeConfig.${string}` | `serverState.${string}` | `sessionPlayers.${string}`>, {
         by_dirty: ["dirtyAt", "_creationTime"];
         by_game_and_status: ["gameId", "status", "_creationTime"];
+        by_game_status_tick: ["gameId", "status", "tickAnchorMs", "_creationTime"];
         by_status: ["status", "_creationTime"];
     }, {}, {}>;
     jgPlayerProfiles: import("convex/server").TableDefinition<import("convex/values").VObject<{
@@ -360,8 +365,13 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         by_server_channel: ["serverId", "channelId", "_creationTime"];
     }, {}, {}>;
 }, true>;
-type JGDataModel = DataModelFromSchemaDefinition<typeof schemaForTypes>;
-type JGMutationCtx = GenericMutationCtx<JGDataModel>;
+/** Data model of the {@link jgengineTables} schema — the shape a host's own Convex ctx must satisfy to
+ * call the exported persistence helpers. */
+export type JGDataModel = DataModelFromSchemaDefinition<typeof schemaForTypes>;
+/** Mutation ctx accepted by {@link loadServerSnapshot} / {@link persistServerSnapshot}. */
+export type JGMutationCtx = GenericMutationCtx<JGDataModel>;
+/** A `jgGameServers` row — the server handle the persistence helpers load from and write back to. */
+export type ServerDoc = DocumentByName<JGDataModel, "jgGameServers">;
 export type JgAuthMode = "anonymous" | "required";
 export declare const DEFAULT_CONVEX_POSE_RULES: PoseSyncRules;
 /** Resolve the acting user id under a {@link JgAuthMode}: the Convex identity when signed in (rejecting a mismatched claim), the claimed external id under `"anonymous"`, else `null`.
@@ -370,14 +380,112 @@ export declare const DEFAULT_CONVEX_POSE_RULES: PoseSyncRules;
 export declare function resolveActor(ctx: {
     auth: Auth;
 }, claimedExternalId: string | undefined, mode: JgAuthMode): Promise<string | null>;
+/**
+ * How much of a server to hydrate. Both fields default to "everything", which is a document 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: a command that only moves the actor's own
+ * state needs `players: [actorUserId]`, and a spatial edit needs only the chunk keys it writes
+ * (`chunkKeysInRadius` from `@jgengine/core/runtime/worldChunks`).
+ *
+ * Persisting a narrowed snapshot is safe: the plan merges session state over the stored map and
+ * writes only dirty profiles and dirty chunks, so members and chunks left unhydrated are untouched.
+ */
+export type LoadSnapshotScope = {
+    /** 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[];
+};
+/**
+ * Hydrate a server's `GameRuntimeSnapshot` from its row, its members' profiles, and its world chunks.
+ * Reach for it when writing your own mutation that must read runtime state before touching host tables.
+ * Pass a {@link LoadSnapshotScope} to bound the read instead of loading the whole world.
+ * @capability convex-load-server-snapshot read a hosted server's runtime snapshot inside a host-written Convex mutation
+ */
+export declare function loadServerSnapshot(ctx: JGMutationCtx, server: ServerDoc, runtime: GameRuntime, scope?: LoadSnapshotScope): Promise<GameRuntimeSnapshot>;
 /** @internal */
 export declare function applyLeaderboardIncrements(ctx: JGMutationCtx, gameId: string, entries: LeaderboardIncrement[]): Promise<void>;
+/**
+ * Write a snapshot back: server row, dirty player profiles, dirty chunks, and drained leaderboard
+ * increments, all under `save`. Pair it with your own table writes to keep both in one transaction.
+ *
+ * A persist that would change nothing writes nothing and returns `false`. That matters beyond write
+ * cost: every subscriber of a query that read this row re-receives the whole result when the document
+ * changes, so an unconditional write on a 1 Hz tick re-pushes the entire world to every client once a
+ * second whether or not anything moved.
+ * @capability convex-persist-server-snapshot write runtime state and host tables in one Convex transaction
+ */
+export declare function persistServerSnapshot(ctx: JGMutationCtx, server: ServerDoc, snapshot: GameRuntimeSnapshot, save: SaveConfig): Promise<boolean>;
 export declare const JG_RUNTIME_TICK_MS = 1000;
-/** @internal */
+/** Outcome of a runtime command: applied, or refused with a reason (unknown server, non-member, validation, revision conflict). */
+export type RunCommandOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper. */
+export type RunCommandArgs = {
+    serverId: string;
+    command: string;
+    input: unknown;
+    externalId?: string;
+};
+/** A server resolved for runtime work: its row, its registered runtime, and its hydrated snapshot. */
+export type LoadedServerSnapshot = {
+    server: ServerDoc;
+    runtime: GameRuntime;
+    snapshot: GameRuntimeSnapshot;
+};
+/**
+ * The plain-function half of {@link createGameServerFunctions}, bound to the same runtime registry and
+ * auth mode as its mutations. Reach for it when a host mutation must pair snapshot work with its own
+ * table writes in one transaction, which a pre-registered mutation cannot do.
+ */
+export type GameServerHelpers = {
+    loadSnapshot: (ctx: JGMutationCtx, serverId: string, scope?: LoadSnapshotScope) => Promise<LoadedServerSnapshot | null>;
+    applyCommand: (args: {
+        gameId: string;
+        loadedRevision: number;
+        currentRevision: number;
+        snapshot: GameRuntimeSnapshot;
+        actorUserId: string;
+        command: string;
+        input: unknown;
+    }) => {
+        ok: true;
+        snapshot: GameRuntimeSnapshot;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    persistSnapshot: (ctx: JGMutationCtx, server: ServerDoc, snapshot: GameRuntimeSnapshot, save?: SaveConfig) => Promise<boolean>;
+    runCommand: (ctx: JGMutationCtx, args: RunCommandArgs) => Promise<RunCommandOutcome>;
+};
+/** How many running servers one `tickActiveServers` transaction may hydrate, tick, and persist. */
+export declare const DEFAULT_MAX_SERVERS_PER_TICK = 32;
+/** How many chunk rows one `getChunks` call may return. */
+export declare const MAX_CHUNKS_PER_QUERY = 64;
+/**
+ * Build the hosted-server Convex functions for a set of game runtimes.
+ *
+ * **Supported world size.** One server is one Convex document holding the world row, the member
+ * roster, and every member's session state, and the host rewrites that document whenever the world
+ * changes. `slotsPerServer` is therefore capped at {@link JG_MAX_MEMBERS_PER_SERVER} (256) and a
+ * larger value throws here, at wiring time, rather than at the write that overflows the document.
+ * World geometry that outgrows one row belongs in `jgWorldChunks`, hydrated by key
+ * ({@link LoadSnapshotScope}) and read by clients through `getChunks` — not in `serverState`.
+ *
+ * `matchmaking: "singleton"` makes auto-match target one shared world per game: a join past capacity
+ * fails loudly instead of quietly starting a second world the player would be alone in.
+ * @internal
+ */
 export declare function createGameServerFunctions(options?: {
     runtimes?: GameRuntime[];
     auth?: JgAuthMode;
     slotsPerServer?: number;
+    matchmaking?: MatchmakingMode;
+    maxServersPerTick?: number;
     allowedFeedActions?: readonly string[];
 }): {
     joinServer: import("convex/server").RegisteredMutation<"public", {
@@ -401,12 +509,7 @@ export declare function createGameServerFunctions(options?: {
         externalId?: string | undefined;
         input: any;
         serverId: GenericId<"jgGameServers">;
-    }, Promise<{
-        ok: false;
-        reason: string;
-    } | {
-        ok: true;
-    }>>;
+    }, Promise<RunCommandOutcome>>;
     flushSave: import("convex/server").RegisteredMutation<"public", {
         externalId?: string | undefined;
         serverId: GenericId<"jgGameServers">;
@@ -432,6 +535,28 @@ export declare function createGameServerFunctions(options?: {
         };
         updatedAt: number;
     } | null>>;
+    getServerMeta: import("convex/server").RegisteredQuery<"public", {
+        externalId?: string | undefined;
+        serverId: GenericId<"jgGameServers">;
+    }, Promise<{
+        _id: GenericId<"jgGameServers">;
+        gameId: string;
+        status: "closed" | "open" | "running";
+        mode: string | undefined;
+        memberCount: number;
+        slotsPerServer: number;
+        revision: number;
+        updatedAt: number;
+    } | null>>;
+    getChunks: import("convex/server").RegisteredQuery<"public", {
+        chunkKeys: string[];
+        externalId?: string | undefined;
+        serverId: GenericId<"jgGameServers">;
+    }, Promise<{
+        chunkKey: string;
+        snapshot: unknown;
+        updatedAt: number;
+    }[]>>;
     getPlayerProfile: import("convex/server").RegisteredQuery<"public", {
         externalId?: string | undefined;
         gameId: string;
@@ -472,6 +597,7 @@ export declare function createGameServerFunctions(options?: {
     flushDirtyServers: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
         saved: number;
     }>>;
+    helpers: GameServerHelpers;
 };
 /** @internal */
 export declare function createLeaderboardFunctions(options?: {

package/dist/server.js

@@ -3,12 +3,12 @@ import { ConvexError, v } from "convex/values";
 import { createFeedWriteGate, validateFeedWrite, } from "@jgengine/core/multiplayer/feedWriteGate";
 import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, spawnPresenceState, } from "@jgengine/core/multiplayer/presenceModel";
 import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
-import { buildHydratePlayers, planServerPersist, shouldAutoSave, trimFeedEntries } from "@jgengine/core/runtime/hostPersistence";
-import { isAutoJoinCandidate, isListablePublicly, isPrivateJoinBlocked, isServerFull, isServerMember, statusAfterLeave, withJoinedMember, withoutMember, } from "@jgengine/core/runtime/hostPolicy";
-import { clearDirtyFlags, createEmptyServerRow } from "@jgengine/core/runtime/snapshot";
+import { buildHydratePlayers, planServerPersist, shouldAutoSave, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
+import { JG_MAX_MEMBERS_PER_SERVER, isListablePublicly, isPrivateJoinBlocked, isServerFull, isServerMember, selectJoinTarget, statusAfterLeave, validateSlotsPerServer, withJoinedMember, withoutMember, } from "@jgengine/core/runtime/hostPolicy";
+import { createEmptyServerRow, markAllPlayersDirty } from "@jgengine/core/runtime/snapshot";
 import { applyCommandWithOcc, commitIfRevisionMatch } from "./occ.js";
 /** @internal Re-export shared host-policy pure helpers so existing convex imports keep working. */
-export { canJoinPrivateServer, isListablePublicly, } from "@jgengine/core/runtime/hostPolicy";
+export { JG_MAX_MEMBERS_PER_SERVER, canJoinPrivateServer, isListablePublicly, validateSlotsPerServer, } from "@jgengine/core/runtime/hostPolicy";
 const saveConfigValidator = v.union(v.literal("none"), v.object({
     auto: v.string(),
     scope: v.union(v.literal("player"), v.literal("chunks"), v.literal("player+chunks")),
@@ -37,6 +37,7 @@ export function jgengineTables() {
         })
             .index("by_game_and_status", ["gameId", "status"])
             .index("by_status", ["status"])
+            .index("by_game_status_tick", ["gameId", "status", "tickAnchorMs"])
             .index("by_dirty", ["dirtyAt"]),
         jgPlayerProfiles: defineTable({
             userId: v.string(),
@@ -218,9 +219,19 @@ function serverDocToRecord(server) {
         updatedAt: server.updatedAt,
     };
 }
-async function loadServerSnapshot(ctx, server, runtime) {
+/**
+ * Hydrate a server's `GameRuntimeSnapshot` from its row, its members' profiles, and its world chunks.
+ * Reach for it when writing your own mutation that must read runtime state before touching host tables.
+ * Pass a {@link LoadSnapshotScope} to bound the read instead of loading the whole world.
+ * @capability convex-load-server-snapshot read a hosted server's runtime snapshot inside a host-written Convex mutation
+ */
+export async function loadServerSnapshot(ctx, server, runtime, scope) {
     const profiles = {};
-    for (const userId of server.memberUserIds) {
+    const memberIds = new Set(server.memberUserIds);
+    const hydrateUserIds = scope?.players === undefined
+        ? server.memberUserIds
+        : scope.players.filter((userId) => memberIds.has(userId));
+    for (const userId of hydrateUserIds) {
         const profile = await ctx.db
             .query("jgPlayerProfiles")
             .withIndex("by_user_and_game", (q) => q.eq("userId", userId).eq("gameId", server.gameId))
@@ -235,14 +246,25 @@ async function loadServerSnapshot(ctx, server, runtime) {
             }
             : null;
     }
-    const playersByUserId = buildHydratePlayers(serverDocToRecord(server), profiles);
-    const chunks = await ctx.db
-        .query("jgWorldChunks")
-        .withIndex("by_server", (q) => q.eq("serverId", server._id))
-        .collect();
+    const playersByUserId = buildHydratePlayers(serverDocToRecord(server), profiles, hydrateUserIds);
     const chunksByKey = {};
-    for (const chunk of chunks) {
-        chunksByKey[chunk.chunkKey] = chunk.snapshot;
+    if (scope?.chunkKeys === undefined) {
+        const chunks = await ctx.db
+            .query("jgWorldChunks")
+            .withIndex("by_server", (q) => q.eq("serverId", server._id))
+            .collect();
+        for (const chunk of chunks)
+            chunksByKey[chunk.chunkKey] = chunk.snapshot;
+    }
+    else {
+        for (const chunkKey of new Set(scope.chunkKeys)) {
+            const chunk = await ctx.db
+                .query("jgWorldChunks")
+                .withIndex("by_server_and_chunk", (q) => q.eq("serverId", server._id).eq("chunkKey", chunkKey))
+                .unique();
+            if (chunk)
+                chunksByKey[chunk.chunkKey] = chunk.snapshot;
+        }
     }
     return runtime.hydrate({
         gameId: server.gameId,
@@ -279,9 +301,21 @@ export async function applyLeaderboardIncrements(ctx, gameId, entries) {
         }
     }
 }
-async function persistServerSnapshot(ctx, server, snapshot, save) {
+/**
+ * Write a snapshot back: server row, dirty player profiles, dirty chunks, and drained leaderboard
+ * increments, all under `save`. Pair it with your own table writes to keep both in one transaction.
+ *
+ * A persist that would change nothing writes nothing and returns `false`. That matters beyond write
+ * cost: every subscriber of a query that read this row re-receives the whole result when the document
+ * changes, so an unconditional write on a 1 Hz tick re-pushes the entire world to every client once a
+ * second whether or not anything moved.
+ * @capability convex-persist-server-snapshot write runtime state and host tables in one Convex transaction
+ */
+export async function persistServerSnapshot(ctx, server, snapshot, save) {
     const now = Date.now();
     const plan = planServerPersist(serverDocToRecord(server), snapshot, save, now);
+    if (!plan.changed.any)
+        return false;
     if (plan.leaderboard.length > 0) {
         await applyLeaderboardIncrements(ctx, server.gameId, plan.leaderboard);
     }
@@ -293,7 +327,6 @@ async function persistServerSnapshot(ctx, server, snapshot, save) {
         const profilePatch = {
             playerState: profile.playerState,
             revision: profile.revision,
-            dirtyAt: undefined,
             updatedAt: profile.updatedAt,
         };
         if (existing) {
@@ -338,29 +371,56 @@ async function persistServerSnapshot(ctx, server, snapshot, save) {
             await ctx.db.delete(existing._id);
     }
     await ctx.db.patch(server._id, {
-        serverState: plan.server.serverState,
-        sessionPlayers: plan.server.sessionPlayers,
+        ...(plan.changed.serverState ? { serverState: plan.server.serverState } : {}),
+        ...(plan.changed.sessionPlayers ? { sessionPlayers: plan.server.sessionPlayers } : {}),
         revision: plan.server.revision,
         dirtyAt: plan.server.dirtyAt,
         updatedAt: plan.server.updatedAt,
         lastSavedAt: plan.server.lastSavedAt,
     });
+    return true;
 }
-async function flushServerIfDue(ctx, server, now, runtime) {
+/** Autosave a server whose `save.auto` interval has elapsed, reusing an already-hydrated snapshot. */
+async function flushServerIfDue(ctx, server, now, runtime, loaded) {
     if (!shouldAutoSave(server.save, server.dirtyAt, server.lastSavedAt, now)) {
         return false;
     }
-    const snapshot = await loadServerSnapshot(ctx, server, runtime);
-    await persistServerSnapshot(ctx, server, clearDirtyFlags(snapshot), server.save);
+    const snapshot = loaded ?? (await loadServerSnapshot(ctx, server, runtime));
+    await persistServerSnapshot(ctx, server, markAllPlayersDirty(snapshot), server.save);
     return true;
 }
 export const JG_RUNTIME_TICK_MS = 1_000;
-/** @internal */
+/** How many running servers one `tickActiveServers` transaction may hydrate, tick, and persist. */
+export const DEFAULT_MAX_SERVERS_PER_TICK = 32;
+/** How many chunk rows one `getChunks` call may return. */
+export const MAX_CHUNKS_PER_QUERY = 64;
+/**
+ * Build the hosted-server Convex functions for a set of game runtimes.
+ *
+ * **Supported world size.** One server is one Convex document holding the world row, the member
+ * roster, and every member's session state, and the host rewrites that document whenever the world
+ * changes. `slotsPerServer` is therefore capped at {@link JG_MAX_MEMBERS_PER_SERVER} (256) and a
+ * larger value throws here, at wiring time, rather than at the write that overflows the document.
+ * World geometry that outgrows one row belongs in `jgWorldChunks`, hydrated by key
+ * ({@link LoadSnapshotScope}) and read by clients through `getChunks` — not in `serverState`.
+ *
+ * `matchmaking: "singleton"` makes auto-match target one shared world per game: a join past capacity
+ * fails loudly instead of quietly starting a second world the player would be alone in.
+ * @internal
+ */
 export function createGameServerFunctions(options) {
     const mode = options?.auth ?? "required";
     const hostSlotsPerServer = options?.slotsPerServer ?? 16;
+    const slotsCheck = validateSlotsPerServer(hostSlotsPerServer);
+    if (!slotsCheck.ok)
+        throw new Error(slotsCheck.reason);
+    const matchmaking = options?.matchmaking ?? "auto";
+    const maxServersPerTick = Math.max(1, options?.maxServersPerTick ?? DEFAULT_MAX_SERVERS_PER_TICK);
     const feedWriteGate = createFeedWriteGate(options?.allowedFeedActions ?? []);
     const registry = buildRuntimeRegistry(options?.runtimes);
+    const tickableGameIds = (options?.runtimes ?? [])
+        .filter((runtime) => runtime.hasTick)
+        .map((runtime) => runtime.gameId);
     const joinServer = mutation({
         args: {
             gameId: v.string(),
@@ -388,6 +448,7 @@ export function createGameServerFunctions(options) {
             if (server && server.gameId !== args.gameId) {
                 throw new ConvexError("Server belongs to a different game");
             }
+            let mayCreate = true;
             if (!server) {
                 const joinable = [];
                 for (const status of ["running", "open"]) {
@@ -397,15 +458,21 @@ export function createGameServerFunctions(options) {
                         .collect();
                     joinable.push(...rows);
                 }
-                server =
-                    joinable.find((row) => isAutoJoinCandidate({
-                        memberUserIds: row.memberUserIds,
-                        slotsPerServer: row.slotsPerServer,
-                        visibility: row.visibility,
-                        userId: actorUserId,
-                    })) ?? null;
+                // Two concurrent first-joins can both see an empty list here and both insert. Convex's OCC
+                // resolves it — the loser's read set is invalidated and its mutation retries against the
+                // winner's row — so the engine adds no lock. A `HostPersistence` backend without
+                // serializable-snapshot retry must supply that guarantee itself.
+                const target = selectJoinTarget(joinable, {
+                    userId: actorUserId,
+                    mode: matchmaking,
+                    slotsPerServer,
+                });
+                if (target.kind === "refuse")
+                    throw new ConvexError(target.reason);
+                server = target.kind === "join" ? target.row : null;
+                mayCreate = target.kind === "create";
             }
-            if (!server) {
+            if (!server && mayCreate) {
                 const serverId = await ctx.db.insert("jgGameServers", {
                     gameId: args.gameId,
                     status: "running",
@@ -427,6 +494,17 @@ export function createGameServerFunctions(options) {
                 if (!server)
                     throw new ConvexError("Failed to create server");
             }
+            if (!server)
+                throw new ConvexError("No joinable server");
+            // Capacity and save policy live in host options, not in the row. Without this a long-lived
+            // world keeps whatever it was created with and raising the host option silently does nothing.
+            if (server.slotsPerServer !== slotsPerServer || JSON.stringify(server.save) !== JSON.stringify(save)) {
+                await ctx.db.patch(server._id, { slotsPerServer, save, updatedAt: now });
+                const reconciled = await ctx.db.get("jgGameServers", server._id);
+                if (!reconciled)
+                    throw new ConvexError("Server missing after reconcile");
+                server = reconciled;
+            }
             if (isServerFull(server.memberUserIds, server.slotsPerServer, actorUserId)) {
                 throw new ConvexError("Server is full");
             }
@@ -456,7 +534,7 @@ export function createGameServerFunctions(options) {
                 throw new ConvexError("Server missing after join");
             let snapshot = await loadServerSnapshot(ctx, refreshed, runtime);
             snapshot = runtime.joinPlayer(snapshot, actorUserId, isNew);
-            await persistServerSnapshot(ctx, refreshed, clearDirtyFlags(snapshot), save);
+            await persistServerSnapshot(ctx, refreshed, snapshot, save);
             return { serverId: refreshed._id, isNew };
         },
     });
@@ -494,17 +572,24 @@ export function createGameServerFunctions(options) {
             return null;
         },
     });
-    const runCommand = mutation({
-        args: {
-            serverId: v.id("jgGameServers"),
-            command: v.string(),
-            input: v.any(),
-            externalId: v.optional(v.string()),
+    const helpers = {
+        async loadSnapshot(ctx, serverId, scope) {
+            const server = await ctx.db.get("jgGameServers", serverId);
+            if (!server)
+                return null;
+            const runtime = resolveRuntime(registry, server.gameId);
+            return { server, runtime, snapshot: await loadServerSnapshot(ctx, server, runtime, scope) };
         },
-        returns: v.union(v.object({ ok: v.literal(true) }), v.object({ ok: v.literal(false), reason: v.string() })),
-        handler: async (ctx, args) => {
+        applyCommand(args) {
+            return applyCommandWithOcc({ ...args, runtime: resolveRuntime(registry, args.gameId) });
+        },
+        persistSnapshot(ctx, server, snapshot, save) {
+            return persistServerSnapshot(ctx, server, snapshot, save ?? server.save);
+        },
+        async runCommand(ctx, args) {
             const actorUserId = await requireActor(ctx, args.externalId, mode);
-            const server = await ctx.db.get("jgGameServers", args.serverId);
+            const serverId = args.serverId;
+            const server = await ctx.db.get("jgGameServers", serverId);
             if (!server) {
                 return { ok: false, reason: "Server not found" };
             }
@@ -526,7 +611,7 @@ export function createGameServerFunctions(options) {
             if (!result.ok) {
                 return result;
             }
-            const latest = await ctx.db.get("jgGameServers", args.serverId);
+            const latest = await ctx.db.get("jgGameServers", serverId);
             if (!latest) {
                 return { ok: false, reason: "Server not found" };
             }
@@ -537,6 +622,16 @@ export function createGameServerFunctions(options) {
             await persistServerSnapshot(ctx, latest, result.snapshot, latest.save);
             return { ok: true };
         },
+    };
+    const runCommand = mutation({
+        args: {
+            serverId: v.id("jgGameServers"),
+            command: v.string(),
+            input: v.any(),
+            externalId: v.optional(v.string()),
+        },
+        returns: v.union(v.object({ ok: v.literal(true) }), v.object({ ok: v.literal(false), reason: v.string() })),
+        handler: (ctx, args) => helpers.runCommand(ctx, args),
     });
     const flushSave = mutation({
         args: {
@@ -551,7 +646,7 @@ export function createGameServerFunctions(options) {
                 return false;
             const runtime = resolveRuntime(registry, server.gameId);
             const snapshot = await loadServerSnapshot(ctx, server, runtime);
-            await persistServerSnapshot(ctx, server, clearDirtyFlags(snapshot), server.save);
+            await persistServerSnapshot(ctx, server, markAllPlayersDirty(snapshot), server.save);
             return true;
         },
     });
@@ -591,6 +686,63 @@ export function createGameServerFunctions(options) {
             };
         }),
     });
+    /**
+     * Lobby-scale view of a server: status, capacity, revision — no world state. Subscribe a menu,
+     * roster, or "is it up" indicator to this instead of `getServer`, whose payload is the whole world.
+     */
+    const getServerMeta = query({
+        args: {
+            serverId: v.id("jgGameServers"),
+            externalId: v.optional(v.string()),
+        },
+        returns: v.union(v.object({
+            _id: v.id("jgGameServers"),
+            gameId: v.string(),
+            status: v.union(v.literal("open"), v.literal("running"), v.literal("closed")),
+            mode: v.optional(v.string()),
+            memberCount: v.number(),
+            slotsPerServer: v.number(),
+            revision: v.number(),
+            updatedAt: v.number(),
+        }), v.null()),
+        handler: (ctx, args) => withMember(ctx, mode, args, null, (server) => ({
+            _id: server._id,
+            gameId: server.gameId,
+            status: server.status,
+            mode: server.mode,
+            memberCount: server.memberUserIds.length,
+            slotsPerServer: server.slotsPerServer,
+            revision: server.revision,
+            updatedAt: server.updatedAt,
+        })),
+    });
+    /**
+     * Read world chunks by key — the client half of the chunk escape hatch. Without it a game that moved
+     * geometry out of `serverState` had no way to show it, because `getServer` returns only the row.
+     * Bounded to {@link MAX_CHUNKS_PER_QUERY} keys; ask for the cells around the viewer
+     * (`chunkKeysInRadius`), not the world.
+     */
+    const getChunks = query({
+        args: {
+            serverId: v.id("jgGameServers"),
+            chunkKeys: v.array(v.string()),
+            externalId: v.optional(v.string()),
+        },
+        returns: v.array(v.object({ chunkKey: v.string(), snapshot: v.any(), updatedAt: v.number() })),
+        handler: (ctx, args) => withMember(ctx, mode, args, [], async (server) => {
+            const keys = [...new Set(args.chunkKeys)].slice(0, MAX_CHUNKS_PER_QUERY);
+            const out = [];
+            for (const chunkKey of keys) {
+                const row = await ctx.db
+                    .query("jgWorldChunks")
+                    .withIndex("by_server_and_chunk", (q) => q.eq("serverId", server._id).eq("chunkKey", chunkKey))
+                    .unique();
+                if (row)
+                    out.push({ chunkKey: row.chunkKey, snapshot: row.snapshot, updatedAt: row.updatedAt });
+            }
+            return out;
+        }),
+    });
     const getPlayerProfile = query({
         args: {
             gameId: v.string(),
@@ -710,31 +862,41 @@ export function createGameServerFunctions(options) {
             }));
         },
     });
+    // Only games that declare `loop.onTick` are swept, and only `maxServersPerTick` of their servers per
+    // transaction, oldest anchor first. A game with no tick hook used to pay a full hydrate + persist per
+    // running server per second to hand `runtime.tick` a snapshot it returned unchanged; now it pays
+    // nothing, and no single transaction can fan out across every world of every game.
     const tickActiveServers = internalMutation({
         args: {},
         handler: async (ctx) => {
             const now = Date.now();
-            const servers = await ctx.db
-                .query("jgGameServers")
-                .withIndex("by_status", (q) => q.eq("status", "running"))
-                .collect();
             let ticked = 0;
             let saved = 0;
-            for (const server of servers) {
-                if (server.memberUserIds.length === 0)
-                    continue;
-                const elapsedMs = now - server.tickAnchorMs;
-                if (elapsedMs < JG_RUNTIME_TICK_MS)
-                    continue;
-                const runtime = resolveRuntime(registry, server.gameId);
-                let snapshot = await loadServerSnapshot(ctx, server, runtime);
-                snapshot = runtime.tick(snapshot, elapsedMs / 1_000);
-                await persistServerSnapshot(ctx, server, snapshot, server.save);
-                await ctx.db.patch(server._id, { tickAnchorMs: now, updatedAt: now });
-                ticked += 1;
-                const refreshed = await ctx.db.get("jgGameServers", server._id);
-                if (refreshed && (await flushServerIfDue(ctx, refreshed, now, runtime))) {
-                    saved += 1;
+            let budget = maxServersPerTick;
+            for (const gameId of tickableGameIds) {
+                if (budget <= 0)
+                    break;
+                const servers = await ctx.db
+                    .query("jgGameServers")
+                    .withIndex("by_game_status_tick", (q) => q.eq("gameId", gameId).eq("status", "running"))
+                    .take(budget);
+                for (const server of servers) {
+                    if (server.memberUserIds.length === 0)
+                        continue;
+                    const elapsedMs = now - server.tickAnchorMs;
+                    if (elapsedMs < JG_RUNTIME_TICK_MS)
+                        continue;
+                    budget -= 1;
+                    const runtime = resolveRuntime(registry, server.gameId);
+                    const loaded = await loadServerSnapshot(ctx, server, runtime);
+                    const snapshot = runtime.tick(loaded, elapsedMs / 1_000);
+                    await persistServerSnapshot(ctx, server, snapshot, server.save);
+                    await ctx.db.patch(server._id, { tickAnchorMs: now });
+                    ticked += 1;
+                    const refreshed = await ctx.db.get("jgGameServers", server._id);
+                    if (refreshed && (await flushServerIfDue(ctx, refreshed, now, runtime, snapshot))) {
+                        saved += 1;
+                    }
                 }
             }
             return { ticked, saved };
@@ -743,18 +905,16 @@ export function createGameServerFunctions(options) {
     const flushDirtyServers = internalMutation({
         args: {},
         handler: async (ctx) => {
-            const now = Date.now();
             const servers = await ctx.db
                 .query("jgGameServers")
                 .withIndex("by_dirty", (q) => q.gt("dirtyAt", 0))
-                .collect();
+                .take(maxServersPerTick);
             let saved = 0;
             for (const server of servers) {
                 const runtime = resolveRuntime(registry, server.gameId);
                 const snapshot = await loadServerSnapshot(ctx, server, runtime);
-                await persistServerSnapshot(ctx, server, clearDirtyFlags(snapshot), server.save);
+                await persistServerSnapshot(ctx, server, markAllPlayersDirty(snapshot), server.save);
                 saved += 1;
-                void now;
             }
             return { saved };
         },
@@ -765,12 +925,15 @@ export function createGameServerFunctions(options) {
         runCommand,
         flushSave,
         getServer,
+        getServerMeta,
+        getChunks,
         getPlayerProfile,
         getFeed,
         pushFeedEntry,
         listOpenServers,
         tickActiveServers,
         flushDirtyServers,
+        helpers,
     };
 }
 const leaderboardScopeValidator = v.union(v.literal("global"), v.literal("server"), v.literal("profile"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/convex",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Convex adapters for JGengine: game transport, presence transport, and backend wiring over @jgengine/core.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,7 +30,7 @@
     "check-types": "bun ../../scripts/check-types-preflight.ts && tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.15.0"
+    "@jgengine/core": "^0.17.0"
   },
   "peerDependencies": {
     "convex": "^1.31.2",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.15.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.17.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -228,7 +228,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.15.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.17.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -264,6 +264,13 @@
 - `CommandValidationError` (type): type CommandValidationError = { reason: string } — ⚠ undocumented
 - `RunCommandResult` (type): type RunCommandResult = | { ok: true; snapshot: GameRuntimeSnapshot } | { ok: false; reason: string } — ⚠ undocumented
 
+## @jgengine/core/runtime/context/objectSlots
+
+- `ObjectSlotRejection` (type): type ObjectSlotRejection = | "unknown-object" | "no-slot-inventory" | "unknown-inventory" | "no-space" | "wrong-kind" | "slot-occupied" | "invalid-slot" | "insufficient" — Why an object slot mutation was refused — the instance, its catalog entry, the player inventory, or the declared `accepts`/capacity.
+- `ObjectSlotResult` (type): type ObjectSlotResult = { status: "ok" } | { status: "rejected"; reason: ObjectSlotRejection } — Outcome of an object slot mutation: applied, or refused with a reason and no state change on either side.
+- `ObjectSlotTransfer` (interface): interface ObjectSlotTransfer — Which player inventory a transfer moves between, and what it moves.
+- `SceneObjectSlots` (interface): interface SceneObjectSlots — Per-instance container contents for placed objects whose catalog entry declares `slotInventory` — the engine side of "install a GPU into a rack", "put an item in a chest". Contents live on `SceneObject.slots`, so they replicate and save with the object rather than needing a game-owned table keyed by `instanceId`, and every mutation is validated against the declared `accepts` and stack limits.
+
 ## @jgengine/core/runtime/gameContext
 
 - `CatalogEntityRole` (type): type CatalogEntityRole = "player" | "enemy" | "hostile" | "npc" | "vehicle" — ⚠ undocumented
@@ -327,7 +334,7 @@
 
 ## @jgengine/core/runtime/gameRuntime
 
-- `GameRuntime` (type): type GameRuntime = { gameId: string; save: SaveConfig; hydrate: (input: HydrateInput) => GameRuntimeSnapshot; runCommand: ( snapshot: GameRuntimeSnapshot, actorUserId: string, commandName: string, input: unknown, ) => ReturnType<typeof runCommand>; tick: (snapshot: GameRuntimeSnapshot, dtSeconds: nu… — ⚠ undocumented
+- `GameRuntime` (type): 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… — ⚠ undocumented
 - `GameRuntimeDefinition` (type): type GameRuntimeDefinition = { gameId: string; save: SaveConfig; commands: Record<string, CommandDef>; loop?: ServerLoopHooks; } — ⚠ undocumented
 - `HydrateInput` (type): type HydrateInput = { gameId: string; serverId: string; serverRow: RuntimeServerRow; playersByUserId: Record<string, RuntimePlayerRow>; chunksByKey: Record<string, RuntimeChunkRow>; revision?: number; } — ⚠ undocumented
 - `RuntimeInitContext` (type): type RuntimeInitContext = { snapshot: GameRuntimeSnapshot; setSnapshot: (snapshot: GameRuntimeSnapshot) => void; } — ⚠ undocumented
@@ -358,21 +365,28 @@
 - `OPEN_SERVER_LISTING_MAX` (const): const OPEN_SERVER_LISTING_MAX: 100 — ⚠ undocumented
 - `PlayerProfileRecord` (type): type PlayerProfileRecord = { userId: string; gameId: string; playerState: RuntimePlayerRow; revision: number; updatedAt: number; } — ⚠ undocumented
 - `ServerListing` (type): type ServerListing = { serverId: string; status: GameServerStatus; memberCount: number; slotsPerServer: number; mode?: string; label?: string; visibility?: SessionVisibility; joinCode?: string; tags?: string[]; updatedAt: number; } — ⚠ undocumented
-- `ServerPersistPlan` (type): type ServerPersistPlan = { server: GameServerRecord; profiles: PlayerProfileRecord[]; chunks: WorldChunkRecord[]; deletedChunks: string[]; leaderboard: LeaderboardIncrement[]; } — ⚠ undocumented
+- `ServerPersistPlan` (type): 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 r… — ⚠ undocumented
 - `SessionAttributes` (type): type SessionAttributes = { label?: string; mode?: string; visibility?: SessionVisibility; joinCode?: string; tags?: string[]; } — ⚠ undocumented
 - `SessionVisibility` (type): type SessionVisibility = "public" | "private" — ⚠ undocumented
 - `ToServerListingOptions` (type): type ToServerListingOptions = { includeJoinCode?: boolean; } — ⚠ undocumented
 - `WorldChunkRecord` (type): type WorldChunkRecord = { serverId: string; chunkKey: string; snapshot: RuntimeChunkRow; updatedAt: number; } — ⚠ undocumented
+- `isSnapshotClean` (function): function isSnapshotClean(snapshot: GameRuntimeSnapshot): boolean — True when a snapshot carries no unwritten mutation — nothing for a persist to do.
 
 ## @jgengine/core/runtime/hostPolicy
 
+- `JG_MAX_MEMBERS_PER_SERVER` (const): const JG_MAX_MEMBERS_PER_SERVER: 256 — Hard ceiling on `slotsPerServer` for a single hosted server row.
+- `JoinCandidate` (type): type JoinCandidate = { memberUserIds: readonly string[]; slotsPerServer: number; visibility?: SessionVisibility | undefined; createdAt: number; } — A row `selectJoinTarget` can choose between — the matchmaking-relevant fields of a server record.
+- `JoinTarget` (type): type JoinTarget<T extends JoinCandidate> = | { kind: "join"; row: T } | { kind: "create" } | { kind: "refuse"; reason: string } — What a join should do with the candidate rows it found.
+- `MatchmakingMode` (type): type MatchmakingMode = "auto" | "singleton" — How auto-match behaves when no `serverId` is supplied.
 - `canJoinPrivateServer` (function): function canJoinPrivateServer(args: { isMember: boolean; joinCode: string | undefined; suppliedCode: string | undefined; }): boolean — Private-server join-code gate. Existing members always pass; non-members must present a matching `joinCode` (loose-normalized via {@link normalizeJoinCode}). Callers still decide whether the server is private — this only answers the code/membership half.
 - `isAutoJoinCandidate` (function): function isAutoJoinCandidate(args: { memberUserIds: readonly string[]; slotsPerServer: number; visibility: SessionVisibility | undefined; userId: string; }): boolean — Auto-match candidate when no `serverId` is supplied: already a member, or a public room with free capacity. Private rooms are never auto-picked (join-by-code / direct id only).
 - `isListablePublicly` (function): function isListablePublicly(visibility: SessionVisibility | undefined): boolean — True when a server's `visibility` should surface in public listings / browse results.
 - `isPrivateJoinBlocked` (function): function isPrivateJoinBlocked(args: { visibility: SessionVisibility | undefined; memberUserIds: readonly string[]; userId: string; joinCode: string | undefined; suppliedCode: string | undefined; }): boolean — Whether a private-visibility server blocks this join (non-member without a matching code). Public / undefined visibility never blocks.
 - `isServerFull` (function): function isServerFull(memberUserIds: readonly string[], slotsPerServer: number, userId: string): boolean — True when the server has no free slots for a non-member. Existing members never count as "full" so rejoin/leave cycles keep working.
 - `isServerMember` (function): function isServerMember(memberUserIds: readonly string[], userId: string): boolean — Whether `userId` is already on the server's member roster.
+- `selectJoinTarget` (function): 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> — 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.
 - `statusAfterLeave` (function): function statusAfterLeave(remainingMemberCount: number, currentStatus: GameServerStatus): GameServerStatus — Status after a leave: empty rooms reopen; non-empty rooms keep their current status.
+- `validateSlotsPerServer` (function): function validateSlotsPerServer(slotsPerServer: number): { ok: true } | { ok: false; reason: string } — Whether a `slotsPerServer` value is a capacity a single hosted server row can actually hold.
 - `withJoinedMember` (function): function withJoinedMember(memberUserIds: readonly string[], userId: string): string[] — Roster after a successful join: unchanged when already a member, else appended.
 - `withoutMember` (function): function withoutMember(memberUserIds: readonly string[], userId: string): string[] — Roster after a leave: `userId` removed; order of remaining members preserved.
 
@@ -402,6 +416,11 @@
 - `MotionIntentBatch` (interface): interface MotionIntentBatch — ⚠ undocumented
 - `MotionIntents` (interface): interface MotionIntents — Seam for game code to reach the motion the shell's FrameDriver otherwise owns privately (#162.4). Game code calls `impulse`, `pushHorizontal`, `setVerticalVelocity`, and/or `setY` from `onTick` or commands; the shell calls `takePending()` once per frame, before integrating gravity, to drain what accumulated. `setY` wins over physics for that frame; impulses add to the velocity the driver is about to integrate; a later `setVerticalVelocity` replaces that velocity outright. Horizontal pushes compose with the walk controller (#282.4): they add to its horizontal velocity and decay naturally as it re-blends toward input — knockback, dashes, explosion shoves without raw `setPose` offsets.
 
+## @jgengine/core/runtime/objectRows
+
+- `fromRuntimeObjectRow` (function): function fromRuntimeObjectRow(row: RuntimeObjectRow): SceneObject — Inverse of {@link toRuntimeObjectRow}: rebuild the live placed object a host persisted.
+- `toRuntimeObjectRow` (function): function toRuntimeObjectRow(object: SceneObject): RuntimeObjectRow — 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`.
+
 ## @jgengine/core/runtime/perContext
 
 - `perContext` (function): function perContext<T>(init: (ctx: GameContext) => T): (ctx: GameContext) => T — Per-`GameContext` lazy state, keyed by context identity through a `WeakMap` so it is reclaimed when the context is — the seam a game uses instead of a module-global `Map`, which is process-global and bleeds across worlds when one host serves several `serverId`s (#632). `init` runs once per distinct context on first access; the same context always resolves to the same value. This mirrors the engine's built-in per-ctx pattern (`ctx.player.motion`, `stepPlayerMovement`).
@@ -441,7 +460,7 @@
 - `RuntimeChunkRow` (type): type RuntimeChunkRow = { chunkKey: string; objects: RuntimeObjectRow[]; entities: RuntimeEntityRow[]; flags?: Record<string, unknown>; } — ⚠ undocumented
 - `RuntimeEntityRow` (type): type RuntimeEntityRow = { instanceId: string; catalogId: string; position?: [number, number, number]; rotationY?: number; parentSpace?: string; group?: string; stats?: Record<string, { current: number; max: number; min?: number }>; targetInstanceId?: string | null; userId?: string; } — ⚠ undocumented
 - `RuntimeInventorySlot` (type): type RuntimeInventorySlot = { item: string; count: number; slot?: number; } — ⚠ undocumented
-- `RuntimeObjectRow` (type): type RuntimeObjectRow = { instanceId: string; catalogId: string; position: [number, number, number]; rotationY?: number; parentSpace?: string; flags?: Record<string, unknown>; } — ⚠ undocumented
+- `RuntimeObjectRow` (type): 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 `slotInve… — The persisted form of a placed `SceneObject`: identity, placement, per-instance state, and slot contents. Convert with `toRuntimeObjectRow`/`fromRuntimeObjectRow` (`runtime/objectRows`).
 - `RuntimePlayerRow` (type): type RuntimePlayerRow = { userId: string; inventories: Record<string, RuntimeInventorySlot[]>; economy: Record<string, number>; unlocks: string[]; quests?: unknown; social?: unknown; leaderboard?: Record<string, number>; session?: Record<string, unknown>; } — ⚠ undocumented
 - `RuntimeProfileRow` (type): type RuntimeProfileRow = { userId: string; gameId: string; player: RuntimePlayerRow; updatedAt: number; } — ⚠ undocumented
 - `RuntimeServerRow` (type): type RuntimeServerRow = { entities: RuntimeEntityRow[]; objects: RuntimeObjectRow[]; session: Record<string, unknown>; feeds?: Record<string, unknown[]>; } — ⚠ undocumented
@@ -483,6 +502,20 @@
 - `WorldHostConnection` (interface): interface WorldHostConnection — One client's link on the host side: routes its upstream frames into the shared session, pushes it sync frames.
 - `WorldServerFrame` (type): type WorldServerFrame = | { t: "baseline"; revision: number; snapshot: WorldSnapshot } | { t: "diff"; diff: WorldDiff } — Host→client frame: the full baseline a joiner needs, then per-tick diffs. What a transport marshals downstream.
 
+## @jgengine/core/runtime/worldChunks
+
+- `ChunkCoord` (type): type ChunkCoord = { cx: number; cz: number } — Integer cell coordinates of a chunk on the ground plane.
+- `DEFAULT_CHUNK_SIZE` (const): const DEFAULT_CHUNK_SIZE: 64 — Default edge length, in world units, of one persisted world chunk.
+- `chunkCoordAt` (function): function chunkCoordAt(position: readonly [number, number, number], size: number = DEFAULT_CHUNK_SIZE): ChunkCoord — Chunk coordinates containing a world position at `size` units per cell.
+- `chunkKeyAt` (function): function chunkKeyAt(position: readonly [number, number, number], size: number = DEFAULT_CHUNK_SIZE): string — Chunk key containing a world position at `size` units per cell.
+- `chunkKeyOf` (function): function chunkKeyOf(coord: ChunkCoord): string — 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.
+- `chunkKeysInRadius` (function): function chunkKeysInRadius(center: readonly [number, number, number], radius: number, size: number = DEFAULT_CHUNK_SIZE): string[] — 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.
+- `createEmptyChunkRow` (function): function createEmptyChunkRow(chunkKey: string): RuntimeChunkRow — An empty chunk row for `chunkKey` — the starting value for a cell nothing has been placed in yet.
+- `deleteChunk` (function): function deleteChunk(snapshot: GameRuntimeSnapshot, chunkKey: string): GameRuntimeSnapshot — Drop a chunk from a snapshot and mark the key dirty so the host deletes its stored row.
+- `parseChunkKey` (function): function parseChunkKey(key: string): ChunkCoord | null — Parse a `chunkKeyOf` string back to coordinates; `null` for anything not in that form.
+- `setChunk` (function): function setChunk(snapshot: GameRuntimeSnapshot, chunkKey: string, chunk: RuntimeChunkRow): GameRuntimeSnapshot — 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.
+- `updateChunk` (function): function updateChunk(snapshot: GameRuntimeSnapshot, chunkKey: string, update: (chunk: RuntimeChunkRow) => RuntimeChunkRow): GameRuntimeSnapshot — Read-modify-write a chunk (creating it empty when absent), marking it dirty.
+
 ## @jgengine/core/runtime/worldMirror
 
 - `WorldMirror` (interface): interface WorldMirror — The client end of host-authoritative replication: folds a host's baseline + {@link WorldDiff} stream onto a local {@link GameContext}. It keeps the last full {@link WorldSnapshot}, advances it with each diff, and pushes the result through `ctx.hydrate` — so the client mirrors exactly the subsystems its own game opted into and silently ignores host modules it lacks. This is the inverse of a {@link HostedWorldSession}; the transport in between (loopback, ws, Convex) is irrelevant.

package/skills/jgengine/capabilities.md

@@ -48,6 +48,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `canJoinPrivateServer` (function) · `import { canJoinPrivateServer } from "@jgengine/core/runtime/hostPolicy"`
 
+## host-join-target — choose or refuse an auto-matched server under a matchmaking mode
+
+- `selectJoinTarget` (function) · `import { selectJoinTarget } from "@jgengine/core/runtime/hostPolicy"`
+
 ## host-listing-filter — exclude private sessions from public browse results
 
 - `isListablePublicly` (function) · `import { isListablePublicly } from "@jgengine/core/runtime/hostPolicy"`
@@ -100,6 +104,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `ws` (function) · `import { ws } from "@jgengine/core/runtime/adapter"`
 
+## object-slot-inventory — placed objects hold validated per-instance container contents that replicate and save with the placement
+
+- `SceneObjectSlots` (interface) · `import { SceneObjectSlots } from "@jgengine/core/runtime/context/objectSlots"`
+
+## placed-object-rehydrate — rebuild live placed objects, with their state and slot contents, from persisted snapshot rows
+
+- `fromRuntimeObjectRow` (function) · `import { fromRuntimeObjectRow } from "@jgengine/core/runtime/objectRows"`
+
+## placed-object-rows — a placed object's per-instance state and container contents convert to and from the persisted snapshot row a host stores
+
+- `toRuntimeObjectRow` (function) · `import { toRuntimeObjectRow } from "@jgengine/core/runtime/objectRows"`
+
 ## render-fallback-diagnostics — Enable/disable the dev-only placeholder-fallback probe.
 
 - `armFallbackSeams` (function) · `import { armFallbackSeams } from "@jgengine/core/devtools/fallbackSeams"`
@@ -134,6 +150,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineStore` (function) · `import { defineStore } from "@jgengine/shell/gameKit"`
 
+## world-chunk-key — map world positions to persisted chunk keys at a declared cell size
+
+- `chunkKeyOf` (function) · `import { chunkKeyOf } from "@jgengine/core/runtime/worldChunks"`
+
+## world-chunk-write — mutate a snapshot's chunk and have the host persist it
+
+- `setChunk` (function) · `import { setChunk } from "@jgengine/core/runtime/worldChunks"`
+
 ## world-convergence — derive environment coordinate content from the scene document
 
 - `environmentContentFromDocument` (function) · `import { environmentContentFromDocument } from "@jgengine/shell/gameKit"`

package/skills/jgengine-multiplayer/api.md

@@ -14,14 +14,26 @@
 - `ConvexSaveBackendOptions` (interface): interface ConvexSaveBackendOptions — Config for {@link createConvexSaveBackend} — the Convex client, optional function refs (defaults to the `saves.*` convention), and an optional key `namespace`.
 - `ConvexSaveFunctions` (interface): interface ConvexSaveFunctions — The three Convex functions a save backend calls — a `query` that returns the stored string (or `null`) and two `mutation`s. Point them at your app's own module, or lean on the default `saves.*` convention.
 - `DEFAULT_CONVEX_POSE_RULES` (const): const DEFAULT_CONVEX_POSE_RULES: PoseSyncRules — ⚠ undocumented
+- `DEFAULT_MAX_SERVERS_PER_TICK` (const): const DEFAULT_MAX_SERVERS_PER_TICK: 32 — How many running servers one `tickActiveServers` transaction may hydrate, tick, and persist.
+- `GameServerHelpers` (type): type GameServerHelpers = { loadSnapshot: ( ctx: JGMutationCtx, serverId: string, scope?: LoadSnapshotScope, ) => Promise<LoadedServerSnapshot | null>; applyCommand: (args: { gameId: string; loadedRevision: number; currentRevision: number; snapshot: GameRuntimeSnapshot; actorUserId: string; command: … — The plain-function half of {@link createGameServerFunctions}, bound to the same runtime registry and auth mode as its mutations. Reach for it when a host mutation must pair snapshot work with its own table writes in one transaction, which a pre-registered mutation cannot do.
 - `HostedGameConfig` (interface): interface HostedGameConfig — One game the hosted path can serve, bound per `gameId`: its definition plus content lookup.
 - `HostedWorldInvocation` (interface): interface HostedWorldInvocation<T> — Everything one stateless invocation reconstructs a hosted world from: the persisted record via `store`, plus the member roster and held inputs the snapshot doesn't carry, and the op to apply to the fresh session.
 - `HostedWorldOutcome` (interface): interface HostedWorldOutcome<T> — What one stateless invocation produced: the op's value, the resulting revision, whether the world changed (and was saved back), and the post-op roster.
+- `JGDataModel` (type): type JGDataModel = DataModelFromSchemaDefinition<typeof schemaForTypes> — Data model of the {@link jgengineTables} schema — the shape a host's own Convex ctx must satisfy to call the exported persistence helpers.
+- `JGMutationCtx` (type): type JGMutationCtx = GenericMutationCtx<JGDataModel> — Mutation ctx accepted by {@link loadServerSnapshot} / {@link persistServerSnapshot}.
 - `JG_HOSTED_TICK_MS` (const): const JG_HOSTED_TICK_MS: 1000 — Default minimum elapsed ms before `tickHostedWorlds` advances a world — override via the factory's `tickMs`.
+- `JG_MAX_MEMBERS_PER_SERVER` (const): const JG_MAX_MEMBERS_PER_SERVER: 256 — Hard ceiling on `slotsPerServer` for a single hosted server row.
 - `JG_RUNTIME_TICK_MS` (const): const JG_RUNTIME_TICK_MS: 1000 — ⚠ undocumented
 - `JgAuthMode` (type): type JgAuthMode = "anonymous" | "required" — ⚠ undocumented
 - `JgCronSpec` (type): type JgCronSpec = { name: string; intervalSeconds: number; functionKey: "tickActiveServers" | "flushDirtyServers"; } — ⚠ undocumented
+- `LoadSnapshotScope` (type): type LoadSnapshotScope = { /** 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[]; } — How much of a server to hydrate. Both fields default to "everything", which is a document 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: a command that only moves the actor's own state needs `players: [actorUserId]`, and a spatial edit needs only the chunk keys it writes (`chunkKeysInRadius` from `@jgengine/core/runtime/worldChunks`).
+- `LoadedServerSnapshot` (type): type LoadedServerSnapshot = { server: ServerDoc; runtime: GameRuntime; snapshot: GameRuntimeSnapshot; } — A server resolved for runtime work: its row, its registered runtime, and its hydrated snapshot.
+- `MAX_CHUNKS_PER_QUERY` (const): const MAX_CHUNKS_PER_QUERY: 64 — How many chunk rows one `getChunks` call may return.
+- `MatchmakingMode` (type): type MatchmakingMode = "auto" | "singleton" — How auto-match behaves when no `serverId` is supplied.
 - `REVISION_CONFLICT_REASON` (const): const REVISION_CONFLICT_REASON: "Revision conflict" — ⚠ undocumented
+- `RunCommandArgs` (type): type RunCommandArgs = { serverId: string; command: string; input: unknown; externalId?: string; } — Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper.
+- `RunCommandOutcome` (type): type RunCommandOutcome = { ok: true } | { ok: false; reason: string } — Outcome of a runtime command: applied, or refused with a reason (unknown server, non-member, validation, revision conflict).
+- `ServerDoc` (type): type ServerDoc = DocumentByName<JGDataModel, "jgGameServers"> — A `jgGameServers` row — the server handle the persistence helpers load from and write back to.
 - `canJoinPrivateServer` (function): function canJoinPrivateServer(args: { isMember: boolean; joinCode: string | undefined; suppliedCode: string | undefined; }): boolean — Private-server join-code gate. Existing members always pass; non-members must present a matching `joinCode` (loose-normalized via {@link normalizeJoinCode}). Callers still decide whether the server is private — this only answers the code/membership half.
 - `createConvexBackend` (function): function createConvexBackend<TRawPresenceRow extends { actorExternalId: string } = { actorExternalId: string }, TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string>(options: ConvexBackendOptions<TRawPresenceRow, TPresenceRow>): ConvexBackend<TPresenceRow, TPresenceLo… — ⚠ undocumented
 - `createConvexChatSync` (function): function createConvexChatSync(client: ConvexReactClient, api: ConvexGameApi, config: ConvexGameTransportConfig, serverId: string): ChatSync — ⚠ undocumented
@@ -36,8 +48,11 @@
 - `defaultConvexGameApi` (function): function defaultConvexGameApi(): ConvexGameApi — ⚠ undocumented
 - `defaultConvexSaveFunctions` (function): function defaultConvexSaveFunctions(): ConvexSaveFunctions — Default `saves.read` / `saves.write` / `saves.remove` refs for apps that follow the convention — pass your own `functions` to override.
 - `isListablePublicly` (function): function isListablePublicly(visibility: SessionVisibility | undefined): boolean — True when a server's `visibility` should surface in public listings / browse results.
+- `loadServerSnapshot` (function): function loadServerSnapshot(ctx: JGMutationCtx, server: ServerDoc, runtime: GameRuntime, scope?: LoadSnapshotScope): Promise<GameRuntimeSnapshot> — Hydrate a server's `GameRuntimeSnapshot` from its row, its members' profiles, and its world chunks. Reach for it when writing your own mutation that must read runtime state before touching host tables. Pass a {@link LoadSnapshotScope} to bound the read instead of loading the whole world.
+- `persistServerSnapshot` (function): function persistServerSnapshot(ctx: JGMutationCtx, server: ServerDoc, snapshot: GameRuntimeSnapshot, save: SaveConfig): Promise<boolean> — Write a snapshot back: server row, dirty player profiles, dirty chunks, and drained leaderboard increments, all under `save`. Pair it with your own table writes to keep both in one transaction.
 - `randomConvexPlayerId` (function): function randomConvexPlayerId(): string — ⚠ undocumented
 - `resolveConvexMultiplayer` (function): function resolveConvexMultiplayer(args: { game: GameDefinition; gameId: string; url?: string; client?: ConvexReactClient; api?: ConvexGameApi; userId?: string; force?: boolean; feedActions?: string[]; poseTuning?: PoseSyncTuning; }): MultiplayerSession | null — ⚠ undocumented
+- `validateSlotsPerServer` (function): function validateSlotsPerServer(slotsPerServer: number): { ok: true; } | { ok: false; reason: string; } — Whether a `slotsPerServer` value is a capacity a single hosted server row can actually hold.
 - `watchConvexQuery` (function): function watchConvexQuery<TArgs extends DefaultFunctionArgs, TResult, TView>(client: ConvexReactClient, query: FunctionReference<"query", "public", TArgs, TResult>, args: TArgs, toView: (result: TResult) => TView, onChange: (view: TView) => void): () => void — ⚠ undocumented
 
 ## @jgengine/convex/convexChatTransport
@@ -96,11 +111,26 @@
 ## @jgengine/convex/server
 
 - `DEFAULT_CONVEX_POSE_RULES` (const): const DEFAULT_CONVEX_POSE_RULES: PoseSyncRules — ⚠ undocumented
+- `DEFAULT_MAX_SERVERS_PER_TICK` (const): const DEFAULT_MAX_SERVERS_PER_TICK: 32 — How many running servers one `tickActiveServers` transaction may hydrate, tick, and persist.
+- `GameServerHelpers` (type): type GameServerHelpers = { loadSnapshot: ( ctx: JGMutationCtx, serverId: string, scope?: LoadSnapshotScope, ) => Promise<LoadedServerSnapshot | null>; applyCommand: (args: { gameId: string; loadedRevision: number; currentRevision: number; snapshot: GameRuntimeSnapshot; actorUserId: string; command: … — The plain-function half of {@link createGameServerFunctions}, bound to the same runtime registry and auth mode as its mutations. Reach for it when a host mutation must pair snapshot work with its own table writes in one transaction, which a pre-registered mutation cannot do.
+- `JGDataModel` (type): type JGDataModel = DataModelFromSchemaDefinition<typeof schemaForTypes> — Data model of the {@link jgengineTables} schema — the shape a host's own Convex ctx must satisfy to call the exported persistence helpers.
+- `JGMutationCtx` (type): type JGMutationCtx = GenericMutationCtx<JGDataModel> — Mutation ctx accepted by {@link loadServerSnapshot} / {@link persistServerSnapshot}.
+- `JG_MAX_MEMBERS_PER_SERVER` (const): const JG_MAX_MEMBERS_PER_SERVER: 256 — Hard ceiling on `slotsPerServer` for a single hosted server row.
 - `JG_RUNTIME_TICK_MS` (const): const JG_RUNTIME_TICK_MS: 1000 — ⚠ undocumented
 - `JgAuthMode` (type): type JgAuthMode = "anonymous" | "required" — ⚠ undocumented
 - `JgCronSpec` (type): type JgCronSpec = { name: string; intervalSeconds: number; functionKey: "tickActiveServers" | "flushDirtyServers"; } — ⚠ undocumented
+- `LoadSnapshotScope` (type): type LoadSnapshotScope = { /** 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[]; } — How much of a server to hydrate. Both fields default to "everything", which is a document 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: a command that only moves the actor's own state needs `players: [actorUserId]`, and a spatial edit needs only the chunk keys it writes (`chunkKeysInRadius` from `@jgengine/core/runtime/worldChunks`).
+- `LoadedServerSnapshot` (type): type LoadedServerSnapshot = { server: ServerDoc; runtime: GameRuntime; snapshot: GameRuntimeSnapshot; } — A server resolved for runtime work: its row, its registered runtime, and its hydrated snapshot.
+- `MAX_CHUNKS_PER_QUERY` (const): const MAX_CHUNKS_PER_QUERY: 64 — How many chunk rows one `getChunks` call may return.
+- `MatchmakingMode` (type): type MatchmakingMode = "auto" | "singleton" — How auto-match behaves when no `serverId` is supplied.
+- `RunCommandArgs` (type): type RunCommandArgs = { serverId: string; command: string; input: unknown; externalId?: string; } — Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper.
+- `RunCommandOutcome` (type): type RunCommandOutcome = { ok: true } | { ok: false; reason: string } — Outcome of a runtime command: applied, or refused with a reason (unknown server, non-member, validation, revision conflict).
+- `ServerDoc` (type): type ServerDoc = DocumentByName<JGDataModel, "jgGameServers"> — A `jgGameServers` row — the server handle the persistence helpers load from and write back to.
 - `canJoinPrivateServer` (function): function canJoinPrivateServer(args: { isMember: boolean; joinCode: string | undefined; suppliedCode: string | undefined; }): boolean — Private-server join-code gate. Existing members always pass; non-members must present a matching `joinCode` (loose-normalized via {@link normalizeJoinCode}). Callers still decide whether the server is private — this only answers the code/membership half.
 - `isListablePublicly` (function): function isListablePublicly(visibility: SessionVisibility | undefined): boolean — True when a server's `visibility` should surface in public listings / browse results.
+- `loadServerSnapshot` (function): function loadServerSnapshot(ctx: JGMutationCtx, server: ServerDoc, runtime: GameRuntime, scope?: LoadSnapshotScope): Promise<GameRuntimeSnapshot> — Hydrate a server's `GameRuntimeSnapshot` from its row, its members' profiles, and its world chunks. Reach for it when writing your own mutation that must read runtime state before touching host tables. Pass a {@link LoadSnapshotScope} to bound the read instead of loading the whole world.
+- `persistServerSnapshot` (function): function persistServerSnapshot(ctx: JGMutationCtx, server: ServerDoc, snapshot: GameRuntimeSnapshot, save: SaveConfig): Promise<boolean> — Write a snapshot back: server row, dirty player profiles, dirty chunks, and drained leaderboard increments, all under `save`. Pair it with your own table writes to keep both in one transaction.
+- `validateSlotsPerServer` (function): function validateSlotsPerServer(slotsPerServer: number): { ok: true; } | { ok: false; reason: string; } — Whether a `slotsPerServer` value is a capacity a single hosted server row can actually hold.
 
 ## @jgengine/core/multiplayer
 
@@ -137,10 +167,12 @@
 - `createPoseSyncGate` (function): function createPoseSyncGate(tuning: PoseSyncTuning): PoseSyncGate — ⚠ undocumented
 - `createPushToTalk` (function): function createPushToTalk(config?: { mode?: PushToTalkMode; onChange?: (transmitting: boolean) => void; }): PushToTalk — ⚠ undocumented
 - `findByJoinCode` (function): function findByJoinCode(listings: readonly SessionListing[], code: string): SessionListing | null — ⚠ undocumented
+- `fromRuntimeObjectRow` (function): function fromRuntimeObjectRow(row: RuntimeObjectRow): SceneObject — Inverse of {@link toRuntimeObjectRow}: rebuild the live placed object a host persisted.
 - `normalizeJoinCode` (function): function normalizeJoinCode(code: string): string — ⚠ undocumented
 - `quickMatch` (function): function quickMatch(listings: readonly SessionListing[], filter: MatchFilter = {}): SessionListing | null — ⚠ undocumented
 - `resolveGuestSession` (function): function resolveGuestSession(seed?: string): AuthSession — ⚠ undocumented
 - `sessionPlayer` (function): function sessionPlayer(session: AuthSession): PlayerIdentity — ⚠ undocumented
+- `toRuntimeObjectRow` (function): function toRuntimeObjectRow(object: SceneObject): RuntimeObjectRow — 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`.
 - `validateFeedWrite` (function): function validateFeedWrite(gate: FeedWriteGate | undefined, action: string): { ok: true } | { ok: false; reason: string } — ⚠ undocumented
 
 ## @jgengine/core/multiplayer/chatContract

package/skills/jgengine-multiplayer/capabilities.md

@@ -4,6 +4,14 @@
 
 Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
 
+## convex-load-server-snapshot — read a hosted server's runtime snapshot inside a host-written Convex mutation
+
+- `loadServerSnapshot` (function) · `import { loadServerSnapshot } from "@jgengine/convex"`
+
+## convex-persist-server-snapshot — write runtime state and host tables in one Convex transaction
+
+- `persistServerSnapshot` (function) · `import { persistServerSnapshot } from "@jgengine/convex"`
+
 ## convex-save — save a game to Convex (cloud) through the SaveBackend seam
 
 - `createConvexSaveBackend` (function) · `import { createConvexSaveBackend } from "@jgengine/convex"`
@@ -15,3 +23,11 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## host-listing-filter — exclude private sessions from public browse results
 
 - `isListablePublicly` (function) · `import { isListablePublicly } from "@jgengine/convex"`
+
+## placed-object-rehydrate — rebuild live placed objects, with their state and slot contents, from persisted snapshot rows
+
+- `fromRuntimeObjectRow` (function) · `import { fromRuntimeObjectRow } from "@jgengine/core/multiplayer"`
+
+## placed-object-rows — a placed object's per-instance state and container contents convert to and from the persisted snapshot row a host stores
+
+- `toRuntimeObjectRow` (function) · `import { toRuntimeObjectRow } from "@jgengine/core/multiplayer"`

package/skills/jgengine-multiplayer/reference.md

@@ -33,7 +33,13 @@ Once a session resolves, the shell (`GameHost`'s internal player) wires it up wi
 
 A synced pose (`@jgengine/ws/protocol`'s `WsPose`/`WsPresenceRow`) carries an optional `appearance: Record<string, string | number | boolean>` alongside position/rotation — primitive-valued client-set tags (skin id, mount id, active emote, team color) riding the same pose-sync frames as position, so a remote player's cosmetic state updates on the existing presence channel instead of a second round-trip.
 
-**Server side** — `@jgengine/convex/server` ships an entire authoritative Convex backend as factories, not a template to copy: `jgengineTables()` (schema spread), `createGameServerFunctions({ runtimes?, auth? })`, `createLeaderboardFunctions({ auth? })`, `createPresenceFunctions({ auth?, freshWindowMs? })`, `createChatFunctions({ auth?, historyLimit?, maxBodyLength?, minIntervalMs? })`, and `jgengineCronSpecs()` (tick/flush interval metadata for a `crons.ts`). A consumer's `convex/` directory is ~25 lines: `schema.ts` (`defineSchema({ ...jgengineTables() })`), four one-line re-export files (`runtime.ts`, `leaderboard.ts`, `presence.ts`, `chat.ts`, each just calling its factory), and `crons.ts` registering the tick (1s) + flush (60s) internal mutations — see `examples/convex-host` for the reference shape. No game-specific code lives there; any JGengine game can point at the same deployment. Games without a registered `GameRuntime` fall back to a no-save runtime that only understands `engine.ping`; pass `createGameServerFunctions({ runtimes: [createGameRuntime({ gameId, commands, loop, save })] })` to make `runCommand` / tick / save actually do something.
+**Server side** — `@jgengine/convex/server` ships an entire authoritative Convex backend as factories, not a template to copy: `jgengineTables()` (schema spread), `createGameServerFunctions({ runtimes?, auth? })`, `createLeaderboardFunctions({ auth? })`, `createPresenceFunctions({ auth?, freshWindowMs? })`, `createChatFunctions({ auth?, historyLimit?, maxBodyLength?, minIntervalMs? })`, and `jgengineCronSpecs()` (tick/flush interval metadata for a `crons.ts`). A consumer's `convex/` directory is ~25 lines: `schema.ts` (`defineSchema({ ...jgengineTables() })`), four one-line re-export files (`runtime.ts`, `leaderboard.ts`, `presence.ts`, `chat.ts`, each just calling its factory), and `crons.ts` registering the tick (1s) + flush (60s) internal mutations — see `examples/convex-host` for the reference shape. No game-specific code lives there; any JGengine game can point at the same deployment. Games without a registered `GameRuntime` fall back to a no-save runtime that only understands `engine.ping`; pass `createGameServerFunctions({ runtimes: [createGameRuntime({ gameId, commands, loop, save })] })` to make `runCommand` / tick / save actually do something. When a host mutation must pair snapshot work with its own table writes in one transaction, use the factory's `helpers` (`loadSnapshot`, `applyCommand`, `persistSnapshot`, `runCommand` — same registry and auth mode) or the standalone `loadServerSnapshot` / `persistServerSnapshot` exports.
+
+**How big a hosted world gets.** One server is one Convex document holding the world row, the roster, and every member's session state, so member count is a per-transaction cost. `slotsPerServer` is capped at `JG_MAX_MEMBERS_PER_SERVER` (256) and `createGameServerFunctions` throws at wiring time on anything larger — a bigger number was never a bigger world, just a document that overflows later. World geometry that outgrows one row goes in `jgWorldChunks`: hydrate by key (`loadServerSnapshot(ctx, server, runtime, { players, chunkKeys })`), read from clients with the generated `getChunks`, and key cells with `chunkKeyAt` / `chunkKeysInRadius` from `@jgengine/core/runtime/worldChunks`. Mutate chunks through `setChunk` / `updateChunk` / `deleteChunk` — a raw `snapshot.chunks[key] = …` is never marked dirty and never persists.
+
+**What the host does per second.** The tick cron sweeps only games whose runtime declares `loop.onTick`, at most `maxServersPerTick` (default 32) servers per transaction, oldest anchor first; a game with no tick hook costs nothing while idle. A persist that would change nothing writes nothing, so an idle world stops re-pushing itself to every subscriber once a second. Subscribe lobby UI to `getServerMeta` (status, member count, revision) rather than `getServer`, whose payload is the whole world, and set `replication: { aoiRadius }` so `entities`, `stats`, and `objects` all cull to each viewer.
+
+**One shared world.** `createGameServerFunctions({ matchmaking: "singleton" })` makes auto-match always target the existing world and refuse a join past capacity, instead of quietly creating a second world the player would be alone in. `joinServer` also reconciles a stored `slotsPerServer`/`save` that has drifted from the host options, so raising the option takes effect on worlds that already exist. Auto-match relies on Convex OCC to resolve two concurrent first-joins (the loser's read set is invalidated and its mutation retries); a non-Convex `HostPersistence` must supply that guarantee itself.
 
 Auth defaults to `"anonymous"` (`JgAuthMode`) on every factory — the client's `externalId` is trusted as claimed, fine for local dev but spoofable. Pass `{ auth: "required" }` to every factory for production; the resolved actor becomes `ctx.auth.getUserIdentity()`'s `subject` and `externalId` is only cross-checked against it, never trusted alone.