@jgengine/shell 0.10.0 → 0.12.0

package/dist/gameKit.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The happy-path game kit — one import surface covering a whole simple game: authoring
+ * (`defineGame`), mounting (`GameHost`), serializable state (`defineStore`), behavior
+ * (`defineSystem`), the authored-scene document helpers, HUD primitives, and deterministic
+ * randomness. Start here; reach for deep package paths only when a game outgrows the kit.
+ *
+ * @capability game-kit one-stop happy-path import surface for authoring, mounting, state, systems, authored scenes, and HUD
+ */
+export { defineGame, type GameConfig } from "./defineGame.js";
+export { GameHost, type GameHostProps, type EditorSummonModule } from "./GameHost.js";
+export type { PlayableGame } from "./registry.js";
+export { defineStore, type StoreHandle } from "@jgengine/core/store/defineStore";
+export { defineKeyedStore } from "@jgengine/core/store/defineKeyedStore";
+export { defineSystem, type SystemDefinition } from "@jgengine/core/game/defineSystem";
+export type { GameContext } from "@jgengine/core/runtime/gameContext";
+export type { GameLoop } from "@jgengine/core/game/defineGame";
+export { normalizeEditorLayers } from "@jgengine/core/editor/document";
+export type { EditorDocument, EditorCatalogDefinition } from "@jgengine/core/editor/types";
+export { authoredSpawnPosition } from "@jgengine/core/world/authoredSpawn";
+export { collectAuthoredTriggers } from "@jgengine/core/scene/authoredTriggers";
+export { environmentContentFromDocument } from "@jgengine/core/editor/environment";
+export { environment } from "@jgengine/core/world/features";
+export type { GameCameraConfig } from "@jgengine/core/game/playableGame";
+export { HudCanvas, HudPanel, useHudLayout } from "@jgengine/react/hudLayout";
+export { StatBar, Hotbar, Clock, Coins } from "@jgengine/react/hud";
+export { seededRng } from "@jgengine/core/random/rng";
+export { offline } from "@jgengine/core/runtime/adapter";

package/dist/gameKit.js

@@ -0,0 +1,29 @@
+/**
+ * The happy-path game kit — one import surface covering a whole simple game: authoring
+ * (`defineGame`), mounting (`GameHost`), serializable state (`defineStore`), behavior
+ * (`defineSystem`), the authored-scene document helpers, HUD primitives, and deterministic
+ * randomness. Start here; reach for deep package paths only when a game outgrows the kit.
+ *
+ * @capability game-kit one-stop happy-path import surface for authoring, mounting, state, systems, authored scenes, and HUD
+ */
+// Authoring + mounting — the one public path from config to a running game.
+export { defineGame } from "./defineGame.js";
+export { GameHost } from "./GameHost.js";
+// Serializable state + composable behavior.
+export { defineStore } from "@jgengine/core/store/defineStore";
+export { defineKeyedStore } from "@jgengine/core/store/defineKeyedStore";
+export { defineSystem } from "@jgengine/core/game/defineSystem";
+// Authored scene document — normalize `editor.scene.json`, read spawns and trigger volumes.
+export { normalizeEditorLayers } from "@jgengine/core/editor/document";
+export { authoredSpawnPosition } from "@jgengine/core/world/authoredSpawn";
+export { collectAuthoredTriggers } from "@jgengine/core/scene/authoredTriggers";
+export { environmentContentFromDocument } from "@jgengine/core/editor/environment";
+// World + camera.
+export { environment } from "@jgengine/core/world/features";
+// HUD layout + optional building blocks — games own custom chrome (not a stock face).
+export { HudCanvas, HudPanel, useHudLayout } from "@jgengine/react/hudLayout";
+export { StatBar, Hotbar, Clock, Coins } from "@jgengine/react/hud";
+// Deterministic randomness (inject seeds; never Math.random in game logic).
+export { seededRng } from "@jgengine/core/random/rng";
+// Multiplayer story: omit `multiplayer` entirely for solo — offline is the shell default.
+export { offline } from "@jgengine/core/runtime/adapter";

