@jgengine/shell 0.18.0 → 0.19.0

package/dist/world/entityPose.js

@@ -3,6 +3,15 @@ export function writeEntityPose(target, source) {
     target.position.set(source.position[0], source.position[1], source.position[2]);
     target.rotation.y = source.rotationY;
 }
+/** Write the interpolated render pose from `ctx.sim` (falls back to `live` when no history exists). @internal */
+export function writeRenderPose(target, ctx, entityId, live, scratch) {
+    if (ctx.sim.renderPose(entityId, scratch)) {
+        target.position.set(scratch[0], scratch[1], scratch[2]);
+        target.rotation.y = scratch[3];
+        return;
+    }
+    writeEntityPose(target, live);
+}
 /** @internal */
 export function posesEqual(a, b) {
     return (a.position[0] === b.position[0] &&

package/dist/world/tileLayerInstances.d.ts

@@ -0,0 +1,11 @@
+import type { TilemapWorldConfig } from "@jgengine/core/world/features";
+/** One resolved map cell with its world position and atlas UV rectangle. */
+export interface TileLayerInstance {
+    x: number;
+    z: number;
+    frame: string;
+    uvOffset: readonly [number, number];
+    uvScale: readonly [number, number];
+}
+/** Resolve map glyphs to atlas frames and normalized UV rectangles for deterministic tests and renderers. */
+export declare function resolveTileLayerInstances(config: TilemapWorldConfig): readonly TileLayerInstance[];

package/dist/world/tileLayerInstances.js

@@ -0,0 +1,28 @@
+/** Resolve map glyphs to atlas frames and normalized UV rectangles for deterministic tests and renderers. */
+export function resolveTileLayerInstances(config) {
+    if (config.tileSet === undefined)
+        return [];
+    const { atlas, tiles } = config.tileSet;
+    const rows = config.map.replace(/\r\n/g, "\n").split("\n").filter((row) => row.length > 0);
+    const width = Math.max(0, ...rows.map((row) => row.length));
+    const instances = [];
+    for (let row = 0; row < rows.length; row += 1) {
+        const line = rows[row].padEnd(width, " ");
+        for (let column = 0; column < width; column += 1) {
+            const frame = tiles[line[column]];
+            if (frame === undefined)
+                continue;
+            const rect = atlas.frames[frame];
+            if (rect === undefined)
+                throw new Error(`tileSet frame "${frame}" is missing from the atlas`);
+            instances.push({
+                x: column - (width - 1) / 2,
+                z: row - (rows.length - 1) / 2,
+                frame,
+                uvOffset: [rect.x / atlas.size[0], 1 - (rect.y + rect.h) / atlas.size[1]],
+                uvScale: [rect.w / atlas.size[0], rect.h / atlas.size[1]],
+            });
+        }
+    }
+    return instances;
+}

package/dist/worldSync.d.ts

@@ -1,5 +1,7 @@
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import type { GameRuntimeFeeds } from "@jgengine/core/runtime/transport";
+/** Receives the revision of an authoritative world frame after it is applied locally. */
+export type AuthoritativeFrameHandler = (revision: number) => void;
 /**
  * Client half of host-authoritative play: subscribe to the server-state channel and mirror each authoritative
  * `WorldSnapshot` (carried in `serverState`) into the local `ctx`, so the game renders the host's world instead
@@ -8,4 +10,6 @@ import type { GameRuntimeFeeds } from "@jgengine/core/runtime/transport";
  * opts into `authority: "server"`.
   * @internal
   */
-export declare function attachWorldSync(feeds: Pick<GameRuntimeFeeds, "subscribeServer">, serverId: string, ctx: Pick<GameContext, "hydrate">): () => void;
+export declare function attachWorldSync(feeds: Pick<GameRuntimeFeeds, "subscribeServer" | "requestServerBaseline">, serverId: string, ctx: Pick<GameContext, "hydrate">, 
+/** Called after each accepted authoritative baseline or diff, for local prediction reconciliation. */
+onAuthoritativeFrame?: AuthoritativeFrameHandler): () => void;

package/dist/worldSync.js

@@ -7,14 +7,35 @@ import { createWorldMirror } from "@jgengine/core/runtime/worldMirror";
  * opts into `authority: "server"`.
   * @internal
   */
-export function attachWorldSync(feeds, serverId, ctx) {
+export function attachWorldSync(feeds, serverId, ctx, 
+/** Called after each accepted authoritative baseline or diff, for local prediction reconciliation. */
+onAuthoritativeFrame) {
     const mirror = createWorldMirror(ctx);
     return feeds.subscribeServer(serverId, (view) => {
         if (view === null)
             return;
-        const snapshot = view.serverState;
-        if (snapshot === null || snapshot === undefined)
+        const frame = view.serverState;
+        if (frame === null || frame === undefined)
             return;
-        mirror.applyBaseline(view.revision, snapshot);
+        if (isWorldSyncFrame(frame)) {
+            if (frame.kind === "baseline") {
+                mirror.applyBaseline(frame.revision, frame.snapshot);
+                onAuthoritativeFrame?.(frame.revision);
+            }
+            else {
+                mirror.applyDiff(frame.diff);
+                onAuthoritativeFrame?.(frame.revision);
+                if (mirror.needsResync())
+                    feeds.requestServerBaseline?.(serverId);
+            }
+            return;
+        }
+        mirror.applyBaseline(view.revision, frame);
+        onAuthoritativeFrame?.(view.revision);
     });
 }
+function isWorldSyncFrame(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        (value.kind === "baseline" || value.kind === "diff"));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.18.0",
-    "@jgengine/react": "^0.18.0",
-    "@jgengine/ws": "^0.18.0"
+    "@jgengine/core": "^0.19.0",
+    "@jgengine/react": "^0.19.0",
+    "@jgengine/ws": "^0.19.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/ce-handoff/SKILL.md

@@ -143,7 +143,7 @@ When sufficient, return a concise orientation: objective, progress, decisions, c
 
 ## JGengine notes
 
-- Multi-session engine work often spans `docs/plans/`, GitHub issues, and stacked PRs — point at those; do not paste full plan bodies.
+- Multi-session engine work spans GitHub issues and PRs — point at those; do not paste full plan bodies.
 - Prefer `bun run agent:bootstrap --check` status, branch names, and PR links as state anchors.
 - Local parallelism uses `.claude/worktrees/`; never invent `C:\tmp\…` Codex-shared trees.
-- Papercuts and durable process changes belong in `PAPERCUTS.md` / skills, not only the handoff.
+- Durable process changes belong in skills, not only the handoff.

package/skills/game-design/SKILL.md

@@ -11,7 +11,7 @@ Own the intended player experience and the rules that produce it: fantasy, pilla
 
 Use `level-design` for spatial realization; route implementation to `jgengine-gameplay`, `jgengine-world`, `jgengine-combat`, `jgengine-ui`, `jgengine-multiplayer` once intent is coherent.
 
-Read [references/application-playbook.md](references/application-playbook.md) only when the task explicitly calls for design depth — a design brief, a redesign, or "make this fun/better" work; it is not a mandatory step of creating a game. Read [references/field-guide.md](references/field-guide.md) when the task needs deeper loop, economy, progression, genre, accessibility, or research guidance.
+For a greenfield build, read [references/application-playbook.md](references/application-playbook.md) and produce its greenfield contract (promise, pillars, anti-pillars, core decision, and falsifier) before writing code. Audits may read only the playbook's audit sections. Read [references/field-guide.md](references/field-guide.md) when the task needs deeper loop, economy, progression, genre, accessibility, or research guidance.
 
 ## Choose the mode
 
@@ -28,3 +28,13 @@ Every design pass yields an observed journey, a north star (promise, pillars, an
 An audit is not completion for a build/improve request. Finish when the slice is playable, a fresh player can state goal/choice/consequence, failure/recovery behave as intended, and evidence supports the pillars. Use `jgengine-verify` and `workflow` to ship.
 
 **Required: player death is a designed, visible moment.** If the game can kill or down the player, death is part of the experience contract, not an invisible state reset. A lethal hit must resolve into an authored beat the player perceives and understands — a death or downed moment, the stakes it carries, and a legible path back into play (respawn, revive, restart) — never a silent teleport to spawn. Design what death means for this pitch (permadeath, checkpoint, bleed-out-and-revive, run reset) and treat "player dies with no acknowledged consequence" as a failure/recovery defect. `jgengine-ui` owns building the screen and respawn feedback.
+
+## Persistent-builder checks
+
+Before content, write a first-hour balance sheet: starting cash, time to first income, net income per hour at starting hardware and at ten times that hardware, bill cadence versus income, and the insolvency recovery path. Insolvency resets the affected player or changes their options; it never deletes the world. Express clicks and event rewards as a fraction of the designed income rate, never an unrelated flat payout.
+
+Currency precision, elapsed-time anchoring, and reset mechanics are implemented per `jgengine-gameplay` "Persistent economies and input"; test fractional income over real tick cadences before tuning prices.
+
+The first-60-seconds gate requires the first tutorial verb to be executable from spawn with starting inventory. Grant dependencies such as land, power, and slots or let players buy them in-context; the tutorial cannot lock the surface needed to complete itself. Placement previews show cost and affordability inline.
+
+For a persistent shared-world builder, verify capacity and first-player onboarding before scaling the content catalog; presence, command read scopes, territory, chat, and join retry UI come from their owners in `jgengine-world`, `jgengine-ui`, and `jgengine-multiplayer`.

package/skills/jgengine/SKILL.md

@@ -5,10 +5,14 @@ description: Route game work to the smallest useful JGengine guidance set.
 
 # JGengine intake and router
 
-Read the JGengine README for package truth, commands, layering, and license — the repo-root [`README.md`](../../../README.md) in the monorepo, or [jgengine.com](https://jgengine.com) from a scaffolded consumer project (where the relative link does not resolve). This skill decides what to load; it is not an engine manual.
+This skill decides what to load; it is not an engine manual. Package map, commands, layering, and license live in the JGengine README (repo-root [`README.md`](../../../README.md) in the monorepo, [jgengine.com](https://jgengine.com) from a created project); open it when you need one of those facts.
+
+A created project installs only `jgengine`, `jgengine-editor`, `jgengine-verify`, `game-design`, and `jgengine-ui`. Run `npx jgengine skills -p --all` before loading any other domain named below. Those projects do not ship `api.md`; read exact signatures from the `.d.ts` files under `node_modules/@jgengine/<pkg>/dist/`.
 
 ## 1. Establish the target
 
+For greenfield builds, write `src/art-direction.md` before any code.
+
 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
@@ -18,7 +22,7 @@ Treat the pitch as a unique composition of needs, not a genre to fill in — nev
 - HUD/menu states and **custom** UI art direction (compose shipped building blocks + HudTheme; no unskinned stock face)
 - one observable completion scenario
 
-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/*`.
+Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player model, editor scene); a grid, card, tile, or other board game with no 3D scene takes `create --2d` (a `board` world drawn by GameUI over `@jgengine/core/puzzle/cellGrid`). 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/*`.
 
 For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
 
@@ -44,9 +48,9 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 
 Within each selected domain:
 
-0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) for `combat-loop`, `boss-telegraph`, `loot`, `quest`, `coop-presence`, `third-person-camera`; `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
-1. Search `capabilities.md` by intent; it maps needs to imports. Outside the monorepo (or before a domain skill is even loaded), `npx jgengine find <intent>` greps every shipped capability index at once and prints the primitive + import — reach for it the moment you're tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. If you're writing a `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob, a shipped drop-in almost certainly exists (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
-2. Open `api.md` only when exact signatures or export inventory are needed.
+0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) (`combat-loop`, `loot`, `world-drops`, `click-target`, `ability-bar`, `hitscan-weapon`, `rolled-gear`, `enter-vehicle` and more); `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
+1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); in the monorepo, `grep -i "<intent>" .claude/skills/*/capabilities.md` does the same. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
+2. Open `api.md` (monorepo) or the package `.d.ts` only when exact signatures are needed; grep it, never read it whole.
 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.