@jgengine/editor 0.11.0 → 0.12.0

package/skills/jgengine/capabilities.md

@@ -4,18 +4,100 @@
 
 Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
 
-## define-game — single public game-authoring path — compose systems, world, and loop in one definition
+## authored-spawn — read spawn points and markers from the editor document
 
-- `defineGame` (function) · `import { defineGame } from "@jgengine/core/authoring"`
+- `authoredSpawnPosition` (function) · `import { authoredSpawnPosition } from "@jgengine/shell/gameKit"`
+
+## authored-triggers — schema'd on/action vocabulary on volumes and markers with runtime dispatch
+
+- `collectAuthoredTriggers` (function) · `import { collectAuthoredTriggers } from "@jgengine/shell/gameKit"`
+
+## collider-autofit — hitboxes and physical bodies fit each kind's rendered model bounds automatically — no hand-tuned sizes
+
+- `GameContextModels` (interface) · `import { GameContextModels } from "@jgengine/core/runtime/gameContext"`
+
+## define-game — single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
+
+- `defineGame` (function) · `import { defineGame } from "@jgengine/shell/gameKit"`
+
+## define-system — composable game behavior — pure data + hooks the engine schedules; pass via `defineGame({ systems })`
+
+- `defineSystem` (function) · `import { defineSystem } from "@jgengine/shell/gameKit"`
+
+## editor-catalogs — Export typed gameplay catalogs for in-editor tuning.
+
+- `EditorCatalogDefinition` (interface) · `import { EditorCatalogDefinition } from "@jgengine/shell/gameKit"`
+
+## game-system — declare a composable capability with its own schedule and lifecycle
+
+- `SystemDefinition` (interface) · `import { SystemDefinition } from "@jgengine/shell/gameKit"`
 
 ## headless-runner — play a real game loop with no renderer — tick, feed input, read the world snapshot
 
 - `HeadlessRunner` (interface) · `import { HeadlessRunner } from "@jgengine/core/runtime/headlessRunner"`
 
+## host-join-code-gate — membership-or-code gate for private hosted servers
+
+- `canJoinPrivateServer` (function) · `import { canJoinPrivateServer } from "@jgengine/core/runtime/hostPolicy"`
+
+## host-listing-filter — exclude private sessions from public browse results
+
+- `isListablePublicly` (function) · `import { isListablePublicly } from "@jgengine/core/runtime/hostPolicy"`
+
+## hud-canvas — the HUD root surface — design-resolution scaling plus live panel-placement editing (F2+C)
+
+- `HudCanvas` (function) · `import { HudCanvas } from "@jgengine/shell/gameKit"`
+
+## hud-clock — in-game time-of-day readout bound to the sim clock
+
+- `Clock` (function) · `import { Clock } from "@jgengine/shell/gameKit"`
+
+## hud-coins — currency counter widget bound to a currency id
+
+- `Coins` (function) · `import { Coins } from "@jgengine/shell/gameKit"`
+
+## hud-hotbar — optional inventory hotbar building block — games own slot chrome
+
+- `Hotbar` (function) · `import { Hotbar } from "@jgengine/shell/gameKit"`
+
+## hud-layout — persistent, live-editable HUD panel layout state for `HudCanvas`
+
+- `useHudLayout` (function) · `import { useHudLayout } from "@jgengine/shell/gameKit"`
+
+## hud-panel — anchored HUD slot — drop any widget in a named, player-movable panel
+
+- `HudPanel` (function) · `import { HudPanel } from "@jgengine/shell/gameKit"`
+
+## hud-stat-bar — optional stat-bound bar building block (health, mana, stamina) — prefer game-owned chrome
+
+- `StatBar` (function) · `import { StatBar } from "@jgengine/shell/gameKit"`
+
 ## loot-table — validate a loot table definition for use with the registry
 
 - `lootTable` (function) · `import { lootTable } from "@jgengine/core/authoring"`
 