package/dist/hotbarActions.d.ts

@@ -0,0 +1,26 @@
+import { type ActionCodesMap } from "@jgengine/core/input/actionBindings";
+import type { Aim } from "@jgengine/core/scene/spatial";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+type Inventories = Record<string, {
+    hud?: string;
+}>;
+/** Minimal playable slice — avoids coupling to shell vs core PlayableGame generics. @internal */
+export type HotbarPlayable = {
+    game: {
+        inventories?: Inventories;
+        input?: ActionCodesMap;
+    };
+};
+/** @internal Map bound action names to hotbar slot indices. */
+export declare function findHotbarSlotActions(input: ActionCodesMap | undefined): {
+    action: string;
+    slot: number;
+}[];
+/** @internal Resolve the inventory id used as the hotbar HUD binding. */
+export declare function hotbarIdFor(playable: HotbarPlayable): string | null;
+/** @internal Activate an item from a hotbar slot via `ctx.item.use`. */
+export declare function executeHotbarSlot(ctx: GameContext, fromId: string, hotbarId: string, slot: number, yaw: number, pitch: number, aimOverride?: Aim): {
+    ok: boolean;
+    error?: string;
+};
+export {};

package/dist/hotbarActions.js

@@ -0,0 +1,27 @@
+import { hotbarSlotActionIndex } from "@jgengine/core/input/actionBindings";
+/** @internal Map bound action names to hotbar slot indices. */
+export function findHotbarSlotActions(input) {
+    return Object.keys(input ?? {}).flatMap((action) => {
+        const slot = hotbarSlotActionIndex(action);
+        return slot === null ? [] : [{ action, slot }];
+    });
+}
+/** @internal Resolve the inventory id used as the hotbar HUD binding. */
+export function hotbarIdFor(playable) {
+    const declarations = Object.entries(playable.game.inventories ?? {});
+    const hud = declarations.find(([, declaration]) => declaration.hud === "hotbar");
+    return (hud ?? declarations[0])?.[0] ?? null;
+}
+/** @internal Activate an item from a hotbar slot via `ctx.item.use`. */
+export function executeHotbarSlot(ctx, fromId, hotbarId, slot, yaw, pitch, aimOverride) {
+    const stack = ctx.player.inventory.state(hotbarId).slots[slot];
+    if (stack === undefined || stack === null)
+        return { ok: false, error: `Hotbar slot ${slot + 1} is empty` };
+    const result = ctx.item.use.use({
+        from: fromId,
+        itemId: stack.itemId,
+        inventoryId: hotbarId,
+        aim: aimOverride ?? { yaw, pitch },
+    });
+    return result.error === undefined ? { ok: true } : { ok: false, error: result.error };
+}

package/dist/inputSink.d.ts

@@ -4,15 +4,27 @@ import type { LiveGameBackend } from "@jgengine/core/runtime/transport";
 export interface InputSink {
     send(frame: InputFrame): void;
 }
-/** Discards input — the single-player / client-authoritative default, where the client integrates movement itself. */
+/** Discards input — the single-player / client-authoritative default, where the client integrates movement itself.
+ * @internal
+ */
 export declare function noopInputSink(): InputSink;
-/** Sends each frame's input to the authoritative host over the transport, reusing the `runCommand` path via {@link INPUT_COMMAND}. */
+/**
+ * Sends each frame's input to the authoritative host over the transport, reusing the `runCommand` path via
+ * {@link INPUT_COMMAND}. Sends are sequenced one-in-flight-at-a-time per `serverId` and stamped with a monotonic
+ * seq: a frame sent while one is already in flight replaces the pending frame rather than racing it, so the
+ * latest intent always wins and a stale frame can never resolve after (and overwrite) a newer one.
+ * @internal
+ */
 export declare function remoteInputSink(backend: Pick<LiveGameBackend, "transport">, serverId: string): InputSink;
