@jgengine/shell 0.18.1 → 0.19.0

package/dist/structures/buildingSurface.js

@@ -0,0 +1,134 @@
+import { useEffect, useMemo, useState } from "react";
+import * as THREE from "three";
+const SURFACE_ROLES = ["color", "normal", "roughness", "ao", "metalness"];
+/** True when the surface names at least one map URL, so the batch needs the textured path. */
+export function surfaceHasMaps(surface) {
+    if (surface?.maps === undefined)
+        return false;
+    return SURFACE_ROLES.some((role) => surface.maps?.[role] !== undefined);
+}
+/** A stable key for bucketing instances that share one surface (same colour, maps, tiling, and response). */
+export function surfaceKey(surface) {
+    if (surface === undefined)
+        return "";
+    const repeat = surface.repeat === undefined ? 1 : surface.repeat;
+    const maps = surface.maps === undefined ? "" : SURFACE_ROLES.map((role) => surface.maps?.[role] ?? "").join(",");
+    const tiling = typeof repeat === "number" ? String(repeat) : repeat.join("x");
+    return `${surface.color ?? ""}|${maps}|${tiling}|${surface.roughness ?? ""}|${surface.metalness ?? ""}`;
+}
+function repeatOf(surface) {
+    const repeat = surface.repeat ?? 1;
+    return typeof repeat === "number" ? [repeat, repeat] : [repeat[0], repeat[1]];
+}
+const textureLoader = new THREE.TextureLoader();
+const loads = new Map();
+/** One shared decode per URL; a missing file (a pack without `ao.jpg`) resolves to null instead of failing the batch. */
+function loadSurfaceTexture(url) {
+    let pending = loads.get(url);
+    if (pending === undefined) {
+        pending = new Promise((resolve) => {
+            textureLoader.load(url, (texture) => resolve(texture), undefined, () => resolve(null));
+        });
+        loads.set(url, pending);
+    }
+    return pending;
+}
+/**
+ * Loads a surface's PBR maps and returns per-caller clones configured to tile `repeat` times per
+ * slot, or `undefined` until the first map arrives so the batch draws its flat colour meanwhile.
+ * Clones share the decoded image, so two kinds using one map at different repeats cost one
+ * download. Maps whose file is missing are skipped rather than failing the whole surface.
+ * @internal
+ */
+export function useBuildingSurfaceTextures(surface) {
+    const maps = surface?.maps;
+    const color = maps?.color;
+    const normal = maps?.normal;
+    const roughness = maps?.roughness;
+    const ao = maps?.ao;
+    const metalness = maps?.metalness;
+    const urls = useMemo(() => {
+        const record = {};
+        if (color !== undefined)
+            record.color = color;
+        if (normal !== undefined)
+            record.normal = normal;
+        if (roughness !== undefined)
+            record.roughness = roughness;
+        if (ao !== undefined)
+            record.ao = ao;
+        if (metalness !== undefined)
+            record.metalness = metalness;
+        return record;
+    }, [color, normal, roughness, ao, metalness]);
+    const [loaded, setLoaded] = useState(undefined);
+    useEffect(() => {
+        const entries = Object.entries(urls);
+        if (entries.length === 0) {
+            setLoaded(undefined);
+            return;
+        }
+        let cancelled = false;
+        Promise.all(entries.map(([role, url]) => loadSurfaceTexture(url).then((texture) => [role, texture]))).then((results) => {
+            if (cancelled)
+                return;
+            const record = {};
+            for (const [role, texture] of results)
+                if (texture !== null)
+                    record[role] = texture;
+            setLoaded(Object.keys(record).length === 0 ? undefined : record);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [urls]);
+    const [repeatX, repeatY] = surface === undefined ? [1, 1] : repeatOf(surface);
+    const textures = useMemo(() => {
+        if (loaded === undefined)
+            return undefined;
+        const out = {};
+        for (const role of SURFACE_ROLES) {
+            const source = loaded[role];
+            if (source === undefined)
+                continue;
+            const texture = source.clone();
+            texture.wrapS = THREE.RepeatWrapping;
+            texture.wrapT = THREE.RepeatWrapping;
+            texture.repeat.set(repeatX, repeatY);
+            texture.colorSpace = role === "color" ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+            texture.needsUpdate = true;
+            out[role] = texture;
+        }
+        return out;
+    }, [loaded, repeatX, repeatY]);
+    useEffect(() => () => {
+        if (textures === undefined)
+            return;
+        for (const role of SURFACE_ROLES)
+            textures[role]?.dispose();
+    }, [textures]);
+    return textures;
+}
+/** Applies a surface's colour, response, and loaded maps onto a standard or physical material in place. @internal */
+export function applyBuildingSurface(material, surface, textures) {
+    if (surface.color !== undefined)
+        material.color.set(surface.color);
+    if (surface.roughness !== undefined)
+        material.roughness = surface.roughness;
+    if (surface.metalness !== undefined)
+        material.metalness = surface.metalness;
+    if (textures !== undefined) {
+        if (textures.color !== undefined)
+            material.map = textures.color;
+        if (textures.normal !== undefined)
+            material.normalMap = textures.normal;
+        if (textures.roughness !== undefined)
+            material.roughnessMap = textures.roughness;
+        if (textures.ao !== undefined)
+            material.aoMap = textures.ao;
+        if (textures.metalness !== undefined)
+            material.metalnessMap = textures.metalness;
+        material.needsUpdate = true;
+    }
+    return material;
+}

package/dist/useShellMultiplayerSync.d.ts

@@ -1,6 +1,6 @@
 import { type Dispatch, type SetStateAction } from "react";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
-import type { PresencePoseRow } from "@jgengine/core/runtime/transport";
+import { type PresencePoseRow } from "@jgengine/core/runtime/transport";
 import { type AuthoritativeFrameHandler } from "./worldSync.js";
 import type { ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";

package/dist/useShellMultiplayerSync.js

@@ -1,5 +1,6 @@
 import { useEffect, useState, useCallback } from "react";
 import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { createTransportSessionId } from "@jgengine/core/runtime/transport";
 import { attachWorldSync } from "./worldSync.js";
 /** Joins the multiplayer server for the live context and wires presence, feed relay, and chat sync until teardown. */
 export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef, setRemotePlayers, authoritativeFrameRef) {
@@ -14,8 +15,9 @@ export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef,
         setFailureReason(null);
         let disposed = false;
         const cleanups = [];
+        const sessionId = createTransportSessionId();
         void multiplayer.backend.transport
-            .joinServer({ gameId: multiplayer.gameId })
+            .joinServer({ gameId: multiplayer.gameId, sessionId })
             .then((joined) => {
             if (!joined.ok) {
                 if (!disposed) {
@@ -25,7 +27,7 @@ export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef,
                 return;
             }
             if (disposed) {
-                void multiplayer.backend.transport.leaveServer({ serverId: joined.serverId });
+                void multiplayer.backend.transport.leaveServer({ serverId: joined.serverId, sessionId }).catch(() => undefined);
                 return;
             }
             serverIdRef.current = joined.serverId;
@@ -110,7 +112,7 @@ export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef,
             serverIdRef.current = null;
             setRemotePlayers([]);
             if (serverId !== null) {
-                void multiplayer.backend.transport.leaveServer({ serverId }).catch(() => undefined);
+                void multiplayer.backend.transport.leaveServer({ serverId, sessionId }).catch(() => undefined);
             }
         };
     }, [ctx, multiplayer, playable, attempt]);

package/dist/world/WorldParticles.js

@@ -4,7 +4,7 @@ import { useEffect, useRef, useState } from "react";
 import { createParticleSystem } from "@jgengine/core/vfx/particles";
 import { useGameContext } from "@jgengine/react/provider";
 import { ParticleField } from "../vfx/ParticleField.js";
-const QUALITY_POOL_CAP = { low: 128, medium: 256, high: 512 };
+const QUALITY_POOL_CAP = { low: 128, medium: 256, high: 512, ultra: 1024 };
 /**
  * The per-effect particle pool a graphics tier allows: the requested `max`
  * clamped to the tier cap, so lower tiers degrade density instead of dropping

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.18.1",
+  "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.1",
-    "@jgengine/react": "^0.18.1",
-    "@jgengine/ws": "^0.18.1"
+    "@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.
 - Durable process changes belong in skills, not only the handoff.

package/skills/game-design/SKILL.md

@@ -33,8 +33,8 @@ An audit is not completion for a build/improve request. Finish when the slice is
 
 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.
 
-Declare currency `decimals` for income paid per second. Anchor time-based decay to `game.createdAt` or a persisted per-instance creation time, never a fixed wall-clock epoch. Test fractional income over real tick cadences before tuning prices.
+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, compose neighborhood presence, declared command read scopes, membership storage, online-player batched ticks, territory, chat, and join retry UI through their engine owners. Verify capacity and first-player onboarding before scaling the content catalog.
+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,7 +5,9 @@ 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
 
@@ -20,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.
 
@@ -46,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.