@jgengine/shell 0.11.0 → 0.12.0

package/dist/devtools/DevtoolsOverlay.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useFrame } from "@react-three/fiber";
+import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { devtools, instrumentLatency, } from "@jgengine/core/devtools/devtools";
+import { fallbackSeamsSnapshot } from "@jgengine/core/devtools/fallbackSeams";
 import { MOVEMENT_TUNING } from "@jgengine/core/movement/movementModel";
 import { collisionDebug } from "./collisionDebug.js";
 import { readStoredOverrides } from "./devtoolsOverrides.js";
@@ -24,21 +25,35 @@ export function withDevtoolsLatency(multiplayer) {
         },
     };
 }
+const RENDER_SAMPLE_MS = 500;
+const RENDER_PROBE_FRAME_PRIORITY = -10;
 /** @internal */
 export function DevtoolsRendererProbe() {
-    const frameCounter = useRef(0);
+    const gl = useThree((state) => state.gl);
+    const lastSampleAt = useRef(0);
+    useEffect(() => {
+        // three resets gl.info after every render() call, so with a multi-pass
+        // composer the counters only ever hold the last fullscreen pass. Own the
+        // reset instead: accumulate across the whole frame, reset at frame start.
+        gl.info.autoReset = false;
+        return () => {
+            gl.info.autoReset = true;
+        };
+    }, [gl]);
     useFrame((state) => {
-        frameCounter.current += 1;
-        if (frameCounter.current % 30 !== 0)
-            return;
         const info = state.gl.info;
-        devtools.render.record({
-            drawCalls: info.render.calls,
-            triangles: info.render.triangles,
-            geometries: info.memory.geometries,
-            textures: info.memory.textures,
-        });
-    });
+        const now = performance.now();
+        if (now - lastSampleAt.current >= RENDER_SAMPLE_MS) {
+            lastSampleAt.current = now;
+            devtools.render.record({
+                drawCalls: info.render.calls,
+                triangles: info.render.triangles,
+                geometries: info.memory.geometries,
+                textures: info.memory.textures,
+            });
+        }
+        info.reset();
+    }, RENDER_PROBE_FRAME_PRIORITY);
     return null;
 }
 const TABS = [
@@ -194,6 +209,7 @@ export function DevtoolsOverlay({ open, ctx, playable, multiplayer, }) {
         const disposers = [
             devtools.probes.register("entities", () => ctx.scene.entity.list().length),
             devtools.probes.register("objects", () => ctx.scene.object.list().length),
+            devtools.probes.register("fallbacks", () => fallbackSeamsSnapshot()),
         ];
         return () => {
             for (const dispose of disposers)

package/dist/devtools/agentBridge.js

@@ -1,3 +1,4 @@
+import { devtools } from "@jgengine/core/devtools/devtools";
 import { getSaveEndpoint } from "@jgengine/core/devtools/saveEndpoint";
 import { isHudAnchor, listActiveHudLayouts, } from "@jgengine/core/ui/hudLayout";
 import { listHudPanelTypes, resolvePanelResize, resizePanelSize, } from "@jgengine/core/ui/hudDocument";
@@ -104,6 +105,9 @@ export function installAgentBridge(options) {
                 return { ok: true, snapshot: buildLeanReport(playable) };
             case "debug_report":
                 return { ok: true, report: buildFullReport(playable) };
+            case "debug_perf_reset":
+                devtools.frame.reset();
+                return { ok: true };
             case "canvas_state":
                 return { ok: true, layouts: canvasPanels() };
             case "canvas_set_editing": {

package/dist/devtools/perfDiagnose.js

@@ -1,7 +1,7 @@
 import { devtools, LONG_FRAME_MS } from "@jgengine/core/devtools/devtools";
 import { ms } from "./panelAtoms.js";
 const CULPRIT_HINTS = {
-    "outside-sim": "Cost is outside the sim driver — three.js render, React commit, GPU, GC, or tab throttle.",
+    "outside-sim": "Cost is outside the sim driver — three.js render, React commit, GPU, GC, or tab throttle. Check the render sample: high draw calls/triangles mean scene cost (instancing, culling, terrain density); moderate counts with slow frames mean fill cost (dpr, AO/DOF passes, bloom) — try Quality low/medium.",
     sim: "Sim is slow but no named phase stands out — wrap hot onTick work with measure(\"name\", fn).",
     onTick: "Game loop.onTick is the hotspot — profile inside it with measure(\"physics\"|\"ai\"|…, fn).",
     pose: "Shell movement / collision / voxel step is expensive.",

package/dist/diagnostics/RuntimeDiagnostics.d.ts

@@ -23,6 +23,13 @@ export declare class GameUiErrorBoundary extends Component<{
     componentDidCatch(error: unknown, info: ErrorInfo): void;
     render(): ReactNode;
 }
+/** Standalone error footer text (page, browser, engine) shared by every error surface. */
+export declare function errorReportContext(): string;
+/** "Copy error" + "File issue" buttons for any error surface. `report` is the full text to copy / prefill. */
+export declare function ErrorReportActions({ report, issueTitle }: {
+    report: string;
+    issueTitle: string;
+}): import("react").JSX.Element;
 export declare function DiagnosticOverlay({ diagnostics, gameName }: {
     diagnostics: RuntimeDiagnostic[];
     gameName: string;

package/dist/diagnostics/RuntimeDiagnostics.js

@@ -32,16 +32,35 @@ function expandedReactError(message) {
         ? "Maximum update depth exceeded. A component is repeatedly updating state during render or after every update."
         : null;
 }
+const ISSUES_NEW_URL = "https://github.com/Noisemaker111/jgengine/issues/new";
+/** Standalone error footer text (page, browser, engine) shared by every error surface. */
+export function errorReportContext() {
+    return [
+        `Engine: ${VERSION}`,
+        `Page: ${window.location.origin}${window.location.pathname}`,
+        `Browser: ${navigator.userAgent}`,
+    ].join("\n");
+}
+/** "Copy error" + "File issue" buttons for any error surface. `report` is the full text to copy / prefill. */
+export function ErrorReportActions({ report, issueTitle }) {
+    const [copied, setCopied] = useState(false);
+    const issueBody = report.length > 8000 ? `${report.slice(0, 8000)}\n\n[Report truncated; use Copy error for the full report.]` : report;
+    const issueUrl = `${ISSUES_NEW_URL}?title=${encodeURIComponent(`[BUG] ${issueTitle.slice(0, 120)}`)}&body=${encodeURIComponent(issueBody)}`;
+    return (_jsxs("div", { className: "flex gap-2", children: [_jsx("button", { className: "rounded border border-red-300/50 bg-red-900 px-2 py-1 text-xs font-semibold text-red-50 hover:bg-red-800", type: "button", onClick: () => {
+                    void navigator.clipboard.writeText(report).then(() => {
+                        setCopied(true);
+                        window.setTimeout(() => setCopied(false), 2000);
+                    });
+                }, children: copied ? "Copied" : "Copy error" }), _jsx("a", { className: "rounded border border-red-300/50 bg-red-900 px-2 py-1 text-xs font-semibold text-red-50 hover:bg-red-800", href: issueUrl, rel: "noreferrer", target: "_blank", children: "File issue" })] }));
+}
 function diagnosticReport(diagnostic, gameName) {
     const explanation = expandedReactError(diagnostic.message);
     return [
         "JGengine runtime error",
         `Game: ${gameName}`,
-        `Engine: ${VERSION}`,
         `Phase: ${diagnostic.phase}`,
         `Time: ${diagnostic.capturedAt}`,
-        `Page: ${window.location.origin}${window.location.pathname}`,
-        `Browser: ${navigator.userAgent}`,
+        errorReportContext(),
         explanation === null ? null : `Explanation: ${explanation}`,
         "",
         `Message: ${diagnostic.message}`,
@@ -52,18 +71,10 @@ function diagnosticReport(diagnostic, gameName) {
         .join("\n");
 }
 export function DiagnosticOverlay({ diagnostics, gameName }) {
-    const [copied, setCopied] = useState(false);
     if (diagnostics.length === 0)
         return null;
     const latest = diagnostics[diagnostics.length - 1];
     const explanation = expandedReactError(latest.message);
     const report = diagnosticReport(latest, gameName);
-    const issueBody = report.length > 8000 ? `${report.slice(0, 8000)}\n\n[Report truncated; use Copy error for the full report.]` : report;
-    const issueUrl = `https://github.com/Noisemaker111/jgengine/issues/new?title=${encodeURIComponent(`[BUG] ${latest.phase}: ${latest.message.slice(0, 100)}`)}&body=${encodeURIComponent(issueBody)}`;
-    return (_jsxs("div", { className: "pointer-events-auto absolute right-4 top-4 z-50 max-w-lg rounded border border-red-400/60 bg-red-950/95 p-3 text-xs text-red-50 shadow-2xl", children: [_jsx("div", { className: "mb-1 font-semibold uppercase tracking-wide text-red-200", children: "JG engine error" }), _jsxs("div", { className: "font-mono text-[11px] text-red-100", children: ["[", latest.phase, "] ", latest.message] }), explanation !== null ? _jsx("div", { className: "mt-2 text-red-100", children: explanation }) : null, latest.stack !== undefined ? (_jsx("pre", { className: "mt-2 max-h-36 overflow-auto whitespace-pre-wrap text-[10px] text-red-200/80", children: latest.stack })) : null, latest.componentStack !== undefined ? (_jsx("pre", { className: "mt-2 max-h-36 overflow-auto whitespace-pre-wrap text-[10px] text-red-200/80", children: latest.componentStack })) : null, _jsxs("div", { className: "mt-3 flex gap-2", children: [_jsx("button", { className: "rounded border border-red-300/50 bg-red-900 px-2 py-1 font-semibold hover:bg-red-800", type: "button", onClick: () => {
-                            void navigator.clipboard.writeText(report).then(() => {
-                                setCopied(true);
-                                window.setTimeout(() => setCopied(false), 2000);
-                            });
-                        }, children: copied ? "Copied" : "Copy error" }), _jsx("a", { className: "rounded border border-red-300/50 bg-red-900 px-2 py-1 font-semibold hover:bg-red-800", href: issueUrl, rel: "noreferrer", target: "_blank", children: "File issue" })] })] }));
+    return (_jsxs("div", { className: "pointer-events-auto absolute right-4 top-4 z-50 max-w-lg select-text rounded border border-red-400/60 bg-red-950/95 p-3 text-xs text-red-50 shadow-2xl", children: [_jsx("div", { className: "mb-1 font-semibold uppercase tracking-wide text-red-200", children: "JG engine error" }), _jsxs("div", { className: "font-mono text-[11px] text-red-100", children: ["[", latest.phase, "] ", latest.message] }), explanation !== null ? _jsx("div", { className: "mt-2 text-red-100", children: explanation }) : null, latest.stack !== undefined ? (_jsx("pre", { className: "mt-2 max-h-36 overflow-auto whitespace-pre-wrap text-[10px] text-red-200/80", children: latest.stack })) : null, latest.componentStack !== undefined ? (_jsx("pre", { className: "mt-2 max-h-36 overflow-auto whitespace-pre-wrap text-[10px] text-red-200/80", children: latest.componentStack })) : null, _jsx("div", { className: "mt-3", children: _jsx(ErrorReportActions, { report: report, issueTitle: `${latest.phase}: ${latest.message.slice(0, 100)}` }) })] }));
 }

package/dist/environment/EnvironmentScene.js

@@ -9,6 +9,7 @@ import { resolveStructureBuildings } from "@jgengine/core/world/environmentSumma
 import { createTerrainPaletteSampler, resolveEnvironmentField, resolveTerrainDetail, resolveTerrainPalette, } from "@jgengine/core/world/terrain";
 import { GroundPad } from "./GroundPad.js";
 import { RoadRibbons } from "./RoadRibbons.js";
+import { terrainGroundColorSampler } from "./terrainGroundColor.js";
 import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.js";
 import { CarvedTerrain } from "../terrain/CarvedTerrain.js";
@@ -73,7 +74,7 @@ function TerrainGround({ terrain, field, center, }) {
 function areaCenter(area) {
     return area.position ?? [0, 0];
 }
-function Vegetation({ grass, field }) {
+function Vegetation({ grass, field, groundColor, }) {
     const [cx, cz] = areaCenter(grass.area);
     const heightAt = useMemo(() => cx === 0 && cz === 0
         ? field.sampleHeight
@@ -82,7 +83,15 @@ function Vegetation({ grass, field }) {
     const wind = useMemo(() => ({ strength: grass.windStrength }), [grass.windStrength]);
     const colorBase = grass.colors[0];
     const colorTip = grass.colors[grass.colors.length - 1];
-    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, wind: wind, frustumCulled: true }) }));
+    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true }) }));
+}
+/** Terrain color under a grass patch center — so blade roots blend into the ground they stand on. */
+function vegetationGroundColor(terrain, field, grass) {
+    const sampler = terrainGroundColorSampler(terrain, field);
+    if (sampler === undefined)
+        return undefined;
+    const [cx, cz] = areaCenter(grass.area);
+    return sampler(cx, cz);
 }
 function weatherVolume(area) {
     return [area.w, area.h ?? 60, area.d];
@@ -145,5 +154,5 @@ export function EnvironmentScene({ feature }) {
     const pads = feature.pads ?? [];
     const islands = feature.islands ?? [];
     const roads = feature.roads ?? [];
-    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field }, `road-${index}`))), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
+    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field }, `road-${index}`))), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field, groundColor: vegetationGroundColor(feature.terrain, field, grass) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
 }