+## mount-game — mount a defined game in the browser — `<GameHost playable={game} editor={() => import("@jgengine/editor")} />`
+
+- `GameHost` (function) · `import { GameHost } from "@jgengine/shell/gameKit"`
+
+## multiplayer-offline — explicit solo adapter — omit `multiplayer` instead; offline is the shell default
+
+- `offline` (function) · `import { offline } from "@jgengine/shell/gameKit"`
+
+## multiplayer-p2p — serverless co-op over WebRTC — `multiplayer: p2p({ room })`
+
+- `p2p` (function) · `import { p2p } from "@jgengine/core/runtime/adapter"`
+
+## multiplayer-ws — server-hosted shared world over WebSocket — `multiplayer: ws({ authority: "server" })`
+
+- `ws` (function) · `import { ws } from "@jgengine/core/runtime/adapter"`
+
+## render-fallback-diagnostics — Enable/disable the dev-only placeholder-fallback probe.
+
+- `armFallbackSeams` (function) · `import { armFallbackSeams } from "@jgengine/core/devtools/fallbackSeams"`
+- `fallbackSeamsSnapshot` (function) · `import { fallbackSeamsSnapshot } from "@jgengine/core/devtools/fallbackSeams"`
+- `reportFallbackSeam` (function) · `import { reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams"`
+
 ## runtime-save — save/load the whole game world through a pluggable backend, autosave or save points
 
 - `createRuntimeSave` (function) · `import { createRuntimeSave } from "@jgengine/core/runtime/runtimeSave"`
@@ -27,3 +109,23 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `collectOwnershipDiagnostics` (function) · `import { collectOwnershipDiagnostics } from "@jgengine/core/authoring"`
 - `isSceneOwnershipManifest` (function) · `import { isSceneOwnershipManifest } from "@jgengine/core/authoring"`
 - `ownershipKey` (function) · `import { ownershipKey } from "@jgengine/core/authoring"`
+
+## seeded-random — injected deterministic randomness for game logic — never `Math.random` in a simulation
+
+- `seededRng` (function) · `import { seededRng } from "@jgengine/shell/gameKit"`
+
+## typed-keyed-store — a cast-free typed handle onto a per-owner keyed family of reactive game-store slots, replayable and host-authoritative
+
+- `defineKeyedStore` (function) · `import { defineKeyedStore } from "@jgengine/shell/gameKit"`
+
+## typed-store — a cast-free typed handle onto one reactive game-store slot, replayable and host-authoritative
+
+- `defineStore` (function) · `import { defineStore } from "@jgengine/shell/gameKit"`
+
+## world-convergence — derive environment coordinate content from the scene document
+
+- `environmentContentFromDocument` (function) · `import { environmentContentFromDocument } from "@jgengine/shell/gameKit"`
+
+## world-environment — compose editor/preset-derived outdoor dressing — terrain, weather, water, structures — into a legacy environment feature
+
+- `environment` (function) · `import { environment } from "@jgengine/shell/gameKit"`

package/skills/jgengine/recipes/minimal-game.md

