@jgengine/convex 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -26,14 +26,60 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.18.0
+
 ### Migrate
 
+- **Bump lockstep SDK packages to `^0.18.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.15.0`; `@jgengine/github` is `0.5.0`.
+- **Register the presence reaper and redeploy your schema.** `jgPoses` gains `sessionId` / `kind` / `label` / `revokedAt` (all optional) and a `by_updated` index, and `createPresenceFunctions` now also returns `reapIdlePresence`. Re-export it (`export const { list, sync, leave, reapIdlePresence } = createPresenceFunctions(...)`) and add `crons.interval("jg presence reap", { seconds: 60 }, internal.presence.reapIdlePresence, {})`. Without it nothing deletes the row of a player who closed the tab — `list` filtered stale rows at read time but the table grew forever. `jgengineCronSpecs()` carries the new entry, and every spec now names the `module` (`"runtime"` / `"presence"`) it is exported from.
+- **`presence.sync` returns `{ pose, lastSeenAt, displaced }` instead of `null`,** and `presence.leave` marks the row revoked instead of deleting it (the reaper collects it once idle). A caller that ignored the return value is unaffected.
+
 ### Changed
 
+- **`presence.sync` accepts a call with no `pose` at all,** which holds the stored position and moves only the liveness stamp. `createConvexPresenceSync` sends one itself when the pose gate has suppressed writes for 10s, so a standing player keeps their row alive without a pose write — and without the reaper collecting a live session.
+- **`PresencePoseRow` carries optional `sessionId` / `kind` / `label`,** so a nameplate reads off the presence row instead of joining against users per frame.
+
 ### Added
 
+- **`createPresenceFunctions` gains the policy hooks the pose lane was missing** — `resolveSpawn(ctx, { serverId, userId, kind })` for where a session with no row starts (async and ctx-bearing, so a spawn can read the world, replacing a hardcoded origin), `poseRules` as a function of the actor `kind` so an agent need not obey a human's speed cap, `idleCutoffMs` / `maxReapPerRun` for the reaper, and optional `sessionId` on `sync` / `leave`: a second tab is a second row, syncing revokes the others, and the displaced session learns it on its next call through `displaced: true`.
+
+- **A command declares what it touches, so `runCommand` hydrates that and nothing else.** `CommandDef` gains an optional `scope(input, actorUserId)` returning `{ players?, chunkKeys? }`, evaluated before hydration; the registered `runCommand` mutation also accepts an explicit `scope` argument, which wins over the declared one. A game that never sets either keeps the whole-world default. `ServerLoopHooks.joinScope(userId, isNew)` does the same for `onNewPlayer`.
+- **`GameRuntime.commandScope` / `GameRuntime.joinScope`** expose those declarations to any host, alongside the pure helpers `resolveCommandScope` / `scopeWithActor` / `commandScopeEscape` (`@jgengine/core/runtime/commandRunner`).
+
 ### Fixed
 
+- **`runCommand` no longer reads the whole world on every command.** `LoadSnapshotScope` landed in 0.17 but only `helpers.loadSnapshot` accepted one, so the supported way to run a command — the registered `runCommand` mutation, a one-line delegation to `helpers.runCommand` — hydrated every member profile and every chunk however narrow the command was, and a game could only get bounded hydration by reimplementing the mutation. `runCommand`, `joinServer`, and `leaveServer` now hydrate a scope; a command whose `apply` dirties a player or chunk its scope never named is refused rather than persisted, since writing an unhydrated chunk overwrites the stored one with a blank. `flushSave` / `flushServerIfDue` / `tickActiveServers` / `flushDirtyServers` still hydrate everything, which is correct for what they write.
+
+## 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

package/README.md

@@ -25,7 +25,7 @@ Once a session resolves, `GamePlayerShell` wires it up with no game code changes
 
 ## Server
 