package/dist/environment/terrainGroundColor.d.ts

@@ -0,0 +1,9 @@
+import type { TerrainEnvironmentDescriptor } from "@jgengine/core/world/features";
+import { type TerrainField } from "@jgengine/core/world/terrain";
+/**
+ * Terrain surface color at a world XZ — the palette low/high lerped by the sampled ground height,
+ * mirroring how `CarvedTerrain` shades its vertices. The seam that lets everything planted on the
+ * ground (grass roots, soil-patch borders) blend into the exact color it stands on.
+ * @internal
+ */
+export declare function terrainGroundColorSampler(terrain: Omit<TerrainEnvironmentDescriptor, "kind"> | undefined, field: TerrainField): ((x: number, z: number) => string) | undefined;

package/dist/environment/terrainGroundColor.js

@@ -0,0 +1,22 @@
+import * as THREE from "three";
+import { resolveTerrainPalette } from "@jgengine/core/world/terrain";
+/**
+ * Terrain surface color at a world XZ — the palette low/high lerped by the sampled ground height,
+ * mirroring how `CarvedTerrain` shades its vertices. The seam that lets everything planted on the
+ * ground (grass roots, soil-patch borders) blend into the exact color it stands on.
+ * @internal
+ */
+export function terrainGroundColorSampler(terrain, field) {
+    if (terrain === undefined)
+        return undefined;
+    const palette = resolveTerrainPalette(terrain);
+    const low = new THREE.Color(palette.low);
+    const high = new THREE.Color(palette.high);
+    const base = terrain.baseHeight ?? 0;
+    const swing = terrain.height * 1.2;
+    const scratch = new THREE.Color();
+    return (x, z) => {
+        const t = swing <= 0 ? 0.5 : THREE.MathUtils.clamp((field.sampleHeight(x, z) - (base - swing)) / (swing * 2), 0, 1);
+        return `#${scratch.copy(low).lerp(high, t).getHexString()}`;
+    };
+}

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/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/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

