@jgengine/convex 0.49.1 → 0.51.0

package/dist/server.d.ts

@@ -16,13 +16,13 @@ export { JG_MAX_MEMBERS_PER_SERVER, canJoinPrivateServer, isListablePublicly, va
 export declare function jgengineTables(): {
     jgGameServers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         gameId: string;
-        joinCode?: string | undefined;
-        lastSavedAt?: number | undefined;
-        memberCount?: number | undefined;
+        joinCode?: string;
+        lastSavedAt?: number;
+        memberCount?: number;
         memberUserIds: string[];
-        mode?: string | undefined;
+        mode?: string;
         modeConfig?: any;
         revision: number;
         save: "none" | {
@@ -34,9 +34,9 @@ export declare function jgengineTables(): {
         slotsPerServer: number;
         status: "closed" | "open" | "running";
         tickAnchorMs: number;
-        topology?: "rooms" | "shared" | undefined;
+        topology?: "rooms" | "shared";
         updatedAt: number;
-        visibility?: "private" | "public" | undefined;
+        visibility?: "private" | "public";
     }, {
         gameId: import("convex/values").VString<string, "required">;
         status: import("convex/values").VUnion<"closed" | "open" | "running", [import("convex/values").VLiteral<"open", "required">, import("convex/values").VLiteral<"running", "required">, import("convex/values").VLiteral<"closed", "required">], "required", never>;
@@ -75,7 +75,7 @@ export declare function jgengineTables(): {
     jgServerCapacity: import("convex/server").TableDefinition<import("convex/values").VObject<{
         gameId: string;
         memberCount: number;
-        mode?: string | undefined;
+        mode?: string;
         serverId: GenericId<"jgGameServers">;
         slotsPerServer: number;
         status: "closed" | "open" | "running";
@@ -92,7 +92,7 @@ export declare function jgengineTables(): {
     jgServerMembers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         joinedAt: number;
         serverId: GenericId<"jgGameServers">;
-        sessionIds?: string[] | undefined;
+        sessionIds?: string[];
         userId: string;
     }, {
         serverId: import("convex/values").VId<GenericId<"jgGameServers">, "required">;
@@ -133,11 +133,11 @@ export declare function jgengineTables(): {
     }, {}, {}>;
     jgPlayerProfiles: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         gameId: string;
         playerState: any;
         revision: number;
-        sessionServerId?: GenericId<"jgGameServers"> | undefined;
+        sessionServerId?: GenericId<"jgGameServers">;
         sessionState?: any;
         updatedAt: number;
         userId: string;
@@ -156,7 +156,7 @@ export declare function jgengineTables(): {
     }, {}, {}>;
     jgWorldChunks: import("convex/server").TableDefinition<import("convex/values").VObject<{
         chunkKey: string;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         serverId: GenericId<"jgGameServers">;
         snapshot: any;
         updatedAt: number;
@@ -173,7 +173,7 @@ export declare function jgengineTables(): {
     jgLeaderboardRows: import("convex/server").TableDefinition<import("convex/values").VObject<{
         gameId: string;
         scope: "global" | "profile" | "server";
-        serverId?: GenericId<"jgGameServers"> | undefined;
+        serverId?: GenericId<"jgGameServers">;
         stat: string;
         updatedAt: number;
         userId: string;
@@ -204,17 +204,17 @@ export declare function jgengineTables(): {
         by_server_and_action: ["serverId", "action", "_creationTime"];
     }, {}, {}>;
     jgPoses: import("convex/server").TableDefinition<import("convex/values").VObject<{
-        chunkKey?: string | undefined;
-        homeGameId?: string | undefined;
-        kind?: string | undefined;
-        label?: string | undefined;
-        lastWorldSnapshotAt?: number | undefined;
-        ownerActorId?: string | undefined;
-        revokedAt?: number | undefined;
+        chunkKey?: string;
+        homeGameId?: string;
+        kind?: string;
+        label?: string;
+        lastWorldSnapshotAt?: number;
+        ownerActorId?: string;
+        revokedAt?: number;
         rotationPitch: number;
         rotationY: number;
         serverId: string;
-        sessionId?: string | undefined;
+        sessionId?: string;
         updatedAt: number;
         userId: string;
         x: number;
@@ -255,7 +255,7 @@ export declare function jgengineTables(): {
     }, {}, {}>;
     jgChatMessages: import("convex/server").TableDefinition<import("convex/values").VObject<{
         at: number;
-        authorName?: string | undefined;
+        authorName?: string;
         body: string;
         channelId: string;
         serverId: string;
@@ -307,13 +307,13 @@ export declare function jgengineHostedTables(): {
 declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     jgGameServers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         gameId: string;
-        joinCode?: string | undefined;
-        lastSavedAt?: number | undefined;
-        memberCount?: number | undefined;
+        joinCode?: string;
+        lastSavedAt?: number;
+        memberCount?: number;
         memberUserIds: string[];
-        mode?: string | undefined;
+        mode?: string;
         modeConfig?: any;
         revision: number;
         save: "none" | {
@@ -325,9 +325,9 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         slotsPerServer: number;
         status: "closed" | "open" | "running";
         tickAnchorMs: number;
-        topology?: "rooms" | "shared" | undefined;
+        topology?: "rooms" | "shared";
         updatedAt: number;
-        visibility?: "private" | "public" | undefined;
+        visibility?: "private" | "public";
     }, {
         gameId: import("convex/values").VString<string, "required">;
         status: import("convex/values").VUnion<"closed" | "open" | "running", [import("convex/values").VLiteral<"open", "required">, import("convex/values").VLiteral<"running", "required">, import("convex/values").VLiteral<"closed", "required">], "required", never>;
@@ -366,7 +366,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     jgServerCapacity: import("convex/server").TableDefinition<import("convex/values").VObject<{
         gameId: string;
         memberCount: number;
-        mode?: string | undefined;
+        mode?: string;
         serverId: GenericId<"jgGameServers">;
         slotsPerServer: number;
         status: "closed" | "open" | "running";
@@ -383,7 +383,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     jgServerMembers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         joinedAt: number;
         serverId: GenericId<"jgGameServers">;
-        sessionIds?: string[] | undefined;
+        sessionIds?: string[];
         userId: string;
     }, {
         serverId: import("convex/values").VId<GenericId<"jgGameServers">, "required">;
@@ -424,11 +424,11 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     }, {}, {}>;
     jgPlayerProfiles: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         gameId: string;
         playerState: any;
         revision: number;
-        sessionServerId?: GenericId<"jgGameServers"> | undefined;
+        sessionServerId?: GenericId<"jgGameServers">;
         sessionState?: any;
         updatedAt: number;
         userId: string;
@@ -447,7 +447,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     }, {}, {}>;
     jgWorldChunks: import("convex/server").TableDefinition<import("convex/values").VObject<{
         chunkKey: string;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         serverId: GenericId<"jgGameServers">;
         snapshot: any;
         updatedAt: number;
@@ -464,7 +464,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     jgLeaderboardRows: import("convex/server").TableDefinition<import("convex/values").VObject<{
         gameId: string;
         scope: "global" | "profile" | "server";
-        serverId?: GenericId<"jgGameServers"> | undefined;
+        serverId?: GenericId<"jgGameServers">;
         stat: string;
         updatedAt: number;
         userId: string;
@@ -495,17 +495,17 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         by_server_and_action: ["serverId", "action", "_creationTime"];
     }, {}, {}>;
     jgPoses: import("convex/server").TableDefinition<import("convex/values").VObject<{
-        chunkKey?: string | undefined;
-        homeGameId?: string | undefined;
-        kind?: string | undefined;
-        label?: string | undefined;
-        lastWorldSnapshotAt?: number | undefined;
-        ownerActorId?: string | undefined;
-        revokedAt?: number | undefined;
+        chunkKey?: string;
+        homeGameId?: string;
+        kind?: string;
+        label?: string;
+        lastWorldSnapshotAt?: number;
+        ownerActorId?: string;
+        revokedAt?: number;
         rotationPitch: number;
         rotationY: number;
         serverId: string;
-        sessionId?: string | undefined;
+        sessionId?: string;
         updatedAt: number;
         userId: string;
         x: number;
@@ -546,7 +546,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     }, {}, {}>;
     jgChatMessages: import("convex/server").TableDefinition<import("convex/values").VObject<{
         at: number;
-        authorName?: string | undefined;
+        authorName?: string;
         body: string;
         channelId: string;
         serverId: string;
@@ -626,7 +626,7 @@ export type RunCommandOutcome = {
 };
 /** Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper. */
 export type ConvexRunCommandArgs = RunCommandArgs & {
-    externalId?: string;
+    externalId?: string | undefined;
     /**
      * 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.
@@ -662,6 +662,10 @@ export type LoadedServerSnapshot = {
  */
 export type GameServerHelpers = {
     ensureServer: (ctx: JGMutationCtx, gameId: string) => Promise<ServerDoc>;
+    /** The shared singleton world `ensureServer` would return, read without creating it, so a query can scope reads to it. `null` until a player or host mutation creates it. */
+    findServer: (ctx: {
+        db: Pick<JGQueryCtx["db"], "query">;
+    }, gameId: string) => Promise<ServerDoc | null>;
     loadSnapshot: (ctx: JGMutationCtx, serverId: string, scope?: LoadSnapshotScope) => Promise<LoadedServerSnapshot | null>;
     applyCommand: (args: {
         gameId: string;
@@ -723,42 +727,42 @@ export declare function createGameServerFunctions(options?: {
     allowedFeedActions?: readonly string[];
 }): {
     joinServer: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
-        joinCode?: string | undefined;
-        mode?: string | undefined;
+        joinCode?: string;
+        mode?: string;
         modeConfig?: any;
-        serverId?: GenericId<"jgGameServers"> | undefined;
-        sessionId?: string | undefined;
-        visibility?: "private" | "public" | undefined;
+        serverId?: GenericId<"jgGameServers">;
+        sessionId?: string;
+        visibility?: "private" | "public";
     }, Promise<EnsureJoinedOutcome>>;
     leaveServer: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
-        sessionId?: string | undefined;
+        sessionId?: string;
     }, Promise<null>>;
     runCommand: import("convex/server").RegisteredMutation<"public", {
         command: string;
-        externalId?: string | undefined;
+        externalId?: string;
         input: any;
         scope?: {
-            chunkKeys?: string[] | undefined;
-            players?: string[] | undefined;
-        } | undefined;
+            chunkKeys?: string[];
+            players?: string[];
+        };
         serverId: GenericId<"jgGameServers">;
     }, Promise<RunCommandOutcome>>;
     flushSave: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
     }, Promise<boolean>>;
     getServer: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
     }, Promise<{
         _id: GenericId<"jgGameServers">;
         gameId: string;
         status: "closed" | "open" | "running";
-        mode: string | undefined;
+        mode?: string;
         memberUserIds: string[];
         slotsPerServer: number;
         save: "none" | {
@@ -773,30 +777,30 @@ export declare function createGameServerFunctions(options?: {
         updatedAt: number;
     } | null>>;
     getServerMeta: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
-    }, Promise<{
+    }, Promise<import("@jgengine/core/data/definedOnly").DefinedOnly<{
         _id: GenericId<"jgGameServers">;
         gameId: string;
         status: "closed" | "open" | "running";
         mode: string | undefined;
         memberCount: number;
         slotsPerServer: number;
-    } | null>>;
+    }> | null>>;
     getServerCapacity: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
-    }, Promise<{
+    }, Promise<import("@jgengine/core/data/definedOnly").DefinedOnly<{
         _id: GenericId<"jgGameServers">;
         gameId: string;
         status: "closed" | "open" | "running";
         mode: string | undefined;
         memberCount: number;
         slotsPerServer: number;
-    } | null>>;
+    }> | null>>;
     getChunks: import("convex/server").RegisteredQuery<"public", {
         chunkKeys: string[];
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
     }, Promise<{
         chunkKey: string;
@@ -804,7 +808,7 @@ export declare function createGameServerFunctions(options?: {
         updatedAt: number;
     }[]>>;
     getPlayerProfile: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
     }, Promise<{
         userId: string;
@@ -815,27 +819,28 @@ export declare function createGameServerFunctions(options?: {
     } | null>>;
     getFeed: import("convex/server").RegisteredQuery<"public", {
         action: string;
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
     }, Promise<any[]>>;
     pushFeedEntry: import("convex/server").RegisteredMutation<"public", {
         action: string;
         entry: any;
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
     }, Promise<null>>;
     listOpenServers: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
-        limit?: number | undefined;
-    }, Promise<{
+        limit?: number;
+    }, Promise<({
         _id: GenericId<"jgGameServers">;
         status: "closed" | "open" | "running";
         memberCount: number;
         slotsPerServer: number;
-        mode: string | undefined;
         updatedAt: number;
-    }[]>>;
+    } & {
+        mode?: string;
+    })[]>>;
     tickActiveServers: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
         ticked: number;
         saved: number;
@@ -850,18 +855,18 @@ export declare function createLeaderboardFunctions(options?: {
     auth?: JgAuthMode;
 }): {
     getTop: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
-        limit?: number | undefined;
+        limit?: number;
         scope: "global" | "profile" | "server";
-        serverId?: GenericId<"jgGameServers"> | undefined;
+        serverId?: GenericId<"jgGameServers">;
         stat: string;
     }, Promise<{
         userId: string;
         value: number;
     }[]>>;
     getProfile: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
         userId: string;
     }, Promise<Record<string, number>>>;
@@ -869,7 +874,7 @@ export declare function createLeaderboardFunctions(options?: {
         entries: {
             by: number;
             scope: "global" | "profile" | "server";
-            serverId?: GenericId<"jgGameServers"> | undefined;
+            serverId?: GenericId<"jgGameServers">;
             stat: string;
             userId: string;
         }[];
@@ -903,6 +908,17 @@ export type PresenceSyncResult = {
     lastSeenAt: number;
     displaced: boolean;
 };
+/** A live pose row handed to a `checkpoint` writer, so a host can persist its own last-position state. */
+export type PresenceCheckpoint = {
+    userId: string;
+    homeGameId?: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY: number;
+};
 /**
  * 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` —
@@ -925,7 +941,7 @@ export declare function createPresenceFunctions(options?: {
     resolveSpawn?: (ctx: JGMutationCtx, args: {
         serverId: string;
         userId: string;
-        kind?: string;
+        kind?: string | undefined;
     }) => Promise<{
         x: number;
         y: number;
@@ -935,30 +951,38 @@ export declare function createPresenceFunctions(options?: {
         y: number;
         z: number;
     } | null;
+    /**
+     * Persist host-owned last-position state from a live row: on a sync at most once per `intervalMs`
+     * (default 30 s), and always when `leave` ends the row, so a returning player spawns where they stood.
+     */
+    checkpoint?: {
+        intervalMs?: number;
+        write: (ctx: JGMutationCtx, row: PresenceCheckpoint, nowMs: number) => Promise<void>;
+    };
 }): {
     list: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: string;
-        viewerChunkKey?: string | undefined;
+        viewerChunkKey?: string;
     }, Promise<PresenceListRow[]>>;
     sync: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
-        kind?: string | undefined;
-        label?: string | undefined;
+        externalId?: string;
+        kind?: string;
+        label?: string;
         pose?: {
             rotationPitch: number;
             rotationY: number;
             x: number;
             y: number;
             z: number;
-        } | undefined;
+        };
         serverId: string;
-        sessionId?: string | undefined;
+        sessionId?: string;
     }, Promise<PresenceSyncResult | null>>;
     leave: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: string;
-        sessionId?: string | undefined;
+        sessionId?: string;
     }, Promise<null>>;
     reapIdlePresence: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
         reaped: number;
@@ -1033,7 +1057,7 @@ export declare function recentChatMessages(ctx: {
     _creationTime: number;
     _id: GenericId<"jgChatMessages">;
     at: number;
-    authorName?: string | undefined;
+    authorName?: string;
     body: string;
     channelId: string;
     serverId: string;
@@ -1045,19 +1069,19 @@ export declare function recentChatMessages(ctx: {
  */
 export declare function createClientErrorFunctions(): {
     reportClientError: import("convex/server").RegisteredMutation<"public", {
-        agentPrompt?: string | undefined;
-        componentStack?: string | undefined;
-        kind?: string | undefined;
+        agentPrompt?: string;
+        componentStack?: string;
+        kind?: string;
         message: string;
-        pathname?: string | undefined;
-        stack?: string | undefined;
-        url?: string | undefined;
-        userAgent?: string | undefined;
+        pathname?: string;
+        stack?: string;
+        url?: string;
+        userAgent?: string;
     }, Promise<{
         ok: boolean;
         reason: string;
     } | {
-        reason?: undefined;
+        reason?: never;
         ok: boolean;
     }>>;
     pruneClientErrors: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
@@ -1078,18 +1102,18 @@ export declare function createChatFunctions(options?: {
 }): {
     messages: import("convex/server").RegisteredQuery<"public", {
         channelId: string;
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: string;
     }, Promise<ChatMessage[]>>;
     recent: import("convex/server").RegisteredQuery<"public", {
         channelId: string;
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: string;
     }, Promise<ChatMessage[]>>;
     sendMessage: import("convex/server").RegisteredMutation<"public", {
         body: string;
         channelId: string;
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: string;
     }, Promise<ChatSendOutcome>>;
     pruneChatMessages: import("convex/server").RegisteredMutation<"internal", {}, Promise<{