@@ -0,0 +1,88 @@
+# Recipe — minimal game (scaffold → authored scene → win)
+
+**What this wires:** the default end-to-end path from nothing to a complete, genre-free
+walk/interact/win game: a scaffold, one `defineGame` config off the happy-path kit, an
+authored scene edited in the browser, one system, one store slot, an empty-canvas HUD,
+and a win condition. Every new game starts here; add combat, multiplayer, or deeper
+world features only after this loop plays.
+
+## 1. Scaffold
+
+`npx jgengine create <name>` (inside the engine monorepo: `bun run new:game "<id-or-title>"`).
+The file set is thin and already runs:
+
+- `src/main.tsx` — mounts `GameHost` with `editor={() => import("@jgengine/editor")}`; the
+  host owns the F2+E / `?mode=editor` editor summon and the dev save endpoint.
+- `src/game.config.ts` — the whole game definition (below).
+- `src/editor.scene.json` + `src/editorLayers.ts` — the authored scene document, normalized
+  with `normalizeEditorLayers`. All placement lives here, never as coordinates in code.
+- `src/loop.ts` and `src/game/ui/GameUI.tsx` — systems and HUD.
+
+## 2. Define the game — one import surface
+
+```ts
+// game.config.ts — everything below comes from the kit; deeper paths are for outgrowing it.
+import { defineGame } from "@jgengine/shell/gameKit";
+
+import { editorLayers } from "./editorLayers";
+import { GameUI } from "./game/ui/GameUI";
+import { onNewPlayer, systems } from "./loop";
+
+export const game = defineGame({
+  name: "my-game",
+  // Binding movement actions makes the shell drive the walk controller — the game walks day one.
+  input: { moveForward: ["KeyW"], moveBack: ["KeyS"], moveLeft: ["KeyA"], moveRight: ["KeyD"], interact: ["KeyE"] },
+  systems,
+  loop: { onNewPlayer },
+  GameUI,
+  editorLayers, // the authored scene auto-mounts; the player spawns at its player_spawn marker
+});
+// Solo game: omit `multiplayer` entirely — offline is the shell default.
+```
+
+**World is optional and thin.** Omitting `world` is valid — a pure UI/rules game is not a
+spatial place. When the game *is* a place, declare only substrate + laws with `world()` from
+`@jgengine/core/world/place` (e.g. `{ id, ground: { mode: "flat", size: { x: Infinity, z: Infinity } }, physics: { gravity: -24 } }`,
+or `mode: "board"` for 2D). Never seed, sky, or vegetation in `world` — the engine renders its
+default sky until you author one in the editor, and foliage is editor scatter over the ground.
+
+
+```ts
+// loop.ts — one store slot for run state, one system for the rules tick.
+import { defineStore, defineSystem, authoredSpawnPosition, type GameContext } from "@jgengine/shell/gameKit";
+
+import { editorLayers } from "./editorLayers";
+
+export const run = defineStore("run", { collected: 0, won: false });
+
+export const systems = [
+  defineSystem({
+    id: "rules",
+    tick: { type: "fixed" },
+    update(ctx: GameContext) {
+      // System-check win alternative: read/update `run` here (e.g. win at collected >= 3).
+      if (run.read(ctx).collected >= 3) run.update(ctx, (s) => ({ ...s, won: true }));
+    },
+  }),
+];
+
+export function onNewPlayer(ctx: GameContext): void {
+  ctx.scene.entity.spawn("player", { id: ctx.player.userId, position: authoredSpawnPosition(editorLayers) ?? [0, 0, 0] });
+}
+```
+
+`GameUI` starts as an empty `HudCanvas` (`useHudLayout` + `HudCanvas` from the kit). That is
+intentional: **every game owns its UI**. Write a short UI art direction, then build custom
+panels for this pitch — do not ship stock drop-in widgets (`StatBar`, `Hotbar`, `Coins`, glass
+frames) as the product face. Reach for engine pieces only as headless data, layout, or
+interaction models under game-owned chrome (see `jgengine-ui`).
+
+## 3. Author, play, win
+
+1. `bun dev`, then F2+E opens the editor on `editor.scene.json` — move the spawn, place
+   props and trigger markers, Ctrl+S saves back to the document.
+2. The starter scene ships a goal marker with `{ on: "enter", action: "win" }` — walking
+   into it wins with zero game code. Author more rules the same way (triggers in the
+   editor), or read volumes yourself via the kit's `collectAuthoredTriggers(editorLayers)`.
+3. Prove it: `bun test` asserts the document (spawn, goal), and `jgengine-verify` covers
+   screenshot and gameplay evidence before any "it works" claim.

package/skills/jgengine-editor/SKILL.md