-`@jgengine/convex/server` exports factories, not a template to copy: `jgengineTables()`, `createGameServerFunctions({ runtimes?, auth? })`, `createLeaderboardFunctions({ auth? })`, `createPresenceFunctions({ auth?, freshWindowMs? })`, `createChatFunctions({ auth?, historyLimit?, maxBodyLength?, minIntervalMs? })`, and `jgengineCronSpecs()`. A consumer's `convex/` directory is ~25 lines total:
+`@jgengine/convex/server` exports factories, not a template to copy: `jgengineTables()`, `createGameServerFunctions({ runtimes?, auth? })`, `createLeaderboardFunctions({ auth? })`, `createPresenceFunctions({ auth?, freshWindowMs?, idleCutoffMs?, poseRules?, resolveSpawn? })`, `createChatFunctions({ auth?, historyLimit?, maxBodyLength?, minIntervalMs? })`, and `jgengineCronSpecs()`. A consumer's `convex/` directory is ~25 lines total:
 
 ```ts
 // convex/schema.ts
@@ -37,7 +37,7 @@ export default defineSchema({ ...jgengineTables() });
 import { createGameServerFunctions } from "@jgengine/convex/server";
 export const { joinServer, leaveServer, runCommand, flushSave, getServer, getPlayerProfile, getFeed, pushFeedEntry, listOpenServers, tickActiveServers, flushDirtyServers } = createGameServerFunctions();
 
-// convex/crons.ts registers tickActiveServers (1s) + flushDirtyServers (60s)
+// convex/crons.ts registers tickActiveServers (1s) + flushDirtyServers (60s) + reapIdlePresence (60s)
 ```
 
 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.

package/dist/convexPresenceTransport.d.ts

@@ -1,5 +1,11 @@
 import type { FunctionReference } from "convex/server";
 import type { PresenceTransport } from "@jgengine/core/multiplayer/presenceContract";
+/**
+ * The Convex functions a **game** supplies for a world it owns: presence keyed by the game's own ids,
+ * including which residents exist while offline, which is game content and has no engine analogue.
+ * Not satisfied by `createPresenceFunctions` (`@jgengine/convex/server`) — that is the pose lane of a
+ * hosted `jgGameServers` server, backing `PresenceSync` rather than `PresenceTransport`.
+ */
 export interface ConvexPresenceFunctions {
     snapshot: FunctionReference<"query">;
     cityResidents: FunctionReference<"query">;

package/dist/createConvexGameTransport.d.ts

@@ -64,17 +64,31 @@ export type ConvexGameApi = {
         }, PresencePoseRow[]>;
         sync: FunctionReference<"mutation", "public", {
             serverId: string;
-            pose: {
+            pose?: {
                 x: number;
                 y: number;
                 z: number;
                 rotationY: number;
                 rotationPitch: number;
             };
+            sessionId?: string;
+            kind?: string;
+            label?: string;
             externalId?: string;
-        }, null>;
+        }, {
+            pose: {
+                x: number;
+                y: number;
+                z: number;
+                rotationY: number;
+                rotationPitch: number;
+            };
+            lastSeenAt: number;
+            displaced: boolean;
+        } | null>;
         leave: FunctionReference<"mutation", "public", {
             serverId: string;
+            sessionId?: string;
             externalId?: string;
         }, null>;
     };

package/dist/createConvexGameTransport.js

@@ -69,17 +69,30 @@ const DEFAULT_CONVEX_POSE_TUNING = {
     verticalEpsilon: 0.01,
     rotationEpsilon: 0.01,
 };