-/** The sink a server-authoritative shell sends its per-frame input through: remote when `authority: "server"` and a server is joined, a no-op otherwise. */
+/** The sink a server-authoritative shell sends its per-frame input through: remote when `authority: "server"` and a server is joined, a no-op otherwise.
+ * @internal
+ */
 export declare function resolveInputSink(opts: {
     serverAuthoritative: boolean;
     backend: Pick<LiveGameBackend, "transport"> | null;
     serverId: string | null;
 }): InputSink;
-/** Whether two input frames carry identical intent — the shell skips resending unchanged frames so a still player floods the host with nothing. */
+/** Whether two input frames carry identical intent — the shell skips resending unchanged frames so a still player floods the host with nothing.
+ * @internal
+ */
 export declare function inputFramesEqual(a: InputFrame, b: InputFrame): boolean;

package/dist/inputSink.js

@@ -1,26 +1,76 @@
 import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
-/** Discards input — the single-player / client-authoritative default, where the client integrates movement itself. */
+/** Discards input — the single-player / client-authoritative default, where the client integrates movement itself.
+ * @internal
+ */
 export function noopInputSink() {
     return { send() { } };
 }
-/** Sends each frame's input to the authoritative host over the transport, reusing the `runCommand` path via {@link INPUT_COMMAND}. */
+const remoteInputSources = new Map();
+function remoteInputSourceFor(serverId) {
+    let source = remoteInputSources.get(serverId);
+    if (source === undefined) {
+        source = { pending: null, inFlight: false };
+        remoteInputSources.set(serverId, source);
+    }
+    return source;
+}
+function monotonicInputSeq() {
+    return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function pumpRemoteInput(backend, serverId, source) {
+    if (source.inFlight)
+        return;
+    const frame = source.pending;
+    if (frame === null) {
+        remoteInputSources.delete(serverId);
+        return;
+    }
+    source.pending = null;
+    source.inFlight = true;
+    const seq = monotonicInputSeq();
+    void backend.transport
+        .runCommand({ serverId, command: INPUT_COMMAND, input: { ...frame, seq } })
+        .then((result) => {
+        if (!result.ok) {
+            console.warn(`[jgengine:input] frame seq=${seq} to server "${serverId}" rejected: ${result.reason}`);
+        }
+    })
+        .catch((error) => {
+        console.warn(`[jgengine:input] frame seq=${seq} to server "${serverId}" failed to send`, error);
+    })
+        .finally(() => {
+        source.inFlight = false;
+        pumpRemoteInput(backend, serverId, source);
+    });
+}
+/**
+ * Sends each frame's input to the authoritative host over the transport, reusing the `runCommand` path via
+ * {@link INPUT_COMMAND}. Sends are sequenced one-in-flight-at-a-time per `serverId` and stamped with a monotonic
+ * seq: a frame sent while one is already in flight replaces the pending frame rather than racing it, so the
+ * latest intent always wins and a stale frame can never resolve after (and overwrite) a newer one.
+ * @internal
+ */
 export function remoteInputSink(backend, serverId) {
     return {
         send(frame) {
-            void backend.transport
-                .runCommand({ serverId, command: INPUT_COMMAND, input: frame })
-                .catch(() => undefined);
+            const source = remoteInputSourceFor(serverId);
+            source.pending = frame;
+            pumpRemoteInput(backend, serverId, source);
         },
     };
 }
-/** The sink a server-authoritative shell sends its per-frame input through: remote when `authority: "server"` and a server is joined, a no-op otherwise. */
+/** The sink a server-authoritative shell sends its per-frame input through: remote when `authority: "server"` and a server is joined, a no-op otherwise.
+ * @internal
+ */
 export function resolveInputSink(opts) {
     if (opts.serverAuthoritative && opts.backend !== null && opts.serverId !== null) {
         return remoteInputSink(opts.backend, opts.serverId);
     }
     return noopInputSink();
 }
-/** Whether two input frames carry identical intent — the shell skips resending unchanged frames so a still player floods the host with nothing. */
+/** Whether two input frames carry identical intent — the shell skips resending unchanged frames so a still player floods the host with nothing.
+ * @internal
+ */
 export function inputFramesEqual(a, b) {
     if (a.held.length !== b.held.length)
         return false;

package/dist/map/MapMarkerBeacons.d.ts

@@ -1,6 +1,7 @@
-import { type MarkerKindStyle, type MarkerSet } from "@jgengine/core/world/markers";
+import { type MarkerCollection, type MarkerKindStyle } from "@jgengine/core/world/markers";
 export interface MapMarkerBeaconsProps {
-    markers: MarkerSet;
+    /** Static views, an external marker source, or a native JGengine MarkerSet. */
+    markers: MarkerCollection;
     kindStyles?: Record<string, MarkerKindStyle>;
     height?: number;
 }

package/dist/materialOverride.d.ts

@@ -2,5 +2,15 @@ import * as THREE from "three";
 import type { ModelMaterialOverride } from "@jgengine/core/game/playableGame";
 export interface MaterialOverrideOptions {
     clone?: boolean;
+    /** Loaded PBR textures matching `ModelMaterialOverride.maps`' roles, applied onto each `MeshStandardMaterial` alongside the tint override. The caller (a React component, via `useTexture`) owns loading; this function never fetches a URL. */
+    textures?: MaterialOverrideTextures;
 }
+/** Loaded PBR textures for `applyMaterialOverride`'s `textures` option — matches `ModelMaterialMaps`' roles. */
+export interface MaterialOverrideTextures {
+    color?: THREE.Texture;
+    normal?: THREE.Texture;
+    roughness?: THREE.Texture;
+    ao?: THREE.Texture;
+}
+/** @internal */
 export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride, options?: MaterialOverrideOptions): void;

package/dist/materialOverride.js

@@ -1,16 +1,18 @@
 import * as THREE from "three";
+/** @internal */
 export function applyMaterialOverride(root, override, options) {
     const clone = options?.clone !== false;
+    const textures = options?.textures;
     root.traverse((node) => {
         const mesh = node;
         if (!mesh.isMesh)
             return;
         mesh.material = Array.isArray(mesh.material)
-            ? mesh.material.map((material) => overrideOne(material, override, clone))
-            : overrideOne(mesh.material, override, clone);
+            ? mesh.material.map((material) => overrideOne(material, override, clone, textures))
+            : overrideOne(mesh.material, override, clone, textures);
     });
 }
-function overrideOne(material, override, clone) {
+function overrideOne(material, override, clone, textures) {
     if (!(material instanceof THREE.MeshStandardMaterial))
         return material;
     const target = clone ? material.clone() : material;
@@ -24,5 +26,15 @@ function overrideOne(material, override, clone) {
         target.emissive.set(override.emissive);
     if (override.emissiveIntensity !== undefined)
         target.emissiveIntensity = override.emissiveIntensity;
+    if (textures?.color !== undefined)
+        target.map = textures.color;
+    if (textures?.normal !== undefined)
+        target.normalMap = textures.normal;
+    if (textures?.roughness !== undefined)
+        target.roughnessMap = textures.roughness;
+    if (textures?.ao !== undefined)
+        target.aoMap = textures.ao;
+    if (textures !== undefined)
+        target.needsUpdate = true;
     return target;
 }

package/dist/multiplayer.js

@@ -29,16 +29,22 @@ export function resolveShellMultiplayer(args) {
     if (args.force === true)
         return build(args.url ?? DEFAULT_WS_URL);
     const adapter = adapterOf(args.game.multiplayer);
-    if (adapter === null)
+    if (adapter === null || adapter.kind === "offline")
         return null;
     if (adapter.kind === "ws") {
         const url = args.url ?? adapter.url;
-        if (url === undefined && isServerAuthoritative(args.game.multiplayer))
+        if (url === undefined && isServerAuthoritative(args.game.multiplayer)) {
+            console.warn(`[jgengine:multiplayer] ${args.gameId}: ws({ authority: "server" }) has no url; falling back to single-player. ` +
+                `Pass a url (or set adapter.url) so the shell can reach the host.`);
             return null;
+        }
         return build(url ?? DEFAULT_WS_URL);
     }
     if (adapter.kind === "lan")
         return build(args.url ?? lanUrl(adapter));
+    console.warn(`[jgengine:multiplayer] ${args.gameId}: multiplayer adapter "${adapter.kind}" needs its own session bootstrap ` +
+        `(e.g. resolvePeerShellMultiplayer for p2p()); resolveShellMultiplayer cannot build a ws backend for it, ` +
+        `so the game shipped single-player. Wire up the ${adapter.kind} transport or switch to ws()/lan().`);
     return null;
 }
 export async function resolvePeerShellMultiplayer(args) {

package/dist/postfx/PostProcessing.d.ts

@@ -1,10 +1,18 @@
 import type { PostProcessingConfig } from "@jgengine/core/render/postProcessing";
+import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
  * post chain: RenderPass → GTAO → UnrealBloom → OutputPass → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
+ *
+ * `quality` (the player's graphics-quality setting) gates the passes whose cost
+ * scales with scene geometry or resolution beyond the dpr cap: GTAO re-renders
+ * the whole scene for depth/normals and runs a multi-sample full-screen pass,
+ * and Bokeh DOF renders scene depth again — both run on "high" only. Bloom,
+ * tone mapping, and grade stay on every tier.
  */
-export declare function PostProcessing({ config }: {
+export declare function PostProcessing({ config, quality }: {
     config: PostProcessingConfig;
+    quality?: GraphicsQuality;
 }): null;

package/dist/postfx/PostProcessing.js

@@ -1,9 +1,10 @@
 import { useFrame, useThree } from "@react-three/fiber";
-import { useEffect, useMemo } from "react";
+import { useEffect, useRef } from "react";
 import * as THREE from "three";
 import { EffectComposer, RenderPass, UnrealBloomPass } from "three-stdlib";
 import { OutputPass } from "three/examples/jsm/postprocessing/OutputPass.js";
 import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
+import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
 import { createGradePass } from "./gradeShader.js";
 const TONE_MAPPING = {
     aces: THREE.ACESFilmicToneMapping,
@@ -13,18 +14,42 @@ const TONE_MAPPING = {
     linear: THREE.LinearToneMapping,
     none: THREE.NoToneMapping,
 };
+function disposeGraph(built) {
+    for (const pass of built.composer.passes)
+        pass.dispose();
+    if (built.dof !== null) {
+        built.dof.renderTargetDepth.dispose();
+        built.dof.materialDepth.dispose();
+        built.dof.materialBokeh.dispose();
+        built.dof.fsQuad.dispose();
+    }
+    built.composer.dispose();
+}
+function syncSize(built, width, height, pixelRatio) {
+    built.composer.setPixelRatio(pixelRatio);
+    built.composer.setSize(width, height);
+    if (built.dof !== null)
+        built.dof.renderTargetDepth.setSize(width * pixelRatio, height * pixelRatio);
+}
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
  * post chain: RenderPass → GTAO → UnrealBloom → OutputPass → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
+ *
+ * `quality` (the player's graphics-quality setting) gates the passes whose cost
+ * scales with scene geometry or resolution beyond the dpr cap: GTAO re-renders
+ * the whole scene for depth/normals and runs a multi-sample full-screen pass,
+ * and Bokeh DOF renders scene depth again — both run on "high" only. Bloom,
+ * tone mapping, and grade stay on every tier.
  */
-export function PostProcessing({ config }) {
+export function PostProcessing({ config, quality = "high" }) {
     const gl = useThree((s) => s.gl);
     const scene = useThree((s) => s.scene);
     const camera = useThree((s) => s.camera);
     const size = useThree((s) => s.size);
-    const built = useMemo(() => {
+    const builtRef = useRef(null);
+    useEffect(() => {
         const width = Math.max(1, size.width);
         const height = Math.max(1, size.height);
         const target = new THREE.WebGLRenderTarget(width, height, {
@@ -33,7 +58,8 @@ export function PostProcessing({ config }) {
         });
         const composer = new EffectComposer(gl, target);
         composer.addPass(new RenderPass(scene, camera));
-        if (config.ao !== undefined && config.ao !== false) {
+        const heavyPasses = quality === "high";
+        if (heavyPasses && config.ao !== undefined && config.ao !== false) {
             const ao = new GTAOPass(scene, camera, width, height);
             ao.blendIntensity = config.ao.blend ?? 1;
             ao.updateGtaoMaterial({
@@ -49,14 +75,30 @@ export function PostProcessing({ config }) {
             const b = config.bloom ?? {};
             composer.addPass(new UnrealBloomPass(new THREE.Vector2(width, height), b.strength ?? 0.32, b.radius ?? 0.55, b.threshold ?? 0.85));
         }
+        let dof = null;
+        if (heavyPasses && config.dof !== undefined && config.dof !== false) {
+            const d = config.dof;
+            dof = new BokehPass(scene, camera, {
+                focus: d.focus ?? 18,
+                aperture: d.aperture ?? 0.00025,
+                maxblur: d.maxBlur ?? 0.01,
+            });
+            composer.addPass(dof);
+        }
         composer.addPass(new OutputPass());
         let grade = null;
         if (config.grade !== false) {
             grade = createGradePass(config.grade ?? {});
             composer.addPass(grade);
         }
-        return { composer, grade };
-    }, [gl, scene, camera, config, size.width, size.height]);
+        const graph = { composer, grade, dof };
+        syncSize(graph, width, height, gl.getPixelRatio());
+        builtRef.current = graph;
+        return () => {
+            disposeGraph(graph);
+            builtRef.current = null;
+        };
+    }, [gl, scene, camera, config, quality]);
     useEffect(() => {
         const prevTone = gl.toneMapping;
         const prevExposure = gl.toneMappingExposure;
@@ -68,12 +110,15 @@ export function PostProcessing({ config }) {
         };
     }, [gl, config.toneMapping, config.exposure]);
     useEffect(() => {
-        const { composer } = built;
-        composer.setPixelRatio(gl.getPixelRatio());
-        composer.setSize(size.width, size.height);
-        return () => composer.dispose();
-    }, [built, gl, size.width, size.height]);
+        const built = builtRef.current;
+        if (built === null)
+            return;
+        syncSize(built, Math.max(1, size.width), Math.max(1, size.height), gl.getPixelRatio());
+    }, [gl, size.width, size.height]);
     useFrame((_, delta) => {
+        const built = builtRef.current;
+        if (built === null)
+            return;
         if (built.grade !== null)
             built.grade.uniforms.uTime.value += delta;
         built.composer.render(delta);

package/dist/postfx/gradeShader.js

@@ -6,6 +6,7 @@ const DEFAULT_GAMMA = 0.96;
 const DEFAULT_SATURATION = 1.12;
 const DEFAULT_VIGNETTE = 0.2;
 const DEFAULT_GRAIN = 0.012;
+const DEFAULT_CHROMA = 0;
 const fragmentShader = /* glsl */ `
   uniform sampler2D tDiffuse;
   uniform vec3 uLift;
@@ -14,6 +15,7 @@ const fragmentShader = /* glsl */ `
   uniform float uSaturation;
   uniform float uVignette;
   uniform float uGrain;
+  uniform float uChroma;
   uniform float uTime;
   varying vec2 vUv;
 
@@ -22,7 +24,12 @@ const fragmentShader = /* glsl */ `
   }
 
   void main() {
-    vec3 c = texture2D(tDiffuse, vUv).rgb;
+    vec2 dir = vUv - 0.5;
+    // Chromatic aberration: split RGB along the radial direction, growing toward the edges.
+    vec2 shift = uChroma > 0.0 ? dir * uChroma * dot(dir, dir) * 4.0 : vec2(0.0);
+    vec3 c = uChroma > 0.0
+      ? vec3(texture2D(tDiffuse, vUv + shift).r, texture2D(tDiffuse, vUv).g, texture2D(tDiffuse, vUv - shift).b)
+      : texture2D(tDiffuse, vUv).rgb;
     c = c + uLift;
     c = c * uGain;
     c = pow(max(c, 0.0), vec3(uGamma));
@@ -56,6 +63,7 @@ export function createGradePass(config = {}) {
             uSaturation: { value: config.saturation ?? DEFAULT_SATURATION },
             uVignette: { value: config.vignette ?? DEFAULT_VIGNETTE },
             uGrain: { value: config.grain ?? DEFAULT_GRAIN },
+            uChroma: { value: config.chromaticAberration ?? DEFAULT_CHROMA },
             uTime: { value: 0 },
         },
         vertexShader,

package/dist/presentationResolve.d.ts

@@ -0,0 +1,35 @@
+import type { CatalogEntityRole } from "@jgengine/core/runtime/gameContext";
+import type { PresentationEffectsConfig } from "@jgengine/core/game/playableGame";
+/** Resolved world-bar / nameplate config, or `null` when the feature is off. @internal */
+export interface ResolvedWorldOverlayBars {
+    statId: string;
+    roles?: readonly CatalogEntityRole[];
+    maxDistance?: number;
+}
+/**
+ * Normalize `worldHealthBars` / `nameplates` (`boolean | object | undefined`) into a
+ * single resolved shape. `undefined` / `false` → `null` (off); `true` → default stat `"health"`;
+ * object → explicit fields with `statId` defaulting to `"health"`.
+ * @internal
+ */
+export declare function resolveWorldOverlayBars(config: boolean | {
+    statId?: string;
+    roles?: readonly CatalogEntityRole[];
+    maxDistance?: number;
+} | undefined): ResolvedWorldOverlayBars | null;
+/** Resolved combat presentation channels (each boolean is whether that stack piece mounts). @internal */
+export interface ResolvedPresentationEffects {
+    telegraphs: boolean;
+    vfx: boolean;
+    floatText: boolean;
+    tracers: boolean;
+    shake: boolean;
+}
+/**
+ * Resolve `presentationEffects` for the 3D shell.
+ * - `undefined` / `true` → all channels on (historical default).
+ * - `false` → none.
+ * - object → per-channel; missing keys default to on so games can disable one channel.
+ * @internal
+ */
+export declare function resolvePresentationEffects(config: boolean | PresentationEffectsConfig | undefined): ResolvedPresentationEffects;

package/dist/presentationResolve.js

@@ -0,0 +1,51 @@
+/**
+ * Normalize `worldHealthBars` / `nameplates` (`boolean | object | undefined`) into a
+ * single resolved shape. `undefined` / `false` → `null` (off); `true` → default stat `"health"`;
+ * object → explicit fields with `statId` defaulting to `"health"`.
+ * @internal
+ */
+export function resolveWorldOverlayBars(config) {
+    if (config === undefined || config === false)
+        return null;
+    if (config === true)
+        return { statId: "health" };
+    return {
+        statId: config.statId ?? "health",
+        ...(config.roles === undefined ? {} : { roles: config.roles }),
+        ...(config.maxDistance === undefined ? {} : { maxDistance: config.maxDistance }),
+    };
+}
+const ALL_ON = {
+    telegraphs: true,
+    vfx: true,
+    floatText: true,
+    tracers: true,
+    shake: true,
+};
+const ALL_OFF = {
+    telegraphs: false,
+    vfx: false,
+    floatText: false,
+    tracers: false,
+    shake: false,
+};
+/**
+ * Resolve `presentationEffects` for the 3D shell.
+ * - `undefined` / `true` → all channels on (historical default).
+ * - `false` → none.
+ * - object → per-channel; missing keys default to on so games can disable one channel.
+ * @internal
+ */
+export function resolvePresentationEffects(config) {
+    if (config === false)
+        return ALL_OFF;
+    if (config === undefined || config === true)
+        return ALL_ON;
+    return {
+        telegraphs: config.telegraphs !== false,
+        vfx: config.vfx !== false,
+        floatText: config.floatText !== false,
+        tracers: config.tracers !== false,
+        shake: config.shake !== false,
+    };
+}

package/dist/registry.d.ts

@@ -1,9 +1,11 @@
 import type { ComponentType, ReactNode } from "react";
-import type { PlayableGame as EnginePlayableGame } from "@jgengine/core/game/playableGame";
+import type { PlayableGame as EnginePlayableGame, WorldOverlayProps } from "@jgengine/core/game/playableGame";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import type { ViewmodelProps } from "./camera/GameFirstPersonCamera.js";
 export type RenderEntity = (entity: SceneEntity) => ReactNode;
 export type RenderObject = (object: SceneObject) => ReactNode;
-export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity, RenderObject>;
+/** The concrete React-bound playable a shell `defineGame` returns and `GameHost` mounts — the one PlayableGame games handle. */
+export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps>>;
 export type GameRegistry = Record<string, () => Promise<PlayableGame>>;
 export declare function resolveGameLoader(registry: GameRegistry, gameId: string, fallbackGameId?: string): (() => Promise<PlayableGame>) | undefined;

package/dist/render/EnvironmentLighting.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sets a neutral, network-free image-based-lighting environment on the scene so every
+ * `MeshStandardMaterial` — models and un-modeled primitive fallbacks alike — picks up soft
+ * reflections and fill instead of rendering dead-flat. A game's own sky/lighting still layers on
+ * top; this only supplies the reflective ambient the shell never had. Opt out with `look: "flat"`.
+ * @internal shell-internal default lighting; games never import it.
+ */
+export declare function EnvironmentLighting({ intensity }: {
+    intensity?: number;
+}): null;

package/dist/render/EnvironmentLighting.js

@@ -0,0 +1,34 @@
+import { useThree } from "@react-three/fiber";
+import { useEffect } from "react";
+import * as THREE from "three";
+import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
+/**
+ * Sets a neutral, network-free image-based-lighting environment on the scene so every
+ * `MeshStandardMaterial` — models and un-modeled primitive fallbacks alike — picks up soft
+ * reflections and fill instead of rendering dead-flat. A game's own sky/lighting still layers on
+ * top; this only supplies the reflective ambient the shell never had. Opt out with `look: "flat"`.
+ * @internal shell-internal default lighting; games never import it.
+ */
+export function EnvironmentLighting({ intensity = 0.28 }) {
+    const gl = useThree((state) => state.gl);
+    const scene = useThree((state) => state.scene);
+    useEffect(() => {
+        const pmrem = new THREE.PMREMGenerator(gl);
+        const room = new RoomEnvironment();
+        const target = pmrem.fromScene(room, 0.04);
+        const previous = scene.environment;
+        scene.environment = target.texture;
+        const sceneWithIntensity = scene;
+        const previousIntensity = sceneWithIntensity.environmentIntensity;
+        sceneWithIntensity.environmentIntensity = intensity;
+        room.dispose?.();
+        pmrem.dispose();
+        return () => {
+            target.dispose();
+            scene.environment = previous;
+            if (previousIntensity !== undefined)
+                sceneWithIntensity.environmentIntensity = previousIntensity;
+        };
+    }, [gl, scene, intensity]);
+    return null;
+}