@@ -15,14 +15,29 @@ Never replace authorable scene content with hardcoded meshes, coordinate arrays,
 
 Every editor-visible object has an explicit provenance — `authored`, `generated`, `runtime`, or `transient` — and a single verdict from `classifyOwnership` (`@jgengine/core/scene/sceneOwnership`): **expose** (authorable), **bake** (offer import to the document when the provider can emit schema-valid data), or **reject** (read-only runtime content). Runtime/transient content with neither a `bake` capability nor a declared `reason` is a boundary violation — content bypassing the document with no authored home. Genuinely runtime-only or geometry-free content is declared with a serializable `SceneOwnershipManifest` (`scene-ownership.json`), which `check-content-gate` validates — the replacement for game-name exemptions.
 
+## Headless fast path
+
+Inspect, mutate, and persist a game's scene in single commands — no GUI session and no reference reading needed for basic authoring:
+
+```sh
+bun packages/editor/src/mcp/cli.ts --game <id> --tools                     # verb inventory with descriptions
+bun packages/editor/src/mcp/cli.ts --game <id> --rpc '{"method":"scene_summary"}'
+bun packages/editor/src/mcp/cli.ts --game <id> \
+  --rpc '{"method":"set_transform","id":"boss","x":10,"y":0,"z":-5}' --save
+```
+
+Repeat `--rpc` to batch several mutations on one session; `--save` then writes the document back to `Games/<id>/src/editor.scene.json` in the same format as the GUI's Ctrl+S, and a failed RPC aborts the batch before anything is saved.
+
 ## Canonical workflow
 
 1. Inspect the current scene and available editor capabilities.
-2. Make authoring changes through the GUI or `bun packages/editor/src/mcp/cli.ts`; do not hand-edit the JSON.
-3. Save the scene document and verify the intended objects/layers are present.
-4. Make gameplay reference stable authored ids, path kinds, markers, or zones rather than copying coordinates.
+2. Make authoring changes through the GUI or the headless fast path above; do not hand-edit the JSON.
+3. Save the scene document (`--save` headless, Ctrl+S in the GUI) and verify the intended objects/layers are present.
+4. Make gameplay reference stable authored ids, path kinds, markers, or zones rather than copying coordinates (player spawns read the document's `player_spawn` marker via `authoredSpawnPosition` from `@jgengine/core/world/authoredSpawn`).
 5. Render through shared authored-scene primitives and verify with `jgengine-verify`.
 
+Scaffolded games start editor-wired: `npx jgengine create` (also what `bun run new:game` runs in-repo) uses one template that ships `src/editor.scene.json` + `editorLayers.ts`, passes the document to play mode and F2+E through `defineGame({ editorLayers })` (auto-mounted `AuthoredScene`), and spawns at the authored marker — extend the shipped document instead of re-wiring or hardcoding. To promote a scene authored in the standalone editor (`npx jgengine editor`) into a runnable game, `npx jgengine create "<Name>" --from-scene <folder>` bakes that folder's `editor.scene.json` in as the new game's scene (adding a `player_spawn` at the origin only if the authored scene lacks one), so the built game walks the scene that was just authored. Once promoted, an editor asset import (drop a `.glb`/`.gltf`) no longer scans a model folder: the host detects the typed `src/game/assets.ts` catalog, copies the bytes into the game's `public/<basePath>/imported/`, and rewrites `assets.ts` to add a durable `extras` entry (`buildCatalog({ extras })`), so the shipped game resolves the imported id through its own catalog. The rewrite is idempotent — re-importing the same id collapses to one entry — and falls back to the folder-scan import if `assets.ts` can't be safely rewritten.
+
 Use `capabilities.md` to discover editor/runtime imports and `api.md` for signatures. Open [reference.md](reference.md) for RPC/CLI operations, embedded-agent behavior, scene schema details, and troubleshooting.
 
 ## Traps