+/** How long a suppressed pose stream may go quiet before a position-less keep-alive is sent. */
+const KEEP_ALIVE_MS = 10_000;
 export function createConvexPresenceSync(client, api, config, tuning) {
     const gate = createPoseSyncGate(tuning ?? DEFAULT_CONVEX_POSE_TUNING);
+    const lastSentAt = new Map();
     return {
         subscribe(serverId, onChange) {
             return watchConvexQuery(client, api.presence.list, { serverId, externalId: config.userId }, (rows) => rows, onChange);
         },
         syncPose(serverId, pose) {
-            if (!gate.evaluate(pose, Date.now()))
+            const now = Date.now();
+            const moved = gate.evaluate(pose, now);
+            // The gate drops an unchanged pose, so a standing player would otherwise send nothing at all
+            // and the reaper would eventually collect a live session. Keep the row alive without a write.
+            const keepAlive = !moved && now - (lastSentAt.get(serverId) ?? 0) >= KEEP_ALIVE_MS;
+            if (!moved && !keepAlive)
                 return;
+            lastSentAt.set(serverId, now);
             void client
-                .mutation(api.presence.sync, { serverId, pose, externalId: config.userId })
+                .mutation(api.presence.sync, {
+                serverId,
+                ...(moved ? { pose } : {}),
+                externalId: config.userId,
+            })
                 .catch(() => undefined);
         },
     };

package/dist/server.d.ts

@@ -3,12 +3,14 @@ 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 { CommandScope } from "@jgengine/core/runtime/commandRunner";
 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<{
@@ -62,6 +64,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<{
@@ -133,9 +136,13 @@ export declare function jgengineTables(): {
         by_server_and_action: ["serverId", "action", "_creationTime"];
     }, {}, {}>;
     jgPoses: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        kind?: string | undefined;
+        label?: string | undefined;
+        revokedAt?: number | undefined;
         rotationPitch: number;
         rotationY: number;
         serverId: string;
+        sessionId?: string | undefined;
         updatedAt: number;
         userId: string;
         x: number;
@@ -144,15 +151,24 @@ export declare function jgengineTables(): {
     }, {
         serverId: import("convex/values").VString<string, "required">;
         userId: import("convex/values").VString<string, "required">;
+        /** One row per live session, so a second tab is a second row rather than a fight over one. */
+        sessionId: import("convex/values").VString<string | undefined, "optional">;
+        /** Actor class, e.g. `"player"` / `"agent"`, which selects the pose rules applied to it. */
+        kind: import("convex/values").VString<string | undefined, "optional">;
+        /** Display name carried on the row, so nameplates need no per-frame join against users. */
+        label: import("convex/values").VString<string | undefined, "optional">;
         x: import("convex/values").VFloat64<number, "required">;
         y: import("convex/values").VFloat64<number, "required">;
         z: import("convex/values").VFloat64<number, "required">;
         rotationY: import("convex/values").VFloat64<number, "required">;
         rotationPitch: import("convex/values").VFloat64<number, "required">;
         updatedAt: import("convex/values").VFloat64<number, "required">;
-    }, "required", "rotationPitch" | "rotationY" | "serverId" | "updatedAt" | "userId" | "x" | "y" | "z">, {
+        /** Set when the session was displaced or left; the reaper deletes the row once it goes idle. */
+        revokedAt: import("convex/values").VFloat64<number | undefined, "optional">;
+    }, "required", "kind" | "label" | "revokedAt" | "rotationPitch" | "rotationY" | "serverId" | "sessionId" | "updatedAt" | "userId" | "x" | "y" | "z">, {
         by_server: ["serverId", "_creationTime"];
         by_server_and_user: ["serverId", "userId", "_creationTime"];
+        by_updated: ["updatedAt", "_creationTime"];
     }, {}, {}>;
     jgChatMessages: import("convex/server").TableDefinition<import("convex/values").VObject<{
         at: number;
@@ -254,6 +270,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<{
@@ -325,9 +342,13 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         by_server_and_action: ["serverId", "action", "_creationTime"];
     }, {}, {}>;
     jgPoses: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        kind?: string | undefined;
+        label?: string | undefined;
+        revokedAt?: number | undefined;
         rotationPitch: number;
         rotationY: number;
         serverId: string;
+        sessionId?: string | undefined;
         updatedAt: number;
         userId: string;
         x: number;
@@ -336,15 +357,24 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     }, {
         serverId: import("convex/values").VString<string, "required">;
         userId: import("convex/values").VString<string, "required">;
+        /** One row per live session, so a second tab is a second row rather than a fight over one. */
+        sessionId: import("convex/values").VString<string | undefined, "optional">;
+        /** Actor class, e.g. `"player"` / `"agent"`, which selects the pose rules applied to it. */
+        kind: import("convex/values").VString<string | undefined, "optional">;
+        /** Display name carried on the row, so nameplates need no per-frame join against users. */
+        label: import("convex/values").VString<string | undefined, "optional">;
         x: import("convex/values").VFloat64<number, "required">;
         y: import("convex/values").VFloat64<number, "required">;
         z: import("convex/values").VFloat64<number, "required">;
         rotationY: import("convex/values").VFloat64<number, "required">;
         rotationPitch: import("convex/values").VFloat64<number, "required">;
         updatedAt: import("convex/values").VFloat64<number, "required">;
-    }, "required", "rotationPitch" | "rotationY" | "serverId" | "updatedAt" | "userId" | "x" | "y" | "z">, {
+        /** Set when the session was displaced or left; the reaper deletes the row once it goes idle. */
+        revokedAt: import("convex/values").VFloat64<number | undefined, "optional">;
+    }, "required", "kind" | "label" | "revokedAt" | "rotationPitch" | "rotationY" | "serverId" | "sessionId" | "updatedAt" | "userId" | "x" | "y" | "z">, {
         by_server: ["serverId", "_creationTime"];
         by_server_and_user: ["serverId", "userId", "_creationTime"];
+        by_updated: ["updatedAt", "_creationTime"];
     }, {}, {}>;
     jgChatMessages: import("convex/server").TableDefinition<import("convex/values").VObject<{
         at: number;
@@ -377,20 +407,40 @@ 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.
+ *
+ * The registered `runCommand` mutation takes one, and a {@link CommandDef} can derive its own from
+ * its input via `scope`, so a game gets bounded hydration without writing its own mutation.
+ */
+export type LoadSnapshotScope = CommandScope;
 /**
  * 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): Promise<GameRuntimeSnapshot>;
+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<void>;
+export declare function persistServerSnapshot(ctx: JGMutationCtx, server: ServerDoc, snapshot: GameRuntimeSnapshot, save: SaveConfig): Promise<boolean>;
 export declare const JG_RUNTIME_TICK_MS = 1000;
 /** Outcome of a runtime command: applied, or refused with a reason (unknown server, non-member, validation, revision conflict). */
 export type RunCommandOutcome = {
@@ -405,6 +455,11 @@ export type RunCommandArgs = {
     command: string;
     input: unknown;
     externalId?: string;
+    /**
+     * How much of the server to hydrate before applying the command. Overrides whatever the
+     * {@link CommandDef} declares through its own `scope`; omit both to hydrate the whole world.
+     */
+    scope?: LoadSnapshotScope;
 };
 /** A server resolved for runtime work: its row, its registered runtime, and its hydrated snapshot. */
 export type LoadedServerSnapshot = {
@@ -418,7 +473,7 @@ export type LoadedServerSnapshot = {
  * table writes in one transaction, which a pre-registered mutation cannot do.
  */
 export type GameServerHelpers = {
-    loadSnapshot: (ctx: JGMutationCtx, serverId: string) => Promise<LoadedServerSnapshot | null>;
+    loadSnapshot: (ctx: JGMutationCtx, serverId: string, scope?: LoadSnapshotScope) => Promise<LoadedServerSnapshot | null>;
     applyCommand: (args: {
         gameId: string;
         loadedRevision: number;
@@ -434,14 +489,33 @@ export type GameServerHelpers = {
         ok: false;
         reason: string;
     };
-    persistSnapshot: (ctx: JGMutationCtx, server: ServerDoc, snapshot: GameRuntimeSnapshot, save?: SaveConfig) => Promise<void>;
+    persistSnapshot: (ctx: JGMutationCtx, server: ServerDoc, snapshot: GameRuntimeSnapshot, save?: SaveConfig) => Promise<boolean>;
     runCommand: (ctx: JGMutationCtx, args: RunCommandArgs) => Promise<RunCommandOutcome>;
 };
-/** @internal */
+/** 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", {
@@ -464,6 +538,10 @@ export declare function createGameServerFunctions(options?: {
         command: string;
         externalId?: string | undefined;
         input: any;
+        scope?: {
+            chunkKeys?: string[] | undefined;
+            players?: string[] | undefined;
+        } | undefined;
         serverId: GenericId<"jgGameServers">;
     }, Promise<RunCommandOutcome>>;
     flushSave: import("convex/server").RegisteredMutation<"public", {
@@ -491,6 +569,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;
@@ -564,41 +664,92 @@ export declare function createLeaderboardFunctions(options?: {
         gameId: string;
     }, Promise<null>>;
 };
-/** @internal */
+/** One member's pose as `list` reports it. */
+export type PresenceListRow = {
+    userId: string;
+    sessionId?: string;
+    kind?: string;
+    label?: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY: number;
+    rotationPitch: number;
+    lastSeenAt: number;
+};
+/** What `sync` hands back: the pose the server holds after clamping, and whether this session had been displaced. */
+export type PresenceSyncResult = {
+    pose: {
+        x: number;
+        y: number;
+        z: number;
+        rotationY: number;
+        rotationPitch: number;
+    };
+    lastSeenAt: number;
+    displaced: boolean;
+};
+/**
+ * The pose lane of a hosted server: the backend behind `PresenceSync`, which replicates where each
+ * member of one `jgGameServers` server is standing. It is not the backend for `PresenceTransport` —
+ * that contract (`ConvexPresenceFunctions` in `./convexPresenceTransport`) is a game-owned world's
+ * own presence, keyed by the game's own ids, with its own notion of who counts as a resident. A game
+ * on `createConvexPresenceTransport` supplies those functions itself; these do not substitute for them.
+ * @internal
+ */
 export declare function createPresenceFunctions(options?: {
     auth?: JgAuthMode;
+    /** How recently a row must have been written to appear in `list`. */
     freshWindowMs?: number;
-    poseRules?: PoseSyncRules;
+    /** How long a row may go unwritten before `reapIdlePresence` deletes it. */
+    idleCutoffMs?: number;
+    /** Rows deleted per reaper run, so one sweep is a bounded transaction. */
+    maxReapPerRun?: number;
+    /** Movement clamping, optionally per actor `kind` — an agent need not obey a human's speed cap. */
+    poseRules?: PoseSyncRules | ((kind: string | undefined) => PoseSyncRules);
+    /** Where a session with no row starts. Async and ctx-bearing, so a spawn can read the world. */
+    resolveSpawn?: (ctx: JGMutationCtx, args: {
+        serverId: string;
+        userId: string;
+        kind?: string;
+    }) => Promise<{
+        x: number;
+        y: number;
+        z: number;
+    } | null> | {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
 }): {
     list: import("convex/server").RegisteredQuery<"public", {
         externalId?: string | undefined;
         serverId: string;
-    }, Promise<{
-        userId: string;
-        position: {
-            x: number;
-            y: number;
-            z: number;
-        };
-        rotationY: number;
-        rotationPitch: number;
-        lastSeenAt: number;
-    }[]>>;
+    }, Promise<PresenceListRow[]>>;
     sync: import("convex/server").RegisteredMutation<"public", {
         externalId?: string | undefined;
-        pose: {
+        kind?: string | undefined;
+        label?: string | undefined;
+        pose?: {
             rotationPitch: number;
             rotationY: number;
             x: number;
             y: number;
             z: number;
-        };
+        } | undefined;
         serverId: string;
-    }, Promise<null>>;
+        sessionId?: string | undefined;
+    }, Promise<PresenceSyncResult | null>>;
     leave: import("convex/server").RegisteredMutation<"public", {
         externalId?: string | undefined;
         serverId: string;
+        sessionId?: string | undefined;
     }, Promise<null>>;
+    reapIdlePresence: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
+        reaped: number;
+    }>>;
 };
 /** @internal */
 export declare function createChatFunctions(options?: {
@@ -622,7 +773,9 @@ export declare function createChatFunctions(options?: {
 export type JgCronSpec = {
     name: string;
     intervalSeconds: number;
-    functionKey: "tickActiveServers" | "flushDirtyServers";
+    functionKey: "tickActiveServers" | "flushDirtyServers" | "reapIdlePresence";
+    /** Which factory's exports the function lives in, i.e. which `convex/*.ts` file to reach it through. */
+    module: "runtime" | "presence";
 };
 /** @internal */
 export declare function jgengineCronSpecs(): readonly JgCronSpec[];