@jgengine/convex 0.10.0 → 0.12.0

package/README.md

@@ -11,7 +11,7 @@ import { resolveConvexMultiplayer } from "@jgengine/convex/resolveConvexMultipla
 
 const session = resolveConvexMultiplayer({
   game: myGame,
-  gameId: "voxel-mine",
+  gameId: "my-game",
   url: import.meta.env.VITE_CONVEX_URL,
   force: import.meta.env.VITE_CONVEX_URL !== undefined,
 });
@@ -44,6 +44,6 @@ No game-specific code lives there — any JGengine game can point at the same de
 
 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) and `Games/voxel-mine` for a game that declares `multiplayer: convex({ topology: "shared" })`. 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.
+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.
 
-Part of [JGengine](https://github.com/Noisemaker111/jgengine). AGPL-3.0-only.
+Part of [JGengine](https://github.com/Noisemaker111/jgengine). Apache-2.0.

package/dist/convexSaveBackend.d.ts

@@ -0,0 +1,35 @@
+import type { ConvexReactClient } from "convex/react";
+import type { FunctionReference } from "convex/server";
+import { type SaveBackend } from "@jgengine/core/game/saveStore";
+/** 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. */
+export interface ConvexSaveFunctions {
+    read: FunctionReference<"query", "public", {
+        key: string;
+    }, string | null>;
+    write: FunctionReference<"mutation", "public", {
+        key: string;
+        value: string;
+    }, unknown>;
+    remove: FunctionReference<"mutation", "public", {
+        key: string;
+    }, unknown>;
+}
+/** Default `saves.read` / `saves.write` / `saves.remove` refs for apps that follow the convention — pass your own `functions` to override. */
+export declare function defaultConvexSaveFunctions(): ConvexSaveFunctions;
+/** Config for {@link createConvexSaveBackend} — the Convex client, optional function refs (defaults to the `saves.*` convention), and an optional key `namespace`. */
+export interface ConvexSaveBackendOptions {
+    client: ConvexReactClient;
+    /** The read/write/remove function refs; defaults to the `saves.*` convention. */
+    functions?: ConvexSaveFunctions;
+    /** Prefix every key so multiple games or users can share one `saves` table. */
+    namespace?: string;
+}
+/**
+ * A cloud {@link SaveBackend} backed by Convex — reads through a query and
+ * writes through mutations, so a {@link createSaveStore} configured with it
+ * saves to the server instead of `localStorage`. The only change from an offline
+ * game is swapping the backend; autosave, slots, and migration behave the same.
+ *
+ * @capability convex-save save a game to Convex (cloud) through the SaveBackend seam
+ */
+export declare function createConvexSaveBackend(options: ConvexSaveBackendOptions): SaveBackend;

package/dist/convexSaveBackend.js

@@ -0,0 +1,24 @@
+import { anyApi } from "convex/server";
+import { remoteSaveBackend } from "@jgengine/core/game/saveStore";
+/** Default `saves.read` / `saves.write` / `saves.remove` refs for apps that follow the convention — pass your own `functions` to override. */
+export function defaultConvexSaveFunctions() {
+    return anyApi.saves;
+}
+/**
+ * A cloud {@link SaveBackend} backed by Convex — reads through a query and
+ * writes through mutations, so a {@link createSaveStore} configured with it
+ * saves to the server instead of `localStorage`. The only change from an offline
+ * game is swapping the backend; autosave, slots, and migration behave the same.
+ *
+ * @capability convex-save save a game to Convex (cloud) through the SaveBackend seam
+ */
+export function createConvexSaveBackend(options) {
+    const functions = options.functions ?? defaultConvexSaveFunctions();
+    const prefix = options.namespace === undefined ? "" : `${options.namespace}:`;
+    const scope = (key) => `${prefix}${key}`;
+    return remoteSaveBackend({
+        read: (key) => options.client.query(functions.read, { key: scope(key) }),
+        write: (key, value) => options.client.mutation(functions.write, { key: scope(key), value }).then(() => undefined),
+        remove: (key) => options.client.mutation(functions.remove, { key: scope(key) }).then(() => undefined),
+    });
+}

package/dist/hostedServer.d.ts

@@ -1,5 +1,5 @@
 import type { GameDefinition } from "@jgengine/core/game/defineGame";
-import type { GameContextContent } from "@jgengine/core/runtime/gameContext";
+import type { GameContextContent, GameContextModels } from "@jgengine/core/runtime/gameContext";
 import { type InputFrame } from "@jgengine/core/runtime/hostedGameRunner";
 import { type HostedWorldSession, type HostedWorldStore } from "@jgengine/core/runtime/hostedWorldSession";
 import type { ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
@@ -8,6 +8,8 @@ import { type JgAuthMode } from "./server.js";
 export interface HostedGameConfig {
     definition: GameDefinition<ModelAssetRef, unknown>;
     content: GameContextContent;
+    /** Render-model lookup for collider auto-fit — pass the same lookup the shell derives (`contextModels(playable)`) so the authoritative host resolves the hitboxes clients see. */
+    models?: GameContextModels;
 }
 /**
  * Everything one stateless invocation reconstructs a hosted world from: the persisted record via `store`,
@@ -32,7 +34,8 @@ export interface HostedWorldOutcome<T> {
  * The reconstruct → op → save core of the stateless hosted path, Convex-agnostic so it unit-tests against
  * `memoryWorldStore`: build a fresh {@link createHostedWorldSession} from `store.load()`, resume persisted
  * members and replay held inputs, run the op, then persist the snapshot at `revision + 1` iff the world changed.
- */
+  * @internal
+  */
 export declare function invokeHostedWorld<T>(invocation: HostedWorldInvocation<T>): HostedWorldOutcome<T>;
 /** Default minimum elapsed ms before `tickHostedWorlds` advances a world — override via the factory's `tickMs`. */
 export declare const JG_HOSTED_TICK_MS = 1000;
@@ -41,7 +44,8 @@ export declare const JG_HOSTED_TICK_MS = 1000;
  * reconstructing a hosted session from the persisted `jgHostedWorlds` row on every invocation via
  * {@link invokeHostedWorld}. Destructure + re-export the returned functions from a `convex/` module and
  * drive `tickHostedWorlds` from a cron. Requires {@link jgengineHostedTables} in the deployment schema.
- */
+  * @internal
+  */
 export declare function createHostedGameServerFunctions(options: {
     games: Record<string, HostedGameConfig>;
     auth?: JgAuthMode;

package/dist/hostedServer.js

@@ -8,7 +8,8 @@ import { jgengineHostedTables, resolveActor } from "./server.js";
  * The reconstruct → op → save core of the stateless hosted path, Convex-agnostic so it unit-tests against
  * `memoryWorldStore`: build a fresh {@link createHostedWorldSession} from `store.load()`, resume persisted
  * members and replay held inputs, run the op, then persist the snapshot at `revision + 1` iff the world changed.
- */
+  * @internal
+  */
 export function invokeHostedWorld(invocation) {
     const { game, store, members = [], inputs = {}, now, op } = invocation;
     const loaded = store.load();
@@ -18,6 +19,7 @@ export function invokeHostedWorld(invocation) {
         content: game.content,
         store: { load: () => loaded, save: () => { } },
         ...(now === undefined ? {} : { now }),
+        ...(game.models === undefined ? {} : { models: game.models }),
     });
     for (const userId of members)
         session.runner().resume(userId);
@@ -94,7 +96,8 @@ async function persistWorldRow(ctx, args) {
  * reconstructing a hosted session from the persisted `jgHostedWorlds` row on every invocation via
  * {@link invokeHostedWorld}. Destructure + re-export the returned functions from a `convex/` module and
  * drive `tickHostedWorlds` from a cron. Requires {@link jgengineHostedTables} in the deployment schema.
- */
+  * @internal
+  */
 export function createHostedGameServerFunctions(options) {
     const mode = options.auth ?? "anonymous";
     const tickMs = options.tickMs ?? JG_HOSTED_TICK_MS;
@@ -302,7 +305,10 @@ export function createHostedGameServerFunctions(options) {
         args: {},
         handler: async (ctx) => {
             const nowMs = Date.now();
-            const rows = await ctx.db.query("jgHostedWorlds").collect();
+            const rows = await ctx.db
+                .query("jgHostedWorlds")
+                .withIndex("by_tick_anchor", (q) => q.lte("tickAnchorMs", nowMs - tickMs))
+                .collect();
             let ticked = 0;
             let saved = 0;
             for (const row of rows) {
@@ -312,8 +318,6 @@ export function createHostedGameServerFunctions(options) {
                 if (row.memberUserIds.length === 0)
                     continue;
                 const elapsedMs = nowMs - row.tickAnchorMs;
-                if (elapsedMs < tickMs)
-                    continue;
                 const { store, captured } = worldStoreForRow(row);
                 const outcome = invokeHostedWorld({
                     game,

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./convexChatTransport.js";
 export * from "./convexPresenceTransport.js";
 export * from "./createConvexBackend.js";
+export * from "./convexSaveBackend.js";
 export * from "./createConvexGameTransport.js";
 export * from "./hostedServer.js";
 export * from "./occ.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "./convexChatTransport.js";
 export * from "./convexPresenceTransport.js";
 export * from "./createConvexBackend.js";
+export * from "./convexSaveBackend.js";
 export * from "./createConvexGameTransport.js";
 export * from "./hostedServer.js";
 export * from "./occ.js";

package/dist/occ.d.ts

@@ -1,12 +1,14 @@
 import type { GameRuntime } from "@jgengine/core/runtime/gameRuntime";
 import type { GameRuntimeSnapshot } from "@jgengine/core/runtime/snapshot";
 export declare const REVISION_CONFLICT_REASON = "Revision conflict";
+/** @internal */
 export declare function commitIfRevisionMatch(loadedRevision: number, currentRevision: number): {
     ok: true;
 } | {
     ok: false;
     reason: string;
 };
+/** @internal */
 export declare function applyCommandWithOcc(args: {
     loadedRevision: number;
     currentRevision: number;

package/dist/occ.js

@@ -1,10 +1,12 @@
 export const REVISION_CONFLICT_REASON = "Revision conflict";
+/** @internal */
 export function commitIfRevisionMatch(loadedRevision, currentRevision) {
     if (currentRevision !== loadedRevision) {
         return { ok: false, reason: REVISION_CONFLICT_REASON };
     }
     return { ok: true };
 }
+/** @internal */
 export function applyCommandWithOcc(args) {
     const gate = commitIfRevisionMatch(args.loadedRevision, args.currentRevision);
     if (!gate.ok)

package/dist/server.d.ts

@@ -5,6 +5,9 @@ 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";
+/** @internal Re-export shared host-policy pure helpers so existing convex imports keep working. */
+export { canJoinPrivateServer, isListablePublicly, } from "@jgengine/core/runtime/hostPolicy";
+/** @internal */
 export declare function jgengineTables(): {
     jgGameServers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
@@ -55,7 +58,9 @@ export declare function jgengineTables(): {
         createdAt: import("convex/values").VFloat64<number, "required">;
         updatedAt: import("convex/values").VFloat64<number, "required">;
     }, "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_status: ["status", "_creationTime"];
     }, {}, {}>;
     jgPlayerProfiles: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
@@ -167,7 +172,8 @@ export declare function jgengineTables(): {
  * Convex table for the hosted GameContext-world path: one row per (gameId, serverId) holding the full
  * `WorldSnapshot` blob, its revision, the member roster, and each member's held input. A sibling of
  * {@link jgengineTables} — spread either (or both) into `defineSchema`.
- */
+  * @internal
+  */
 export declare function jgengineHostedTables(): {
     jgHostedWorlds: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
@@ -191,6 +197,7 @@ export declare function jgengineHostedTables(): {
         updatedAt: import("convex/values").VFloat64<number, "required">;
     }, "required", "createdAt" | "gameId" | "inputs" | "memberUserIds" | "revision" | "serverId" | "snapshot" | "tickAnchorMs" | "updatedAt" | `inputs.${string}` | `snapshot.${string}`>, {
         by_game_and_server: ["gameId", "serverId", "_creationTime"];
+        by_tick_anchor: ["tickAnchorMs", "_creationTime"];
     }, {}, {}>;
 };
 declare const schemaForTypes: import("convex/server").SchemaDefinition<{
@@ -243,7 +250,9 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         createdAt: import("convex/values").VFloat64<number, "required">;
         updatedAt: import("convex/values").VFloat64<number, "required">;
     }, "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_status: ["status", "_creationTime"];
     }, {}, {}>;
     jgPlayerProfiles: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
@@ -355,12 +364,16 @@ type JGDataModel = DataModelFromSchemaDefinition<typeof schemaForTypes>;
 type JGMutationCtx = GenericMutationCtx<JGDataModel>;
 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`. */
+/** 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`.
+ * @internal
+ */
 export declare function resolveActor(ctx: {
     auth: Auth;
 }, claimedExternalId: string | undefined, mode: JgAuthMode): Promise<string | null>;
+/** @internal */
 export declare function applyLeaderboardIncrements(ctx: JGMutationCtx, gameId: string, entries: LeaderboardIncrement[]): Promise<void>;
 export declare const JG_RUNTIME_TICK_MS = 1000;
+/** @internal */
 export declare function createGameServerFunctions(options?: {
     runtimes?: GameRuntime[];
     auth?: JgAuthMode;
@@ -460,6 +473,7 @@ export declare function createGameServerFunctions(options?: {
         saved: number;
     }>>;
 };
+/** @internal */
 export declare function createLeaderboardFunctions(options?: {
     auth?: JgAuthMode;
 }): {
@@ -490,6 +504,7 @@ export declare function createLeaderboardFunctions(options?: {
         gameId: string;
     }, Promise<null>>;
 };
+/** @internal */
 export declare function createPresenceFunctions(options?: {
     auth?: JgAuthMode;
     freshWindowMs?: number;
@@ -525,6 +540,7 @@ export declare function createPresenceFunctions(options?: {
         serverId: string;
     }, Promise<null>>;
 };
+/** @internal */
 export declare function createChatFunctions(options?: {
     auth?: JgAuthMode;
     historyLimit?: number;
@@ -548,5 +564,5 @@ export type JgCronSpec = {
     intervalSeconds: number;
     functionKey: "tickActiveServers" | "flushDirtyServers";
 };
+/** @internal */
 export declare function jgengineCronSpecs(): readonly JgCronSpec[];
-export {};