@jgengine/convex 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -12,6 +12,32 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.12.0
+
+### Migrate
+
+- **Author games through `defineGame` from `@jgengine/shell`** — it is the single public authoring entry (and carries the define-game capability tag). Core's constructor was renamed `defineGame` → `defineGameDefinition` (`@jgengine/core/game/defineGame`); only hosts and tooling call it. If you imported `defineGame` from core, switch the import to `@jgengine/shell`. `GamePlayer`/`GamePlayerShell` are `@internal` now — `GameHost` is the documented mount, and it owns the editor summon (`?mode=editor`, F2+E, dev save endpoint), so delete any per-game editor bootstrap.
+- **Declare your world with `world()`** (`@jgengine/core/world/place`): `world({ id, ground: { mode, size, surface? }, physics? })` with `flat` / `round` / `voxel` / `board` ground. New scaffolds emit a thin infinite flat place instead of the old 96 m meadow. `environment()` still works but is demoted to the legacy consumption path for editor-written scene data — **nothing required** for existing games; new worlds should use `world()` and author all dressing in the editor.
+- Everything else is additive — stat pools, minimap marker sources, auction house, city/path generation, editor workspaces require no changes to existing games.
+
+### Added
+
+- **World = place: `world()` API** (#1178) — a world is substrate + laws, not a coded diorama. `@jgengine/core/world/place` ships `world({ id, ground: { mode, size, surface?, generator? }, physics? })`; size is discriminated by mode (flat `{x,z}` with `Infinity` axes, round `{radius}`, voxel generator domain, board `{x,y}` cells — TS and runtime both reject mismatches). `ground.surface` carries matter/feel laws (metal vs slime vs felt) read by the same rule systems; per-place `physics` resolves over the game default; multiple worlds per game are first-class. The shell renders place substrates (`PlaceScene`) under the engine default sky; seeds derive from world id + save via `seedForPlace`.
+- **`@jgengine/shell/gameKit`** — happy-path authoring surface: authoring, mount, stores, systems, authored-scene helpers, HUD primitives, seeded rng in one import.
+- **Portable generic stat pools** — `@jgengine/core/stats/statPool`: bounded named pools (health, energy, heat, ammo…) with the entity-stats integration rebuilt on them; recipe in skill `jgengine-combat`.
+- **Auction-house economy primitives** (#1086) — `@jgengine/core/economy/auctionBook` (timed bid auctions, escrowed bids, outbid refunds, optional buyout, anti-snipe close extension, seller settlement minus house cut) plus market price history.
+- **Portable minimap marker sources** — core world seam feeding game minimaps; recipe in skill `jgengine-ui`.
+- **Unified seed-driven path network + city generation v2** (#1103, #1106) — streets/blocks/buildings with grid-ness, curviness, branching and block-size dials; zone bands, weighted building-class mixes, massing pieces, balance presets, junction-centered clustering, road-derived block polygons and parcels. Shell renders realistic roads: real intersections, curbs, lane lines, tunnels, and roads riding bridge decks.
+- **Physical fidelity** — mesh-accurate hitboxes (shots pass through holes in concave models, #1075), auto-fit entity/object colliders from measured model bounds (#1072), movement obstruction reading fitted boxes + compound-box openings (#1077).
+- **Editor overhaul** (#1110) — materials / lighting / scripting / animation-timeline / multiplayer workspaces, command palette, minimap bake wired end-to-end (#1036), real offscreen GLB thumbnails in the content browser, hierarchy drag-drop + keyboard + context menus + per-object visibility/lock, multi-select inspector, console RPC, asset drag-place, ortho projection, pivot modes, play chrome.
+- **Editor authoring pipeline** — author entity definitions and starter catalogs (#1012), author catalogs/schema fields in the Data tab (#1043), promote an authored scene folder into a runnable game (#1011), authored triggers promoted to a shared primitive with goal/win rules (#1013), asset import rewrites the game's `game/assets.ts` (#1042).
+- **Skills** — research-backed `game-design` and `level-design` skills (#962); every-game-owns-custom-UI invariant codified (#1148).
+
+### Changed
+
+- `npx jgengine create` scaffolds a thin infinite flat `world()` place; the editor `blankWorld` no longer pre-bakes seeded grass. Dressing belongs in `editor.scene.json`.
+- Environment studio visual-quality pass — turf tufts, depth-aware water, relief soil, weathered poles; grass fields no longer rebuild geometry per frame (#1090).
+
 ## 0.11.0
 
 ### Migrate

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`,

package/dist/hostedServer.js

@@ -19,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);

package/dist/server.d.ts

@@ -4,7 +4,9 @@ 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, SessionVisibility } from "@jgengine/core/runtime/hostPersistence";
+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<{
@@ -368,18 +370,6 @@ export declare const DEFAULT_CONVEX_POSE_RULES: PoseSyncRules;
 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;
@@ -576,4 +566,3 @@ export type JgCronSpec = {
 };
 /** @internal */
 export declare function jgengineCronSpecs(): readonly JgCronSpec[];
-export {};

package/dist/server.js

@@ -1,12 +1,14 @@
 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 { DEFAULT_POSE_SYNC_RULES, decidePoseSync, spawnPresenceState, } from "@jgengine/core/multiplayer/presenceModel";
 import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
 import { buildHydratePlayers, planServerPersist, shouldAutoSave, trimFeedEntries } from "@jgengine/core/runtime/hostPersistence";
+import { isAutoJoinCandidate, isListablePublicly, isPrivateJoinBlocked, isServerFull, isServerMember, statusAfterLeave, withJoinedMember, withoutMember, } from "@jgengine/core/runtime/hostPolicy";
 import { clearDirtyFlags, createEmptyServerRow } from "@jgengine/core/runtime/snapshot";
 import { applyCommandWithOcc, commitIfRevisionMatch } from "./occ.js";
+/** @internal Re-export shared host-policy pure helpers so existing convex imports keep working. */
+export { canJoinPrivateServer, isListablePublicly, } from "@jgengine/core/runtime/hostPolicy";
 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")),
@@ -119,13 +121,7 @@ const schemaForTypes = defineSchema(jgengineTables());
 const query = queryGeneric;
 const mutation = mutationGeneric;
 const internalMutation = internalMutationGeneric;
-export const DEFAULT_CONVEX_POSE_RULES = {
-    maxSpeed: 12,
-    maxVerticalOffset: 3,
-    minElapsedSec: 0.05,
-    maxElapsedSec: 0.5,
-    keepAliveRefreshMs: 10_000,
-};
+export const DEFAULT_CONVEX_POSE_RULES = DEFAULT_POSE_SYNC_RULES;
 /** 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
  */
@@ -144,30 +140,38 @@ 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)
         return null;
-    if (!server.memberUserIds.includes(actorUserId))
+    if (!isServerMember(server.memberUserIds, actorUserId))
         return null;
     return server;
 }
+/** Resolve the acting user for a mutation, throwing the standard error when unauthenticated.
+ * @internal
+ */
+async function requireActor(ctx, externalId, mode) {
+    const actorUserId = await resolveActor(ctx, externalId, mode);
+    if (!actorUserId)
+        throw new ConvexError("Not authenticated");
+    return actorUserId;
+}
+/**
+ * Resolve the actor and confirm server membership, invoking `fn` only when both hold and yielding
+ * `deniedResult` for every denial (unauthenticated or non-member). The uniform-denial path shared by
+ * the read handlers whose not-authenticated and not-member cases return the same value.
+ * @internal
+ */
+async function withMember(ctx, mode, args, deniedResult, fn) {
+    const actorUserId = await resolveActor(ctx, args.externalId, mode);
+    if (!actorUserId)
+        return deniedResult;
+    const server = await requireServerMember(ctx, args.serverId, actorUserId);
+    if (server === null)
+        return deniedResult;
+    return fn(server, actorUserId);
+}
 const builtinRuntimeCommands = {
     "engine.ping": {
         validate: (_snapshot) => null,
@@ -372,10 +376,7 @@ export function createGameServerFunctions(options) {
             isNew: v.boolean(),
         }),
         handler: async (ctx, args) => {
-            const actorUserId = await resolveActor(ctx, args.externalId, mode);
-            if (!actorUserId) {
-                throw new ConvexError("Not authenticated");
-            }
+            const actorUserId = await requireActor(ctx, args.externalId, mode);
             const now = Date.now();
             const runtime = resolveRuntime(registry, args.gameId);
             const save = runtime.save;
@@ -397,13 +398,12 @@ export function createGameServerFunctions(options) {
                     joinable.push(...rows);
                 }
                 server =
-                    joinable.find((row) => {
-                        if (row.memberUserIds.includes(actorUserId))
-                            return true;
-                        if (row.memberUserIds.length >= row.slotsPerServer)
-                            return false;
-                        return (row.visibility ?? "public") !== "private";
-                    }) ?? null;
+                    joinable.find((row) => isAutoJoinCandidate({
+                        memberUserIds: row.memberUserIds,
+                        slotsPerServer: row.slotsPerServer,
+                        visibility: row.visibility,
+                        userId: actorUserId,
+                    })) ?? null;
             }
             if (!server) {
                 const serverId = await ctx.db.insert("jgGameServers", {
@@ -427,16 +427,16 @@ export function createGameServerFunctions(options) {
                 if (!server)
                     throw new ConvexError("Failed to create server");
             }
-            if (server.memberUserIds.length >= server.slotsPerServer &&
-                !server.memberUserIds.includes(actorUserId)) {
+            if (isServerFull(server.memberUserIds, server.slotsPerServer, actorUserId)) {
                 throw new ConvexError("Server is full");
             }
-            if ((server.visibility ?? "public") === "private" &&
-                !canJoinPrivateServer({
-                    isMember: server.memberUserIds.includes(actorUserId),
-                    joinCode: server.joinCode,
-                    suppliedCode: args.joinCode,
-                })) {
+            if (isPrivateJoinBlocked({
+                visibility: server.visibility,
+                memberUserIds: server.memberUserIds,
+                userId: actorUserId,
+                joinCode: server.joinCode,
+                suppliedCode: args.joinCode,
+            })) {
                 throw new ConvexError("Server is private");
             }
             const profile = await ctx.db
@@ -444,9 +444,7 @@ export function createGameServerFunctions(options) {
                 .withIndex("by_user_and_game", (q) => q.eq("userId", actorUserId).eq("gameId", args.gameId))
                 .unique();
             const isNew = profile === null;
-            const memberUserIds = server.memberUserIds.includes(actorUserId)
-                ? server.memberUserIds
-                : [...server.memberUserIds, actorUserId];
+            const memberUserIds = withJoinedMember(server.memberUserIds, actorUserId);
             await ctx.db.patch(server._id, {
                 memberUserIds,
                 status: "running",
@@ -469,20 +467,15 @@ export function createGameServerFunctions(options) {
         },
         returns: v.null(),
         handler: async (ctx, args) => {
-            const actorUserId = await resolveActor(ctx, args.externalId, mode);
-            if (!actorUserId) {
-                throw new ConvexError("Not authenticated");
-            }
-            const server = await ctx.db.get("jgGameServers", args.serverId);
-            if (!server)
-                return null;
-            if (!server.memberUserIds.includes(actorUserId))
+            const actorUserId = await requireActor(ctx, args.externalId, mode);
+            const server = await requireServerMember(ctx, args.serverId, actorUserId);
+            if (server === null)
                 return null;
             const now = Date.now();
             const runtime = resolveRuntime(registry, server.gameId);
             const snapshot = await loadServerSnapshot(ctx, server, runtime);
             await persistServerSnapshot(ctx, server, snapshot, server.save);
-            const memberUserIds = server.memberUserIds.filter((id) => id !== actorUserId);
+            const memberUserIds = withoutMember(server.memberUserIds, actorUserId);
             const sessionPlayers = { ...server.sessionPlayers };
             delete sessionPlayers[actorUserId];
             await ctx.db.patch(server._id, {
@@ -490,7 +483,7 @@ export function createGameServerFunctions(options) {
                 sessionPlayers,
                 updatedAt: now,
                 dirtyAt: now,
-                status: memberUserIds.length === 0 ? "open" : server.status,
+                status: statusAfterLeave(memberUserIds.length, server.status),
             });
             const pose = await ctx.db
                 .query("jgPoses")
@@ -510,15 +503,12 @@ export function createGameServerFunctions(options) {
         },
         returns: v.union(v.object({ ok: v.literal(true) }), v.object({ ok: v.literal(false), reason: v.string() })),
         handler: async (ctx, args) => {
-            const actorUserId = await resolveActor(ctx, args.externalId, mode);
-            if (!actorUserId) {
-                throw new ConvexError("Not authenticated");
-            }
+            const actorUserId = await requireActor(ctx, args.externalId, mode);
             const server = await ctx.db.get("jgGameServers", args.serverId);
             if (!server) {
                 return { ok: false, reason: "Server not found" };
             }
-            if (!server.memberUserIds.includes(actorUserId)) {
+            if (!isServerMember(server.memberUserIds, actorUserId)) {
                 return { ok: false, reason: "Not a member of this server" };
             }
             const loadedRevision = server.revision;
@@ -555,14 +545,9 @@ export function createGameServerFunctions(options) {
         },
         returns: v.boolean(),
         handler: async (ctx, args) => {
-            const actorUserId = await resolveActor(ctx, args.externalId, mode);
-            if (!actorUserId) {
-                throw new ConvexError("Not authenticated");
-            }
-            const server = await ctx.db.get("jgGameServers", args.serverId);
-            if (!server)
-                return false;
-            if (!server.memberUserIds.includes(actorUserId))
+            const actorUserId = await requireActor(ctx, args.externalId, mode);
+            const server = await requireServerMember(ctx, args.serverId, actorUserId);
+            if (server === null)
                 return false;
             const runtime = resolveRuntime(registry, server.gameId);
             const snapshot = await loadServerSnapshot(ctx, server, runtime);
@@ -588,15 +573,7 @@ export function createGameServerFunctions(options) {
             sessionPlayers: v.any(),
             updatedAt: v.number(),
         }), v.null()),
-        handler: async (ctx, args) => {
-            const actorUserId = await resolveActor(ctx, args.externalId, mode);
-            if (!actorUserId)
-                return null;
-            const server = await ctx.db.get("jgGameServers", args.serverId);
-            if (!server)
-                return null;
-            if (!server.memberUserIds.includes(actorUserId))
-                return null;
+        handler: (ctx, args) => withMember(ctx, mode, args, null, (server, actorUserId) => {
             const sessionPlayers = server.sessionPlayers;
             const ownSession = sessionPlayers[actorUserId];
             return {
@@ -612,7 +589,7 @@ export function createGameServerFunctions(options) {
                 sessionPlayers: ownSession === undefined ? {} : { [actorUserId]: ownSession },
                 updatedAt: server.updatedAt,
             };
-        },
+        }),
     });
     const getPlayerProfile = query({
         args: {
@@ -653,17 +630,13 @@ export function createGameServerFunctions(options) {
         },
         returns: v.array(v.any()),
         handler: async (ctx, args) => {
-            const actorUserId = await resolveActor(ctx, args.externalId, mode);
-            if (!actorUserId)
-                return [];
-            const server = await ctx.db.get("jgGameServers", args.serverId);
-            if (!server || !server.memberUserIds.includes(actorUserId))
-                return [];
-            const row = await ctx.db
-                .query("jgFeedBuffers")
-                .withIndex("by_server_and_action", (q) => q.eq("serverId", args.serverId).eq("action", args.action))
-                .unique();
-            return row?.entries ?? [];
+            return withMember(ctx, mode, args, [], async () => {
+                const row = await ctx.db
+                    .query("jgFeedBuffers")
+                    .withIndex("by_server_and_action", (q) => q.eq("serverId", args.serverId).eq("action", args.action))
+                    .unique();
+                return row?.entries ?? [];
+            });
         },
     });
     const pushFeedEntry = mutation({
@@ -675,16 +648,13 @@ export function createGameServerFunctions(options) {
         },
         returns: v.null(),
         handler: async (ctx, args) => {
-            const actorUserId = await resolveActor(ctx, args.externalId, mode);
-            if (!actorUserId) {
-                throw new ConvexError("Not authenticated");
-            }
+            const actorUserId = await requireActor(ctx, args.externalId, mode);
             const allowed = validateFeedWrite(feedWriteGate, args.action);
             if (!allowed.ok) {
                 throw new ConvexError(allowed.reason);
             }
             const server = await ctx.db.get("jgGameServers", args.serverId);
-            if (!server || !server.memberUserIds.includes(actorUserId)) {
+            if (!server || !isServerMember(server.memberUserIds, actorUserId)) {
                 throw new ConvexError("Not a member of this server");
             }
             const now = Date.now();
@@ -887,25 +857,22 @@ export function createPresenceFunctions(options) {
             lastSeenAt: v.number(),
         })),
         handler: async (ctx, args) => {
-            const actorUserId = await resolveActor(ctx, args.externalId, mode);
-            if (!actorUserId)
-                return [];
-            if ((await requireServerMember(ctx, args.serverId, actorUserId)) === null)
-                return [];
-            const threshold = Date.now() - freshWindowMs;
-            const rows = await ctx.db
-                .query("jgPoses")
-                .withIndex("by_server", (q) => q.eq("serverId", args.serverId))
-                .collect();
-            return rows
-                .filter((row) => row.updatedAt >= threshold)
-                .map((row) => ({
-                userId: row.userId,
-                position: { x: row.x, y: row.y, z: row.z },
-                rotationY: row.rotationY,
-                rotationPitch: row.rotationPitch,
-                lastSeenAt: row.updatedAt,
-            }));
+            return withMember(ctx, mode, args, [], async () => {
+                const threshold = Date.now() - freshWindowMs;
+                const rows = await ctx.db
+                    .query("jgPoses")
+                    .withIndex("by_server", (q) => q.eq("serverId", args.serverId))
+                    .collect();
+                return rows
+                    .filter((row) => row.updatedAt >= threshold)
+                    .map((row) => ({
+                    userId: row.userId,
+                    position: { x: row.x, y: row.y, z: row.z },
+                    rotationY: row.rotationY,
+                    rotationPitch: row.rotationPitch,
+                    lastSeenAt: row.updatedAt,
+                }));
+            });
         },
     });
     const sync = mutation({
@@ -921,12 +888,7 @@ export function createPresenceFunctions(options) {
             externalId: v.optional(v.string()),
         },
         returns: v.null(),
-        handler: async (ctx, args) => {
-            const actorUserId = await resolveActor(ctx, args.externalId, mode);
-            if (!actorUserId)
-                return null;
-            if ((await requireServerMember(ctx, args.serverId, actorUserId)) === null)
-                return null;
+        handler: (ctx, args) => withMember(ctx, mode, args, null, async (_server, actorUserId) => {
             const now = Date.now();
             const existing = await ctx.db
                 .query("jgPoses")
@@ -962,7 +924,7 @@ export function createPresenceFunctions(options) {
                 await ctx.db.insert("jgPoses", { serverId: args.serverId, userId: actorUserId, ...patch });
             }
             return null;
-        },
+        }),
     });
     const leave = mutation({
         args: {
@@ -1004,12 +966,7 @@ export function createChatFunctions(options) {
             body: v.string(),
             at: v.number(),
         })),
-        handler: async (ctx, args) => {
-            const actorUserId = await resolveActor(ctx, args.externalId, mode);
-            if (!actorUserId)
-                return [];
-            if ((await requireServerMember(ctx, args.serverId, actorUserId)) === null)
-                return [];
+        handler: (ctx, args) => withMember(ctx, mode, args, [], async () => {
             const rows = await ctx.db
                 .query("jgChatMessages")
                 .withIndex("by_server_channel", (q) => q.eq("serverId", args.serverId).eq("channelId", args.channelId))
@@ -1025,7 +982,7 @@ export function createChatFunctions(options) {
                 body: row.body,
                 at: row.at,
             }));
-        },
+        }),
     });
     const sendMessage = mutation({
         args: {

package/package.json

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

package/skills/jgengine/SKILL.md

@@ -9,16 +9,16 @@ Read the repository [README](../../../README.md) for package truth, commands, la
 
 ## 1. Establish the target
 
-Capture only decisions that change architecture:
+Treat the pitch as a unique composition of needs, not a genre to fill in — never reach for a genre kit, preset, archetype, or class template ("default sports car", "default RPG", "default FPS") in the SDK or skills (see [AGENTS.md](../../../AGENTS.md)). Use `game-design` to turn the pitch into a testable player promise, verbs, loops, progression, failure, and completion scenario. Use `level-design` when play depends on authored spaces, routes, encounters, exploration, or spatial pacing. 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
+- HUD/menu states and **custom** UI art direction (every game owns its presentation — no stock drop-in face)
 - 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/*`.
+For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
 
 ## 2. Select domains
 
@@ -26,6 +26,8 @@ Load only rows the target needs. Do not preload every domain.
 
 | Need | Skill | Owner |
 | --- | --- | --- |
+| player promise, pillars, verbs, loops, economy, progression, balance | `game-design` | experience and rule intent |
+| metrics, topology, encounters, navigation, spatial pacing | `level-design` | playable space intent |
 | 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 |
@@ -34,7 +36,7 @@ Load only rows the target needs. Do not preload every domain.
 | 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.
+World content routes editor-first: any request that adds, moves, restyles, or removes something visible in the world — however phrased ("design this world", "place the enemies", "make it look better") — starts in `jgengine-editor`; the other domains consume the authored document. 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
 
@@ -43,6 +45,7 @@ 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.
+4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.
 
 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.