@jgengine/convex 0.10.0 → 0.11.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

@@ -32,7 +32,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 +42,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();
@@ -94,7 +95,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 +304,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 +317,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

@@ -4,7 +4,8 @@ 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 { LeaderboardIncrement, SessionVisibility } from "@jgengine/core/runtime/hostPersistence";
+/** @internal */
 export declare function jgengineTables(): {
     jgGameServers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
@@ -55,7 +56,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 +170,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 +195,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 +248,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 +362,28 @@ 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>;
+/** True when a server's `visibility` should surface in public listings/browse results.
+ * @internal
+ */
+export declare function isListablePublicly(visibility: SessionVisibility | undefined): boolean;
+/** A non-member may enter a private server only by presenting its `joinCode`; members always pass.
+ * @internal
+ */
+export declare function canJoinPrivateServer(args: {
+    isMember: boolean;
+    joinCode: string | undefined;
+    suppliedCode: string | undefined;
+}): boolean;
+/** @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 +483,7 @@ export declare function createGameServerFunctions(options?: {
         saved: number;
     }>>;
 };
+/** @internal */
 export declare function createLeaderboardFunctions(options?: {
     auth?: JgAuthMode;
 }): {
@@ -490,6 +514,7 @@ export declare function createLeaderboardFunctions(options?: {
         gameId: string;
     }, Promise<null>>;
 };
+/** @internal */
 export declare function createPresenceFunctions(options?: {
     auth?: JgAuthMode;
     freshWindowMs?: number;
@@ -525,6 +550,7 @@ export declare function createPresenceFunctions(options?: {
         serverId: string;
     }, Promise<null>>;
 };
+/** @internal */
 export declare function createChatFunctions(options?: {
     auth?: JgAuthMode;
     historyLimit?: number;
@@ -548,5 +574,6 @@ export type JgCronSpec = {
     intervalSeconds: number;
     functionKey: "tickActiveServers" | "flushDirtyServers";
 };
+/** @internal */
 export declare function jgengineCronSpecs(): readonly JgCronSpec[];
 export {};

package/dist/server.js

@@ -1,6 +1,7 @@
 import { defineSchema, defineTable, internalMutationGeneric, mutationGeneric, queryGeneric, } from "convex/server";
 import { ConvexError, v } from "convex/values";
 import { createFeedWriteGate, validateFeedWrite, } from "@jgengine/core/multiplayer/feedWriteGate";
+import { normalizeJoinCode } from "@jgengine/core/multiplayer/matchmaking";
 import { decidePoseSync, spawnPresenceState, } from "@jgengine/core/multiplayer/presenceModel";
 import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
 import { buildHydratePlayers, planServerPersist, shouldAutoSave, trimFeedEntries } from "@jgengine/core/runtime/hostPersistence";
@@ -10,6 +11,7 @@ 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")),
 }));
+/** @internal */
 export function jgengineTables() {
     return {
         jgGameServers: defineTable({
@@ -30,7 +32,10 @@ export function jgengineTables() {
             dirtyAt: v.optional(v.number()),
             createdAt: v.number(),
             updatedAt: v.number(),
-        }).index("by_game_and_status", ["gameId", "status"]),
+        })
+            .index("by_game_and_status", ["gameId", "status"])
+            .index("by_status", ["status"])
+            .index("by_dirty", ["dirtyAt"]),
         jgPlayerProfiles: defineTable({
             userId: v.string(),
             gameId: v.string(),
@@ -91,7 +96,8 @@ export 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 function jgengineHostedTables() {
     return {
         jgHostedWorlds: defineTable({
@@ -104,7 +110,9 @@ export function jgengineHostedTables() {
             tickAnchorMs: v.number(),
             createdAt: v.number(),
             updatedAt: v.number(),
-        }).index("by_game_and_server", ["gameId", "serverId"]),
+        })
+            .index("by_game_and_server", ["gameId", "serverId"])
+            .index("by_tick_anchor", ["tickAnchorMs"]),
     };
 }
 const schemaForTypes = defineSchema(jgengineTables());
@@ -118,7 +126,9 @@ export const DEFAULT_CONVEX_POSE_RULES = {
     maxElapsedSec: 0.5,
     keepAliveRefreshMs: 10_000,
 };
-/** 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 async function resolveActor(ctx, claimedExternalId, mode) {
     const identity = await ctx.auth.getUserIdentity();
     if (identity !== null) {
@@ -134,6 +144,22 @@ export async function resolveActor(ctx, claimedExternalId, mode) {
     }
     return null;
 }
+/** True when a server's `visibility` should surface in public listings/browse results.
+ * @internal
+ */
+export function isListablePublicly(visibility) {
+    return (visibility ?? "public") !== "private";
+}
+/** A non-member may enter a private server only by presenting its `joinCode`; members always pass.
+ * @internal
+ */
+export function canJoinPrivateServer(args) {
+    if (args.isMember)
+        return true;
+    if (args.joinCode === undefined || args.suppliedCode === undefined)
+        return false;
+    return normalizeJoinCode(args.suppliedCode) === normalizeJoinCode(args.joinCode);
+}
 async function requireServerMember(ctx, serverId, actorUserId) {
     const server = await ctx.db.get("jgGameServers", serverId);
     if (!server)
@@ -223,6 +249,7 @@ async function loadServerSnapshot(ctx, server, runtime) {
         revision: server.revision,
     });
 }
+/** @internal */
 export async function applyLeaderboardIncrements(ctx, gameId, entries) {
     const now = Date.now();
     for (const entry of entries) {
@@ -324,6 +351,7 @@ async function flushServerIfDue(ctx, server, now, runtime) {
     return true;
 }
 export const JG_RUNTIME_TICK_MS = 1_000;
+/** @internal */
 export function createGameServerFunctions(options) {
     const mode = options?.auth ?? "required";
     const hostSlotsPerServer = options?.slotsPerServer ?? 16;
@@ -404,8 +432,11 @@ export function createGameServerFunctions(options) {
                 throw new ConvexError("Server is full");
             }
             if ((server.visibility ?? "public") === "private" &&
-                !server.memberUserIds.includes(actorUserId) &&
-                args.serverId === undefined) {
+                !canJoinPrivateServer({
+                    isMember: server.memberUserIds.includes(actorUserId),
+                    joinCode: server.joinCode,
+                    suppliedCode: args.joinCode,
+                })) {
                 throw new ConvexError("Server is private");
             }
             const profile = await ctx.db
@@ -691,11 +722,15 @@ export function createGameServerFunctions(options) {
             updatedAt: v.number(),
         })),
         handler: async (ctx, args) => {
+            const limit = args.limit ?? 20;
             const rows = await ctx.db
                 .query("jgGameServers")
                 .withIndex("by_game_and_status", (q) => q.eq("gameId", args.gameId).eq("status", "running"))
-                .take(args.limit ?? 20);
-            return rows.map((row) => ({
+                .take(Math.min(limit * 4, 200));
+            return rows
+                .filter((row) => isListablePublicly(row.visibility))
+                .slice(0, limit)
+                .map((row) => ({
                 _id: row._id,
                 status: row.status,
                 memberCount: row.memberUserIds.length,
@@ -709,12 +744,13 @@ export function createGameServerFunctions(options) {
         args: {},
         handler: async (ctx) => {
             const now = Date.now();
-            const servers = await ctx.db.query("jgGameServers").collect();
+            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.status !== "running")
-                    continue;
                 if (server.memberUserIds.length === 0)
                     continue;
                 const elapsedMs = now - server.tickAnchorMs;
@@ -738,11 +774,12 @@ export function createGameServerFunctions(options) {
         args: {},
         handler: async (ctx) => {
             const now = Date.now();
-            const servers = await ctx.db.query("jgGameServers").collect();
+            const servers = await ctx.db
+                .query("jgGameServers")
+                .withIndex("by_dirty", (q) => q.gt("dirtyAt", 0))
+                .collect();
             let saved = 0;
             for (const server of servers) {
-                if (server.dirtyAt === undefined)
-                    continue;
                 const runtime = resolveRuntime(registry, server.gameId);
                 const snapshot = await loadServerSnapshot(ctx, server, runtime);
                 await persistServerSnapshot(ctx, server, clearDirtyFlags(snapshot), server.save);
@@ -768,6 +805,7 @@ export function createGameServerFunctions(options) {
 }
 const leaderboardScopeValidator = v.union(v.literal("global"), v.literal("server"), v.literal("profile"));
 const MAX_LEADERBOARD_TOP_LIMIT = 100;
+/** @internal */
 export function createLeaderboardFunctions(options) {
     void options;
     const getTop = query({
@@ -831,6 +869,7 @@ export function createLeaderboardFunctions(options) {
     });
     return { getTop, getProfile, incrementMany };
 }
+/** @internal */
 export function createPresenceFunctions(options) {
     const mode = options?.auth ?? "required";
     const freshWindowMs = options?.freshWindowMs ?? 10_000;
@@ -946,6 +985,7 @@ export function createPresenceFunctions(options) {
     });
     return { list, sync, leave };
 }
+/** @internal */
 export function createChatFunctions(options) {
     const mode = options?.auth ?? "required";
     const historyLimit = options?.historyLimit ?? 100;
@@ -1041,6 +1081,7 @@ const JG_CRON_SPECS = [
     { name: "jg tick", intervalSeconds: 1, functionKey: "tickActiveServers" },
     { name: "jg flush", intervalSeconds: 60, functionKey: "flushDirtyServers" },
 ];
+/** @internal */
 export function jgengineCronSpecs() {
     return JG_CRON_SPECS;
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@jgengine/convex",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Convex adapters for JGengine: game transport, presence transport, and backend wiring over @jgengine/core.",
-  "license": "AGPL-3.0-only",
+  "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "repository": {
@@ -13,7 +13,7 @@
   "files": [
     "dist",
     "CHANGELOG.md",
-    "llms.txt"
+    "skills"
   ],
   "exports": {
     ".": {
@@ -30,7 +30,7 @@
     "check-types": "tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.10.0"
+    "@jgengine/core": "^0.11.0"
   },
   "peerDependencies": {
     "convex": "^1.31.2",

package/skills/jgengine/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: jgengine
+description: Route game work to the smallest useful JGengine guidance set.
+---
+
+# JGengine intake and router
+
+Read the repository [README](../../../README.md) for package truth, commands, layering, and license. This skill decides what to load; it is not an engine manual.
+
+## 1. Establish the target
+
+Capture only decisions that change architecture:
+
+- player point of view and controls
+- world shape and authored content
+- core loop, interaction, combat, and progression
+- solo, local, hosted, or persistent multiplayer
+- HUD/menu states and art direction
+- one observable completion scenario
+
+For a new in-repo game, scaffold with `bun run new:game <id> --name "Title"`. Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+
+## 2. Select domains
+
+Load only rows the target needs. Do not preload every domain.
+
+| Need | Skill | Owner |
+| --- | --- | --- |
+| scene placement, terrain painting, paths, asset authoring | `jgengine-editor` | editor document and authoring tools |
+| runtime world, movement, input, interaction, AI, navigation, audio | `jgengine-world` | spatial simulation and world runtime |
+| game state, systems, inventory, crafting, quests, economy, turns | `jgengine-gameplay` | non-combat rules and state |
+| targeting, stats, damage, effects, abilities, projectiles, loot | `jgengine-combat` | combat resolution |
+| HUD, menus, layout, accessibility, touch presentation | `jgengine-ui` | player-facing interface |
+| models, sprites, materials, audio files, source licensing | `jgengine-assets` | asset discovery and catalogs |
+| authority, transport, replication, sessions, host persistence | `jgengine-multiplayer` | network topology and persistence adapters |
+
+Scenes normally require both `jgengine-editor` for authoring and `jgengine-world` for runtime consumption. Combat and multiplayer are opt-in, not default intake.
+
+## 3. Discover before designing
+
+Within each selected domain:
+
+1. Search `capabilities.md` by intent; it maps needs to imports.
+2. Open `api.md` only when exact signatures or export inventory are needed.
+3. Open the linked reference only for a deeper recipe or trap.
+
+If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.
+
+## 4. Build and finish
+
+Keep scene coordinates in the editor document, state serializable, randomness injected, and hot-path work bounded. Use `jgengine-verify` for evidence appropriate to the change. Inside this monorepo, `workflow` owns issue/PR completion. Visual polish work also uses the `jgengine-ui` quality reference.