@@ -36,8 +36,14 @@ function syncSize(built, width, height, pixelRatio) {
  * (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);
@@ -52,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({
@@ -69,7 +76,7 @@ export function PostProcessing({ config }) {
             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 (config.dof !== undefined && config.dof !== false) {
+        if (heavyPasses && config.dof !== undefined && config.dof !== false) {
             const d = config.dof;
             dof = new BokehPass(scene, camera, {
                 focus: d.focus ?? 18,
@@ -91,7 +98,7 @@ export function PostProcessing({ config }) {
             disposeGraph(graph);
             builtRef.current = null;
         };
-    }, [gl, scene, camera, config]);
+    }, [gl, scene, camera, config, quality]);
     useEffect(() => {
         const prevTone = gl.toneMapping;
         const prevExposure = gl.toneMappingExposure;

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

@@ -5,6 +5,7 @@ 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;
+/** 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/assetBase.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolves a root-absolute asset URL (`/models/…`, `/materials/…`) against the
+ * installed app base. Relative, protocol-relative, absolute-scheme (`https:`,
+ * `blob:`, `data:`), and already-based URLs pass through unchanged. Installed
+ * as the URL modifier on THREE loading managers so every model and texture
+ * load resolves correctly wherever the app is mounted.
+ */
+export declare function resolveAssetBaseUrl(url: string): string;
+/**
+ * Installs the app base URL (pass `import.meta.env.BASE_URL`) so root-absolute
+ * asset paths load from under it. Call once at app startup, before any game
+ * loads. Bases that are not root-absolute (`/`, `./`) reset to the pass-through
+ * default. Also registers {@link resolveAssetBaseUrl} on
+ * `THREE.DefaultLoadingManager`, covering `TextureLoader`, drei's `useTexture`
+ * / `useGLTF`, and every other loader on the default manager.
+ */
+export declare function installAssetBase(base: string): void;

package/dist/render/assetBase.js

@@ -0,0 +1,35 @@
+import * as THREE from "three";
+/**
+ * The app base URL every root-absolute asset path resolves under. `/` (the
+ * default) leaves URLs untouched — standalone game runners serve assets from
+ * the site root. The website serves the runner under `/play/`, where a game's
+ * `/models/…` or `/materials/…` must load from `/play/models/…`.
+ * @internal
+ */
+let assetBase = "/";
+/**
+ * Resolves a root-absolute asset URL (`/models/…`, `/materials/…`) against the
+ * installed app base. Relative, protocol-relative, absolute-scheme (`https:`,
+ * `blob:`, `data:`), and already-based URLs pass through unchanged. Installed
+ * as the URL modifier on THREE loading managers so every model and texture
+ * load resolves correctly wherever the app is mounted.
+ */
+export function resolveAssetBaseUrl(url) {
+    if (assetBase === "/" || !url.startsWith("/") || url.startsWith("//") || url.startsWith(assetBase)) {
+        return url;
+    }
+    return `${assetBase.replace(/\/+$/, "")}${url}`;
+}
+/**
+ * Installs the app base URL (pass `import.meta.env.BASE_URL`) so root-absolute
+ * asset paths load from under it. Call once at app startup, before any game
+ * loads. Bases that are not root-absolute (`/`, `./`) reset to the pass-through
+ * default. Also registers {@link resolveAssetBaseUrl} on
+ * `THREE.DefaultLoadingManager`, covering `TextureLoader`, drei's `useTexture`
+ * / `useGLTF`, and every other loader on the default manager.
+ */
+export function installAssetBase(base) {
+    const normalized = base.endsWith("/") ? base : `${base}/`;
+    assetBase = normalized.startsWith("/") && !normalized.startsWith("//") ? normalized : "/";
+    THREE.DefaultLoadingManager.setURLModifier(resolveAssetBaseUrl);
+}

package/dist/render/modelLoad.js

@@ -2,6 +2,7 @@ import * as THREE from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";
 import { classifyAssetResponse, } from "@jgengine/core/scene/assetDiagnostics";
+import { resolveAssetBaseUrl } from "./assetBase.js";
 /**
  * Dedicated LoadingManager for every GLB load instead of THREE.DefaultLoadingManager.
  * The shared default manager is process-wide; under repeated dev-server navigations its
@@ -10,6 +11,7 @@ import { classifyAssetResponse, } from "@jgengine/core/scene/assetDiagnostics";
  * @internal
  */
 const modelLoadingManager = new THREE.LoadingManager();
+modelLoadingManager.setURLModifier(resolveAssetBaseUrl);
 /** How many leading bytes to read when probing a failed model URL for its signature. @internal */
 const PROBE_BYTE_LIMIT = 64;
 /**
@@ -52,7 +54,8 @@ export class DiagnosticGLTFLoader extends GLTFLoader {
         super.load(url, onLoad, onProgress, (event) => {
             if (onError === undefined)
                 return;
-            void probeModelUrl(url)
+            // Probe the URL the loader actually fetched (base-resolved), not the raw input.
+            void probeModelUrl(this.manager.resolveURL(url))
                 .then((diagnosis) => {
                 if (diagnosis.ok) {
                     // The bytes look fine on re-fetch — surface the original parse error unchanged.

package/dist/render/resolveModel.d.ts

@@ -1,5 +1,6 @@
 import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import type { GameContextModels } from "@jgengine/core/runtime/gameContext";
 export interface ModelResolveContext {
     seam: "entityModels" | "objectModels" | "scatterModels";
     key: string;
@@ -40,6 +41,20 @@ export declare function pickModel(assets: AssetCatalog, pick: ModelPick): ModelC
  * @internal
  */
 export declare function resolveModelPlan(assets: AssetCatalog, plan: Record<string, ModelPick>): Record<string, ModelConfig>;
+/**
+ * The `createGameContext` `models` lookup derived from a playable's render maps: what each entity kind /
+ * object catalog id actually renders as, so colliders auto-fit the rendered mesh. Soft-resolves string
+ * ids (a missing catalog id keeps the default collider instead of throwing — the render path already
+ * reports it), passes inline configs through. `undefined` when the playable maps no models at all.
+ * @internal
+ */
+export declare function contextModels(playable: {
+    game: {
+        assets: AssetCatalog;
+    };
+    entityModels?: Record<string, string | ModelConfig>;
+    objectModels?: Record<string, string | ModelConfig>;
+}): GameContextModels | undefined;
 /**
  * Builds a `(key) => ModelConfig | null` override from a `seam`'s id/config map plus its catalog —
  * `undefined` when either half is missing so the caller can fall back to its own default renderer.