@jgengine/ws 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/host.js

@@ -1,6 +1,7 @@
 import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
 import { applyLeaderboardRows, buildHydratePlayers, planServerPersist, profileLeaderboardStats, shouldAutoSave, topLeaderboardRows, toOpenServerListings, toServerListing, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
-import { browseSessions, findByJoinCode, normalizeJoinCode } from "@jgengine/core/multiplayer/matchmaking";
+import { isListablePublicly, isPrivateJoinBlocked, isServerFull, isServerMember, statusAfterLeave, withJoinedMember, withoutMember, } from "@jgengine/core/runtime/hostPolicy";
+import { browseSessions, findByJoinCode } from "@jgengine/core/multiplayer/matchmaking";
 import { createFeedWriteGate, validateFeedWrite, } from "@jgengine/core/multiplayer/feedWriteGate";
 import { clearDirtyFlags, createEmptyServerRow, splitProfilePlayer } from "@jgengine/core/runtime/snapshot";
 const builtinCommands = {
@@ -219,15 +220,14 @@ export function createGameHost(options) {
                     throw new Error("Server belongs to a different game");
                 }
                 if (entry !== null &&
-                    entry.record.visibility === "private" &&
-                    !entry.record.memberUserIds.includes(args.userId)) {
-                    const requiredCode = entry.record.joinCode;
-                    const matches = requiredCode !== undefined &&
-                        args.code !== undefined &&
-                        normalizeJoinCode(args.code) === normalizeJoinCode(requiredCode);
-                    if (!matches) {
-                        throw new Error("Server is private");
-                    }
+                    isPrivateJoinBlocked({
+                        visibility: entry.record.visibility,
+                        memberUserIds: entry.record.memberUserIds,
+                        userId: args.userId,
+                        joinCode: entry.record.joinCode,
+                        suppliedCode: args.code,
+                    })) {
+                    throw new Error("Server is private");
                 }
                 if (entry === null) {
                     const attributes = args.attributes;
@@ -253,17 +253,14 @@ export function createGameHost(options) {
                     entry = await hydrate(record);
                 }
                 const { record } = entry;
-                if (record.memberUserIds.length >= record.slotsPerServer &&
-                    !record.memberUserIds.includes(args.userId)) {
+                if (isServerFull(record.memberUserIds, record.slotsPerServer, args.userId)) {
                     throw new Error("Server is full");
                 }
                 const profile = await persistence.loadProfile({ userId: args.userId, gameId: args.gameId });
                 const isNew = profile === null;
                 entry.record = {
                     ...record,
-                    memberUserIds: record.memberUserIds.includes(args.userId)
-                        ? record.memberUserIds
-                        : [...record.memberUserIds, args.userId],
+                    memberUserIds: withJoinedMember(record.memberUserIds, args.userId),
                     status: "running",
                     updatedAt: timestamp,
                     dirtyAt: timestamp,
@@ -292,11 +289,11 @@ export function createGameHost(options) {
             const entry = await getLive(args.serverId);
             if (entry === null)
                 return;
-            if (!entry.record.memberUserIds.includes(args.userId))
+            if (!isServerMember(entry.record.memberUserIds, args.userId))
                 return;
             await flushServer(entry);
             const timestamp = now();
-            const memberUserIds = entry.record.memberUserIds.filter((id) => id !== args.userId);
+            const memberUserIds = withoutMember(entry.record.memberUserIds, args.userId);
             const sessionPlayers = { ...entry.record.sessionPlayers };
             delete sessionPlayers[args.userId];
             const players = { ...entry.snapshot.players };
@@ -306,7 +303,7 @@ export function createGameHost(options) {
                 memberUserIds,
                 sessionPlayers,
                 updatedAt: timestamp,
-                status: memberUserIds.length === 0 ? "open" : entry.record.status,
+                status: statusAfterLeave(memberUserIds.length, entry.record.status),
             };
             entry.snapshot = { ...entry.snapshot, players };
             await persistence.saveServer(entry.record);
@@ -321,7 +318,7 @@ export function createGameHost(options) {
             if (entry === null) {
                 return { ok: false, reason: "Server not found" };
             }
-            if (!entry.record.memberUserIds.includes(args.userId)) {
+            if (!isServerMember(entry.record.memberUserIds, args.userId)) {
                 return { ok: false, reason: "Not a member of this server" };
             }
             const envelope = unwrapOpEnvelope(args.input);
@@ -351,13 +348,13 @@ export function createGameHost(options) {
             const entry = await getLive(args.serverId);
             if (entry === null)
                 return false;
-            return entry.record.memberUserIds.includes(args.userId);
+            return isServerMember(entry.record.memberUserIds, args.userId);
         },
         getServerView: async (args) => {
             const entry = await getLive(args.serverId);
             if (entry === null)
                 return null;
-            if (!entry.record.memberUserIds.includes(args.userId))
+            if (!isServerMember(entry.record.memberUserIds, args.userId))
                 return null;
             return {
                 serverId: entry.record.serverId,
@@ -372,7 +369,7 @@ export function createGameHost(options) {
             const entry = await getLive(args.serverId);
             if (entry === null)
                 return null;
-            if (!entry.record.memberUserIds.includes(args.userId))
+            if (!isServerMember(entry.record.memberUserIds, args.userId))
                 return null;
             const player = entry.snapshot.players[args.userId];
             if (player !== undefined) {
@@ -397,7 +394,7 @@ export function createGameHost(options) {
             const entry = await getLive(args.serverId);
             if (entry === null)
                 return [];
-            if (!entry.record.memberUserIds.includes(args.userId))
+            if (!isServerMember(entry.record.memberUserIds, args.userId))
                 return [];
             return persistence.loadFeed({ serverId: args.serverId, action: args.action });
         },
@@ -407,7 +404,7 @@ export function createGameHost(options) {
                 throw new Error(allowed.reason);
             }
             const entry = await getLive(args.serverId);
-            if (entry === null || !entry.record.memberUserIds.includes(args.userId)) {
+            if (entry === null || !isServerMember(entry.record.memberUserIds, args.userId)) {
                 throw new Error("Not a member of this server");
             }
             await persistence.appendFeed({ serverId: args.serverId, action: args.action, entry: args.entry });
@@ -416,14 +413,14 @@ export function createGameHost(options) {
         listOpenServers: async (args) => {
             const byId = new Map();
             for (const record of await persistence.listServers(args.gameId)) {
-                if ((record.visibility ?? "public") === "private")
+                if (!isListablePublicly(record.visibility))
                     continue;
                 byId.set(record.serverId, toServerListing(record));
             }
             for (const entry of live.values()) {
                 if (entry.record.gameId !== args.gameId)
                     continue;
-                if ((entry.record.visibility ?? "public") === "private")
+                if (!isListablePublicly(entry.record.visibility))
                     continue;
                 byId.set(entry.record.serverId, toServerListing(entry.record));
             }

package/dist/hostRouter.js

@@ -1,15 +1,9 @@
-import { decidePoseSync, spawnPresenceState } from "@jgengine/core/multiplayer/presenceModel";
+import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, spawnPresenceState, } from "@jgengine/core/multiplayer/presenceModel";
 import { createPositionHistory } from "@jgengine/core/multiplayer/lagCompensation";
 import { createChatRateLimiter, DEFAULT_CHAT_BODY_LENGTH, DEFAULT_CHAT_HISTORY_LIMIT, DEFAULT_CHAT_RATE_LIMIT, } from "@jgengine/core/game/chat";
 import { createCommandMiddleware, } from "./commandMiddleware.js";
 import { decodeWsClientMessage, encodeWsMessage, inspectWsDecodeFailure, subscriptionKey, } from "./protocol.js";
-export const DEFAULT_POSE_RULES = {
-    maxSpeed: 12,
-    maxVerticalOffset: 3,
-    minElapsedSec: 0.05,
-    maxElapsedSec: 0.5,
-    keepAliveRefreshMs: 10_000,
-};
+export const DEFAULT_POSE_RULES = DEFAULT_POSE_SYNC_RULES;
 /** Cap on frames queued behind a connection's in-flight message; beyond this a flood gets rejected instead of piling up unbounded promises. */
 export const MAX_QUEUED_MESSAGES = 64;
 function appearanceEqual(a, b) {
@@ -23,6 +17,29 @@ function appearanceEqual(a, b) {
         return false;
     return aKeys.every((key) => a[key] === b[key]);
 }
+function getOrCreate(map, key, factory) {
+    let value = map.get(key);
+    if (value === undefined) {
+        value = factory();
+        map.set(key, value);
+    }
+    return value;
+}
+/**
+ * Remove `userId` from every visited `server|scope` bucket, drop buckets that empty out, and notify
+ * per changed key. Backs both the disconnect-wide and per-server drops for presence and voice.
+ */
+function dropUserFrom(store, userId, shouldVisit, onChanged) {
+    for (const [key, inner] of store) {
+        if (!shouldVisit(key))
+            continue;
+        if (!inner.delete(userId))
+            continue;
+        if (inner.size === 0)
+            store.delete(key);
+        onChanged(key);
+    }
+}
 export function createHostRouter(options) {
     const host = options.host;
     const now = options.now ?? Date.now;
@@ -59,14 +76,7 @@ export function createHostRouter(options) {
     const presence = new Map();
     const positionHistoryMs = options.positionHistoryMs ?? 1_000;
     const histories = new Map();
-    const historyFor = (serverId) => {
-        let history = histories.get(serverId);
-        if (history === undefined) {
-            history = createPositionHistory({ historyMs: positionHistoryMs });
-            histories.set(serverId, history);
-        }
-        return history;
-    };
+    const historyFor = (serverId) => getOrCreate(histories, serverId, () => createPositionHistory({ historyMs: positionHistoryMs }));
     const send = (connection, message) => {
         connection.transport.send(encodeWsMessage(message));
     };
@@ -89,16 +99,21 @@ export function createHostRouter(options) {
             appearance: pose.appearance,
         }));
     };
-    const broadcastPresence = (serverId) => {
-        const key = subscriptionKey("presence", serverId);
+    const broadcast = (key, build) => {
         const targets = subscribersOf(key);
         if (targets.length === 0)
             return;
-        const data = presenceRows(serverId);
-        for (const connection of targets) {
-            send(connection, { v: 1, t: "update", channel: "presence", serverId, data });
-        }
+        const message = build();
+        for (const connection of targets)
+            send(connection, message);
     };
+    const broadcastPresence = (serverId) => broadcast(subscriptionKey("presence", serverId), () => ({
+        v: 1,
+        t: "update",
+        channel: "presence",
+        serverId,
+        data: presenceRows(serverId),
+    }));
     const commandMiddleware = createCommandMiddleware({
         limits: options.limits,
         authorize: options.authorize,
@@ -125,69 +140,37 @@ export function createHostRouter(options) {
     const chatHistoryLimit = options.chatHistoryLimit ?? DEFAULT_CHAT_HISTORY_LIMIT;
     const chatMaxBodyLength = options.chatMaxBodyLength ?? DEFAULT_CHAT_BODY_LENGTH;
     let chatCounter = 0;
-    const chatRing = (serverId, channelId) => {
-        const key = `${serverId}|${channelId}`;
-        let ring = chatRings.get(key);
-        if (ring === undefined) {
-            ring = [];
-            chatRings.set(key, ring);
-        }
-        return ring;
-    };
-    const broadcastChat = (serverId, channelId) => {
-        const key = subscriptionKey("chat", serverId, channelId);
-        const targets = subscribersOf(key);
-        if (targets.length === 0)
-            return;
-        const data = chatRing(serverId, channelId).slice();
-        for (const connection of targets) {
-            send(connection, { v: 1, t: "update", channel: "chat", serverId, action: channelId, data });
-        }
-    };
+    const chatRing = (serverId, channelId) => getOrCreate(chatRings, `${serverId}|${channelId}`, () => []);
+    const broadcastChat = (serverId, channelId) => broadcast(subscriptionKey("chat", serverId, channelId), () => ({
+        v: 1,
+        t: "update",
+        channel: "chat",
+        serverId,
+        action: channelId,
+        data: chatRing(serverId, channelId).slice(),
+    }));
     const voiceRosters = new Map();
-    const voiceRoster = (serverId, channelId) => {
-        const key = `${serverId}|${channelId}`;
-        let roster = voiceRosters.get(key);
-        if (roster === undefined) {
-            roster = new Map();
-            voiceRosters.set(key, roster);
-        }
-        return roster;
-    };
+    const voiceRoster = (serverId, channelId) => getOrCreate(voiceRosters, `${serverId}|${channelId}`, () => new Map());
     const voiceParticipants = (serverId, channelId) => [...voiceRoster(serverId, channelId).values()].map((participant) => ({ ...participant }));
-    const broadcastVoice = (serverId, channelId) => {
-        const key = subscriptionKey("voice", serverId, channelId);
-        const targets = subscribersOf(key);
-        if (targets.length === 0)
-            return;
-        const data = voiceParticipants(serverId, channelId);
-        for (const connection of targets) {
-            send(connection, { v: 1, t: "update", channel: "voice", serverId, action: channelId, data });
-        }
-    };
+    const broadcastVoice = (serverId, channelId) => broadcast(subscriptionKey("voice", serverId, channelId), () => ({
+        v: 1,
+        t: "update",
+        channel: "voice",
+        serverId,
+        action: channelId,
+        data: voiceParticipants(serverId, channelId),
+    }));
     const dropVoice = (connection) => {
         if (connection.userId === null)
             return;
-        for (const [key, roster] of voiceRosters) {
-            if (!roster.delete(connection.userId))
-                continue;
-            if (roster.size === 0)
-                voiceRosters.delete(key);
+        dropUserFrom(voiceRosters, connection.userId, () => true, (key) => {
             const [serverId, channelId] = key.split("|");
             broadcastVoice(serverId, channelId);
-        }
+        });
     };
     const dropVoiceForServer = (userId, serverId) => {
         const prefix = `${serverId}|`;
-        for (const [key, roster] of voiceRosters) {
-            if (!key.startsWith(prefix))
-                continue;
-            if (!roster.delete(userId))
-                continue;
-            if (roster.size === 0)
-                voiceRosters.delete(key);
-            broadcastVoice(serverId, key.slice(prefix.length));
-        }
+        dropUserFrom(voiceRosters, userId, (key) => key.startsWith(prefix), (key) => broadcastVoice(serverId, key.slice(prefix.length)));
     };
     const requireMembership = async (connection, id, serverId) => {
         const userId = connection.userId;
@@ -337,21 +320,10 @@ export function createHostRouter(options) {
     const dropPresence = (connection) => {
         if (connection.userId === null)
             return;
-        for (const [serverId, rows] of presence) {
-            if (rows.delete(connection.userId)) {
-                if (rows.size === 0)
-                    presence.delete(serverId);
-                broadcastPresence(serverId);
-            }
-        }
+        dropUserFrom(presence, connection.userId, () => true, (serverId) => broadcastPresence(serverId));
     };
     const dropPresenceForServer = (userId, serverId) => {
-        const rows = presence.get(serverId);
-        if (rows === undefined || !rows.delete(userId))
-            return;
-        if (rows.size === 0)
-            presence.delete(serverId);
-        broadcastPresence(serverId);
+        dropUserFrom(presence, userId, (key) => key === serverId, () => broadcastPresence(serverId));
     };
     const handleMessage = async (connection, message) => {
         if (message.t === "hello") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/ws",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Browser-safe WebSocket client backend for JGengine: protocol codec, createWsBackend, and HTTP read helpers.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.11.0"
+    "@jgengine/core": "^0.12.0"
   },
   "publishConfig": {
     "access": "public"

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.