@jgengine/shell 0.11.0 → 0.13.0

package/dist/GamePlayerShell.js

@@ -1,77 +1,60 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Canvas } from "@react-three/fiber";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
 import { createActionStateTracker, toActionStateBindingMap, } from "@jgengine/core/input/actionBindings";
 import { RESERVED_INPUT_ACTIONS } from "./boundActionDispatch.js";
-import { resolveWorldSky } from "./worldSky.js";
-import { pointerAimFor, pointerContextMenu } from "./shellPointer.js";
 import { deriveTouchScheme, withTouchCodes, DEFAULT_TOUCH_STYLE } from "@jgengine/core/input/touchScheme";
-import { contextVerbInput, } from "@jgengine/core/interaction/contextMenu";
 import { normalizePointerToAxis } from "@jgengine/core/input/pointerAxis";
-import { createSelectionSet, isMarquee, screenRect, selectWithinRect, } from "@jgengine/core/scene/selection";
 import { createGameContext } from "@jgengine/core/runtime/gameContext";
-import { DEFAULT_PICKUP_RADIUS } from "@jgengine/core/game/worldItem";
 import { useDisplayProfile } from "@jgengine/react/display";
-import { HudViewportProvider } from "@jgengine/react/hudViewport";
-import { GameViewportProvider } from "@jgengine/react/gameViewport";
 import { RotateDeviceScreen } from "@jgengine/react/rotateDevice";
-import { GameProvider } from "@jgengine/react/provider";
-import { CAMERA_FRUSTUM_DEFAULTS } from "@jgengine/core/game/playableGame";
 import { createSettingsStore } from "@jgengine/core/settings/settingsModel";
 import { applyBindingOverrides, clearBindingOverride, loadBindingOverrides, saveBindingOverride, } from "@jgengine/core/input/bindingOverrides";
-import { playControlsActive } from "@jgengine/core/game/controlGate";
 import { orientationGateActive, orientationHintActive, resolveOrientationRequirement, } from "@jgengine/core/ui/orientation";
-import { sky as resolveSkyDescriptor } from "@jgengine/core/world/features";
-import { resolveGameLook } from "@jgengine/core/render/lookPreset";
-import { AudioListener, EntityAudioEmitters, ObjectAudioEmitters } from "./audio/AudioComponents.js";
+import { armFallbackSeams } from "@jgengine/core/devtools/fallbackSeams";
+import { readUrlFlag, subscribeUrlChange, writeUrlParam } from "@jgengine/core/devtools/urlFlags";
 import { createAudioEngine } from "./audio/audioEngine.js";
 import { attachAudioEventWire } from "./audio/audioWire.js";
-import { PostProcessing } from "./postfx/PostProcessing.js";
-import { EnvironmentLighting } from "./render/EnvironmentLighting.js";
-import { CollisionDebugWorld } from "./devtools/CollisionDebugWorld.js";
-import { DevtoolsOverlay, DevtoolsRendererProbe, withDevtoolsLatency } from "./devtools/DevtoolsOverlay.js";
 import { installAgentBridge } from "./devtools/agentBridge.js";
-import { GameCameraRig, PlayerFovProvider, PlayerFovSlider, resolveRigKind, rtsPanKeysConflict, } from "./camera/index.js";
-import { CullingProvider } from "./visibility/CullingProvider.js";
-import { SkyDaylight, TimeOfDayDaylight } from "./environment.js";
-import { resolveSkyLightOwnership, skyEmitsLights } from "./environment/skyLightingPolicy.js";
-import { EnvironmentScene } from "./environment/EnvironmentScene.js";
-import { PointerProbe } from "./pointer/PointerProbe.js";
-import { MarqueeBox, ContextMenuView } from "./pointer/PointerOverlays.js";
-import { createPointerService } from "./pointer/pointerService.js";
-import { CombatCameraShake, ProjectileTracers, Reticle, WorldEntityBars, WorldFloatText, WorldNameplates, WorldTelegraphs, } from "./world/WorldHud.js";
-import { WorldSpellVfx } from "./world/WorldVfx.js";
-import { RetainedVfx } from "./world/RetainedVfx.js";
-import { GridWorldScene } from "./world/GridWorldScene.js";
-import { WorldItems } from "./world/WorldItems.js";
+import { withDevtoolsLatency } from "./devtools/DevtoolsOverlay.js";
+import { resolveRigKind } from "./camera/index.js";
+import { contextModels } from "./render/resolveModel.js";
 import { OrientationHint } from "./touch/OrientationHint.js";
-import { TouchControlsDock, TouchPlaySurface, touchDockClearance } from "./touch/TouchControlsOverlay.js";
-import { BUILT_IN_SETTING_CATEGORIES } from "@jgengine/core/settings/settingsModel";
-import { SettingsProvider } from "@jgengine/react/settings";
-import { SettingsRuntime } from "./settings/SettingsRuntime.js";
-import { SettingsChrome } from "./settings/SettingsChrome.js";
-import { AudioSettingsBridge, useGraphicsSettings, useTouchStyle } from "./settings/appliedSettings.js";
-import { ConfiguredLighting, BackdropFog } from "./render/SceneLighting.js";
-import { WorldView, RemotePlayers } from "./world/WorldScene.js";
-import { FrameDriver } from "./drivers/FrameDriver.js";
-import { HudOnlyDriver } from "./drivers/HudOnlyDriver.js";
-import { DiagnosticOverlay, GameUiErrorBoundary, logRuntimeError, } from "./diagnostics/RuntimeDiagnostics.js";
-import { GamePhaseStamp } from "./GamePhaseStamp.js";
+import { useTouchStyle, useGraphicsSettings } from "./settings/appliedSettings.js";
+import { logRuntimeError, } from "./diagnostics/RuntimeDiagnostics.js";
 import { EMPTY_RESERVED } from "./shellConstants.js";
 import { useShellMultiplayerSync } from "./useShellMultiplayerSync.js";
+import { ShellHudPresentation } from "./ShellHudPresentation.js";
+import { Shell3dPresentation } from "./Shell3dPresentation.js";
 const DEV_USER_ID = "dev-player";
-const PRIMARY_CLICK_MOVE_THRESHOLD_PX = 6;
-const DEFAULT_BACKGROUND_COLOR = "#14161b";
+/** The query param that mirrors the devtools overlay into the URL — present = open. */
+const DEBUG_PARAM = "debug";
 export { applyMotionImpulses } from "@jgengine/core/runtime/motionIntents";
 export { nearbyObstacles } from "@jgengine/core/movement/movementModel";
 export { resolvePhysicsTuning } from "@jgengine/core/movement/playerMovement";
 export { hasEnvironmentTerrain } from "@jgengine/core/world/terrain";
+/**
+ * The shell body `GameHost` renders after resolving multiplayer. Hosts that resolve their own
+ * sessions (the dev runner) render it directly; games mount through `GameHost`.
+ * @internal
+ */
 export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null, poster = false, onContextReady, }) {
     const multiplayer = useMemo(() => (rawMultiplayer === null ? null : withDevtoolsLatency(rawMultiplayer)), [rawMultiplayer]);
     const devtoolsEnabled = playable.devtools !== false && !poster;
-    const [devtoolsOpen, setDevtoolsOpen] = useState(false);
+    armFallbackSeams(devtoolsEnabled);
+    // `?debug` mirrors the devtools overlay into the URL: open with a link, strip the param to close.
+    const [devtoolsOpen, setDevtoolsOpen] = useState(() => devtoolsEnabled && readUrlFlag(DEBUG_PARAM));
     const devtoolsOpenRef = useRef(false);
     devtoolsOpenRef.current = devtoolsOpen;
+    useEffect(() => {
+        if (!devtoolsEnabled)
+            return;
+        writeUrlParam(DEBUG_PARAM, devtoolsOpen ? "1" : null);
+    }, [devtoolsEnabled, devtoolsOpen]);
+    useEffect(() => {
+        if (!devtoolsEnabled)
+            return;
+        return subscribeUrlChange(() => setDevtoolsOpen(readUrlFlag(DEBUG_PARAM)));
+    }, [devtoolsEnabled]);
     useEffect(() => installAgentBridge({
         playable,
         devtoolsEnabled,
@@ -89,15 +72,8 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     const serverIdRef = useRef(null);
     const cameraDraggingRef = useRef(false);
     const primaryClickRef = useRef(false);
-    const pointerDownRef = useRef(null);
     const pointerAxisRef = useRef(null);
-    const marqueeStartRef = useRef(null);
     const f2HeldRef = useRef(false);
-    const pointerService = useMemo(() => createPointerService(), []);
-    const selection = useMemo(() => createSelectionSet(), [playable]);
-    const [marquee, setMarquee] = useState(null);
-    const [selectedIds, setSelectedIds] = useState(() => new Set());
-    const [contextMenu, setContextMenu] = useState(null);
     const settingsStore = useMemo(() => createSettingsStore(), []);
     const [bindingOverrides, setBindingOverrides] = useState(() => loadBindingOverrides(playable.game.name));
     useEffect(() => {
@@ -179,10 +155,12 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     useEffect(() => {
         setDiagnostics([]);
         try {
+            const models = contextModels(playable);
             const context = createGameContext({
                 definition: playable.game,
                 content: playable.content,
                 player: { userId, isNew: true },
+                ...(models === undefined ? {} : { models }),
             });
             playable.loop.onInit(context);
             playable.loop.onNewPlayer(context);
@@ -204,315 +182,41 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     useSyncExternalStore(ctx?.subscribe ?? (() => () => undefined), ctx?.version ?? (() => 0), ctx?.version ?? (() => 0));
     if (ctx === null)
         return _jsx("div", { className: "h-full w-full bg-neutral-950" });
-    const GameUI = playable.GameUI;
-    const WorldOverlay = playable.WorldOverlay;
-    const controlledEntityId = ctx.player.possession.active(userId);
     const cameraConfig = playable.camera?.followEntityId !== undefined
         ? playable.camera
-        : { ...playable.camera, followEntityId: controlledEntityId };
+        : { ...playable.camera, followEntityId: ctx.player.possession.active(userId) };
     const rigKind = resolveRigKind(cameraConfig);
+    const shared = {
+        playable,
+        ctx,
+        multiplayer,
+        tracker,
+        pointerAxisRef,
+        gateRef,
+        wrapperRef,
+        f2HeldRef,
+        yawRef,
+        pitchRef,
+        touchScheme,
+        touchSink,
+        orientationGate,
+        orientationGateEl,
+        coarsePointer,
+        diagnostics,
+        devtoolsEnabled,
+        devtoolsOpen,
+        setDevtoolsOpen,
+        reportRuntimeError,
+        trackPointerAxis,
+        deactivatePointerAxis,
+    };
     if (rigKind === "none" || playable.presentation === "hud") {
-        const GameUI = playable.GameUI;
-        return (_jsx("div", { ref: wrapperRef, tabIndex: 0, className: "relative h-full w-full bg-neutral-950 outline-none", onKeyDown: (event) => {
-                if (event.code === "F2") {
-                    event.preventDefault();
-                    f2HeldRef.current = true;
-                    return;
-                }
-                if (f2HeldRef.current) {
-                    if (event.code === "KeyD" && devtoolsEnabled) {
-                        event.preventDefault();
-                        setDevtoolsOpen((current) => !current);
-                    }
-                    return;
-                }
-                if (event.code === "Tab" || event.code === "Space")
-                    event.preventDefault();
-                if (playControlsActive(ctx))
-                    tracker.handleDown(event.code);
-            }, onKeyUp: (event) => {
-                if (event.code === "F2") {
-                    f2HeldRef.current = false;
-                    return;
-                }
-                if (playControlsActive(ctx))
-                    tracker.handleUp(event.code);
-            }, onBlur: () => {
-                f2HeldRef.current = false;
-                tracker.reset();
-            }, onPointerDown: () => audioEngine.resume(), onPointerMove: trackPointerAxis, onPointerLeave: deactivatePointerAxis, onPointerCancel: deactivatePointerAxis, children: _jsxs(GameViewportProvider, { platforms: playable.platforms, children: [_jsx(HudOnlyDriver, { ctx: ctx, playable: playable, tracker: tracker, pointerAxisRef: pointerAxisRef, gateRef: gateRef, onRuntimeError: reportRuntimeError }), !orientationGate && coarsePointer && touchScheme !== null && touchScheme.gestures !== null && playControlsActive(ctx) ? (_jsx(TouchPlaySurface, { scheme: touchScheme, sink: touchSink, yawRef: yawRef, pitchRef: pitchRef, maxPitch: 0, onPrimaryTap: () => undefined })) : null, _jsx(GameUiErrorBoundary, { onRuntimeError: reportRuntimeError, children: _jsxs(GameProvider, { context: ctx, children: [_jsx(GamePhaseStamp, {}), _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, userScale: graphics.uiScale, children: orientationGate ? null : _jsx(GameUI, {}) })] }) }), orientationGateEl, devtoolsEnabled ? (_jsx(DevtoolsOverlay, { open: devtoolsOpen, ctx: ctx, playable: playable, multiplayer: multiplayer })) : null, _jsx(DiagnosticOverlay, { diagnostics: diagnostics, gameName: playable.game.name })] }) }));
+        return (_jsx(ShellHudPresentation, { ...shared, uiScale: graphics.uiScale, onPointerResumeAudio: () => audioEngine.resume() }));
     }
-    const firstPerson = rigKind === "first";
-    const showReticle = (firstPerson && playable.camera?.firstPerson?.reticle !== false) || rigKind === "shoulder";
-    const rtsPanKeysEnabled = !rtsPanKeysConflict(playable.game.input);
-    const worldBars = playable.worldHealthBars;
-    const barsStatId = worldBars === undefined || worldBars === false
-        ? null
-        : worldBars === true
-            ? "health"
-            : worldBars.statId ?? "health";
-    const barsRoles = worldBars === undefined || worldBars === true || worldBars === false ? undefined : worldBars.roles;
-    const barsMaxDistance = worldBars === undefined || worldBars === true || worldBars === false
-        ? undefined
-        : worldBars.maxDistance;
-    const nameplates = playable.nameplates;
-    const nameplatesStatId = nameplates === undefined || nameplates === false
-        ? null
-        : nameplates === true
-            ? "health"
-            : nameplates.statId ?? "health";
-    const nameplatesRoles = nameplates === undefined || nameplates === true || nameplates === false ? undefined : nameplates.roles;
-    const nameplatesMaxDistance = nameplates === undefined || nameplates === true || nameplates === false ? undefined : nameplates.maxDistance;
-    const resolveEntityRole = (entity) => playable.content.entityById?.(entity.name)?.role;
-    const pointer = playable.pointer;
-    const pointerUsesLeft = pointer !== undefined && (pointer.select === true || pointer.moveCommand !== undefined);
-    const selectFilter = pointer?.selectFilter;
-    const worldSky = resolveWorldSky(playable.game.world);
-    const world = playable.game.world;
-    const biomeBands = world?.kind === "environment" ? world.terrain?.biomeBands : undefined;
-    const AutoEnvironment = playable.environment ??
-        (world?.kind === "environment"
-            ? () => _jsx(EnvironmentScene, { feature: world })
-            : world?.kind === "biomes" || world?.kind === "voxel" || world?.kind === "plots" || world?.kind === "tilemap"
-                ? () => _jsx(GridWorldScene, { feature: world })
-                : undefined);
-    const resolvedLook = resolveGameLook({
-        look: playable.look,
-        lighting: playable.lighting,
-        backdrop: playable.backdrop,
-        postProcessing: playable.postProcessing,
-        hasWorldSky: worldSky !== undefined,
-    });
-    const cinematicLook = (playable.look ?? "cinematic") !== "flat";
-    const backdrop = resolvedLook.backdrop;
-    const backdropSky = backdrop?.sky !== undefined ? resolveSkyDescriptor(backdrop.sky) : undefined;
-    const effectiveSky = backdropSky ?? worldSky;
-    const backgroundColor = backdrop?.background ?? (effectiveSky === undefined ? DEFAULT_BACKGROUND_COLOR : undefined);
-    const lighting = resolvedLook.lighting;
-    const orthographic = playable.camera?.projection === "orthographic";
-    const localXY = (event) => {
-        const rect = wrapperRef.current?.getBoundingClientRect();
-        return rect === undefined
-            ? { x: event.clientX, y: event.clientY }
-            : { x: event.clientX - rect.left, y: event.clientY - rect.top };
-    };
-    const commitSelection = (ids) => {
-        selection.replace(ids);
-        setSelectedIds(new Set(ids));
-    };
-    const finishMarquee = (rect) => {
-        const candidates = [];
-        for (const entity of ctx.scene.entity.list()) {
-            if (selectFilter !== undefined && !selectFilter(entity.id))
-                continue;
-            const screen = pointerService.screenOf(entity.position);
-            if (screen !== null)
-                candidates.push({ id: entity.id, x: screen.x, y: screen.y });
-        }
-        commitSelection(selectWithinRect(candidates, rect));
-    };
-    /** DOM UI (menus, HUD buttons) sits in the same wrapper as the canvas — only canvas-targeted clicks are world input. */
-    const isWorldPointerTarget = (event) => event.target instanceof HTMLCanvasElement;
-    const handlePointerDown = (event) => {
-        if (isWorldPointerTarget(event))
-            wrapperRef.current?.focus();
-        trackPointerAxis(event);
-        audioEngine.resume();
-        if (contextMenu !== null)
-            setContextMenu(null);
-        if (event.button === 0 && isWorldPointerTarget(event)) {
-            const point = localXY(event);
-            pointerDownRef.current = point;
-            if (pointer?.select === true)
-                marqueeStartRef.current = point;
-        }
-    };
-    const handlePointerMove = (event) => {
-        trackPointerAxis(event);
-        if (pointer?.select !== true)
-            return;
-        const start = marqueeStartRef.current;
-        if (start === null || (event.buttons & 1) === 0)
-            return;
-        const point = localXY(event);
-        setMarquee(screenRect(start.x, start.y, point.x, point.y));
-    };
-    const handlePointerUp = (event) => {
-        if (event.button !== 0 || pointerDownRef.current === null)
-            return;
-        const start = pointerDownRef.current;
-        pointerDownRef.current = null;
-        marqueeStartRef.current = null;
-        const end = localXY(event);
-        const rect = screenRect(start.x, start.y, end.x, end.y);
-        const wasMarquee = marquee !== null && isMarquee(rect, PRIMARY_CLICK_MOVE_THRESHOLD_PX);
-        setMarquee(null);
-        if (pointer?.select === true && wasMarquee) {
-            finishMarquee(rect);
-            return;
-        }
-        if (cameraDraggingRef.current)
-            return;
-        if (pointer?.grabWorldItems === true) {
-            const hit = pointerService.worldHit();
-            const itemInstanceId = hit?.entity ?? null;
-            const record = itemInstanceId === null ? null : ctx.scene.worldItem.get(itemInstanceId);
-            if (record !== null && itemInstanceId !== null) {
-                const itemEntity = ctx.scene.entity.get(itemInstanceId);
-                const localPlayer = ctx.scene.entity.get(ctx.player.userId);
-                const pickupRadius = playable.worldItem?.pickupRadius ?? DEFAULT_PICKUP_RADIUS;
-                const withinRadius = itemEntity !== null &&
-                    localPlayer !== null &&
-                    Math.hypot(localPlayer.position[0] - itemEntity.position[0], localPlayer.position[1] - itemEntity.position[1], localPlayer.position[2] - itemEntity.position[2]) <= pickupRadius;
-                if (withinRadius) {
-                    ctx.scene.worldItem.pickup(itemInstanceId, ctx.player.userId);
-                    return;
-                }
-            }
-        }
-        if (pointer?.select === true) {
-            const hit = pointerService.worldHit();
-            if (hit !== null && hit.entity !== null && (selectFilter === undefined || selectFilter(hit.entity))) {
-                commitSelection([hit.entity]);
-            }
-            else {
-                commitSelection([]);
-            }
-            return;
-        }
-        if (pointer?.moveCommand !== undefined) {
-            const hit = pointerService.worldHit();
-            if (hit !== null && ctx.game.commands.has(pointer.moveCommand)) {
-                ctx.game.commands.run(pointer.moveCommand, { point: hit.point, entity: hit.entity, object: hit.object });
-            }
-            return;
-        }
-        const moved = (end.x - start.x) ** 2 + (end.y - start.y) ** 2;
-        if (moved <= PRIMARY_CLICK_MOVE_THRESHOLD_PX * PRIMARY_CLICK_MOVE_THRESHOLD_PX)
-            primaryClickRef.current = true;
-    };
-    const handleContextMenu = (event) => {
-        if (pointer === undefined)
-            return;
-        if (!isWorldPointerTarget(event))
-            return;
-        event.preventDefault();
-        const hit = pointerService.worldHit();
-        if (hit === null)
-            return;
-        if (pointer.contextMenu === true && (hit.entity !== null || hit.object !== null)) {
-            const menu = pointerContextMenu(ctx, playable, hit);
-            if (menu !== null) {
-                const point = localXY(event);
-                setContextMenu({ menu, x: point.x, y: point.y });
+    return (_jsx(Shell3dPresentation, { ...shared, primaryClickRef: primaryClickRef, cameraDraggingRef: cameraDraggingRef, serverIdRef: serverIdRef, remotePlayers: remotePlayers, touchStyle: touchStyle, compact: compact, graphics: graphics, settingsStore: settingsStore, bindingOverrides: bindingOverrides, rebindAction: rebindAction, resetActionBinding: resetActionBinding, audioEngine: audioEngine, poster: poster, posterFrozen: posterFrozen, onPosterSettled: () => {
+            if (posterSettledRef.current)
                 return;
-            }
-        }
-        if (pointer.select === true && pointer.orderCommand !== undefined && selection.size() > 0) {
-            if (ctx.game.commands.has(pointer.orderCommand)) {
-                ctx.game.commands.run(pointer.orderCommand, { selection: selection.list(), point: hit.point });
-            }
-            return;
-        }
-        if (pointer.secondaryCommand !== undefined && ctx.game.commands.has(pointer.secondaryCommand)) {
-            const aim = (pointer.aim === true ? pointerAimFor(ctx, pointerService) : undefined) ?? {
-                yaw: yawRef.current,
-                pitch: pitchRef.current,
-            };
-            ctx.game.commands.run(pointer.secondaryCommand, { point: hit.point, entity: hit.entity, object: hit.object, aim });
-        }
-    };
-    const handleVerbPick = (verb) => {
-        const state = contextMenu;
-        setContextMenu(null);
-        if (state !== null && ctx.game.commands.has(verb.command)) {
-            ctx.game.commands.run(verb.command, contextVerbInput(state.menu, verb));
-        }
-    };
-    const controlsActive = playControlsActive(ctx);
-    const settingsDisabled = playable.settings === false;
-    const settingsConfig = playable.settings === false || playable.settings === undefined ? {} : playable.settings;
-    const settingsSurface = settingsDisabled ? false : settingsConfig.surface ?? false;
-    const settingsVariant = settingsConfig.variant ?? "panel";
-    const hideCategories = settingsDisabled ? BUILT_IN_SETTING_CATEGORIES : settingsConfig.hide ?? [];
-    const fovControlEnabled = !orthographic && playable.camera?.playerFov?.control !== false;
-    const settingsHostsFov = !settingsDisabled && !hideCategories.includes("gameplay") && fovControlEnabled;
-    const settingsActions = settingsDisabled
-        ? []
-        : (settingsConfig.actions ?? []).map((action) => ({
-            id: action.id,
-            label: action.label,
-            kind: action.kind ?? "default",
-            description: action.description,
-            run: () => action.run(ctx),
-        }));
-    const touchScale = compact ? 0.88 : 1;
-    const dockMounted = !poster &&
-        !orientationGate &&
-        coarsePointer &&
-        controlsActive &&
-        touchScheme !== null &&
-        (touchScheme.joystick !== null || touchScheme.buttons.length > 0);
-    return (_jsx(SettingsProvider, { store: settingsStore, children: _jsxs(PlayerFovProvider, { config: playable.camera, orthographic: orthographic, children: [_jsx(AudioSettingsBridge, { store: settingsStore, engine: audioEngine, buses: playable.audio?.buses }), _jsx(SettingsRuntime, { variant: settingsVariant, surface: settingsSurface, actions: settingsActions, input: playable.game.input ?? {}, buses: playable.audio?.buses, extra: settingsConfig.extra ?? [], categories: settingsConfig.categories ?? [], hide: hideCategories, fovEnabled: fovControlEnabled, hideBindings: settingsConfig.hideBindings ?? [], touchStyle: coarsePointer &&
-                        touchScheme !== null &&
-                        (touchScheme.joystick !== null || touchScheme.buttons.length > 0), overrides: bindingOverrides, rebind: rebindAction, resetBinding: resetActionBinding, children: _jsx("div", { ref: wrapperRef, tabIndex: 0, ...(poster && posterFrozen ? { "data-poster-ready": "" } : {}), className: "relative h-full w-full bg-neutral-950 outline-none", style: {
-                            "--jg-hud-dock-clearance": `${dockMounted ? touchDockClearance(touchScheme, touchScale) : 0}px`,
-                        }, onKeyDown: (event) => {
-                            if (event.code === "F2") {
-                                event.preventDefault();
-                                f2HeldRef.current = true;
-                                return;
-                            }
-                            if (f2HeldRef.current) {
-                                if (event.code === "KeyD" && devtoolsEnabled) {
-                                    event.preventDefault();
-                                    document.exitPointerLock?.();
-                                    setDevtoolsOpen((current) => !current);
-                                }
-                                return;
-                            }
-                            if (event.code === "Tab" || event.code === "Space")
-                                event.preventDefault();
-                            if (playControlsActive(ctx))
-                                tracker.handleDown(event.code);
-                        }, onKeyUp: (event) => {
-                            if (event.code === "F2") {
-                                f2HeldRef.current = false;
-                                return;
-                            }
-                            if (playControlsActive(ctx))
-                                tracker.handleUp(event.code);
-                        }, onBlur: () => {
-                            f2HeldRef.current = false;
-                            tracker.reset();
-                        }, onPointerDown: handlePointerDown, onPointerMove: handlePointerMove, onPointerUp: handlePointerUp, onPointerLeave: deactivatePointerAxis, onPointerCancel: deactivatePointerAxis, onContextMenu: handleContextMenu, onWheel: (event) => {
-                            if (ctx === null || !event.shiftKey)
-                                return;
-                            event.preventDefault();
-                            if (event.deltaY < 0 && ctx.game.commands.has("ui.hotbarScrollNext")) {
-                                ctx.game.commands.run("ui.hotbarScrollNext", {});
-                            }
-                            else if (event.deltaY > 0 && ctx.game.commands.has("ui.hotbarScrollPrev")) {
-                                ctx.game.commands.run("ui.hotbarScrollPrev", {});
-                            }
-                        }, children: _jsxs(GameViewportProvider, { platforms: playable.platforms, children: [_jsxs(Canvas, { frameloop: poster && posterFrozen ? "demand" : "always", orthographic: orthographic, camera: orthographic
-                                        ? {
-                                            zoom: playable.camera?.frustum?.zoom ?? CAMERA_FRUSTUM_DEFAULTS.zoom,
-                                            near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
-                                            far: playable.camera?.frustum?.far ?? CAMERA_FRUSTUM_DEFAULTS.far,
-                                        }
-                                        : {
-                                            fov: playable.camera?.frustum?.fov ?? CAMERA_FRUSTUM_DEFAULTS.fov,
-                                            near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
-                                            far: playable.camera?.frustum?.far ?? CAMERA_FRUSTUM_DEFAULTS.far,
-                                        }, shadows: graphics.shadows, dpr: graphics.dpr, gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: [backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? _jsx(EnvironmentLighting, {}) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsxs(GameProvider, { context: ctx, children: [_jsx(CullingProvider, { config: playable.visibility, children: _jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson }) }), WorldOverlay !== undefined ? _jsx(WorldOverlay, { ctx: ctx }) : null, barsStatId !== null ? (_jsx(WorldEntityBars, { statId: barsStatId, roles: barsRoles, resolveRole: resolveEntityRole, ...(barsMaxDistance === undefined ? {} : { maxDistance: barsMaxDistance }) })) : null, nameplatesStatId !== null ? (_jsx(WorldNameplates, { statId: nameplatesStatId, roles: nameplatesRoles, resolveRole: resolveEntityRole, ...(nameplatesMaxDistance === undefined ? {} : { maxDistance: nameplatesMaxDistance }) })) : null, _jsx(WorldItems, { config: playable.worldItem }), _jsx(WorldTelegraphs, {}), _jsx(WorldSpellVfx, {}), _jsx(RetainedVfx, {}), _jsx(WorldFloatText, {}), _jsx(ProjectileTracers, {}), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(CombatCameraShake, {}), _jsx(AudioListener, { engine: audioEngine }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
-                                                        cameraDraggingRef.current = dragging;
-                                                    } }), _jsx(PointerProbe, { service: pointerService })] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, pointerAxisRef: pointerAxisRef, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: () => {
-                                                if (posterSettledRef.current)
-                                                    return;
-                                                posterSettledRef.current = true;
-                                                setPosterFrozen(true);
-                                            } }), _jsx(DevtoolsRendererProbe, {}), resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing })) : null] }), !poster && !orientationGate && coarsePointer && controlsActive && touchScheme !== null && (touchScheme.gestures !== null || touchScheme.look) ? (_jsx(TouchPlaySurface, { scheme: touchScheme, sink: touchSink, yawRef: yawRef, pitchRef: pitchRef, maxPitch: playable.camera?.firstPerson?.maxPitch ?? 1.45, onPrimaryTap: () => {
-                                        primaryClickRef.current = true;
-                                    } })) : null, _jsx(GameUiErrorBoundary, { onRuntimeError: reportRuntimeError, children: _jsxs(GameProvider, { context: ctx, children: [_jsx(GamePhaseStamp, {}), _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, userScale: graphics.uiScale, children: orientationGate ? null : _jsx(GameUI, {}) })] }) }), !poster && !orientationGate && showReticle ? _jsx(Reticle, {}) : null, dockMounted && touchScheme !== null ? (_jsx(TouchControlsDock, { scheme: touchScheme, sink: touchSink, style: touchStyle, scale: touchScale })) : null, orientationGateEl, marquee !== null ? _jsx(MarqueeBox, { rect: marquee }) : null, contextMenu !== null ? (_jsx(ContextMenuView, { menu: contextMenu.menu, x: contextMenu.x, y: contextMenu.y, onPick: handleVerbPick, onClose: () => setContextMenu(null) })) : null, devtoolsEnabled ? (_jsx(DevtoolsOverlay, { open: devtoolsOpen, ctx: ctx, playable: playable, multiplayer: multiplayer })) : null, poster ? null : _jsx(DiagnosticOverlay, { diagnostics: diagnostics, gameName: playable.game.name }), poster || orthographic || settingsHostsFov ? null : _jsx(PlayerFovSlider, {}), poster ? null : _jsx(SettingsChrome, {})] }) }) })] }) }));
+            posterSettledRef.current = true;
+            setPosterFrozen(true);
+        } }));
 }

package/dist/GameUiPreview.js

@@ -3,6 +3,7 @@ import { useEffect, useState } from "react";
 import { createGameContext } from "@jgengine/core/runtime/gameContext";
 import { GameProvider } from "@jgengine/react/provider";
 import { HudViewportProvider } from "@jgengine/react/hudViewport";
+import { contextModels } from "./render/resolveModel.js";
 const PREVIEW_USER_ID = "ui-preview";
 const TICK_STEP = 1 / 60;
 function runTicks(ctx, playable, seconds) {
@@ -37,10 +38,12 @@ export const defaultUiScenario = (ctx, playable) => {
 export function GameUiPreview({ playable, scenario = defaultUiScenario, }) {
     const [ctx, setCtx] = useState(null);
     useEffect(() => {
+        const models = contextModels(playable);
         const context = createGameContext({
             definition: playable.game,
             content: playable.content,
             player: { userId: PREVIEW_USER_ID, isNew: true },
+            ...(models === undefined ? {} : { models }),
         });
         playable.loop.onInit(context);
         playable.loop.onNewPlayer(context);

package/dist/Shell3dPresentation.d.ts

@@ -0,0 +1,63 @@
+import { type Dispatch, type MutableRefObject, type RefObject, type SetStateAction } from "react";
+import type { PointerAxisState } from "@jgengine/core/input/pointerAxis";
+import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { BindingOverrides } from "@jgengine/core/input/bindingOverrides";
+import type { TouchScheme, TouchStyle } from "@jgengine/core/input/touchScheme";
+import { type GraphicsQuality, type SettingsStore } from "@jgengine/core/settings/settingsModel";
+import type { PresencePoseRow } from "@jgengine/core/runtime/transport";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { AudioEngine } from "./audio/audioEngine.js";
+import type { ShellMultiplayer } from "./multiplayer.js";
+import type { PlayableGame } from "./registry.js";
+import type { RuntimeDiagnostic } from "./diagnostics/RuntimeDiagnostics.js";
+/** 3D play surface: canvas, world overlays, and shared chrome. @internal */
+export declare function Shell3dPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, primaryClickRef, cameraDraggingRef, serverIdRef, remotePlayers, touchScheme, touchSink, touchStyle, orientationGate, orientationGateEl, coarsePointer, compact, graphics, settingsStore, bindingOverrides, rebindAction, resetActionBinding, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, audioEngine, poster, posterFrozen, onPosterSettled, }: {
+    playable: PlayableGame;
+    ctx: GameContext;
+    multiplayer: ShellMultiplayer | null;
+    tracker: ActionStateTracker<string>;
+    pointerAxisRef: MutableRefObject<PointerAxisState | null>;
+    gateRef: MutableRefObject<boolean>;
+    wrapperRef: RefObject<HTMLDivElement | null>;
+    f2HeldRef: MutableRefObject<boolean>;
+    yawRef: MutableRefObject<number>;
+    pitchRef: MutableRefObject<number>;
+    primaryClickRef: MutableRefObject<boolean>;
+    cameraDraggingRef: MutableRefObject<boolean>;
+    serverIdRef: MutableRefObject<string | null>;
+    remotePlayers: PresencePoseRow[];
+    touchScheme: TouchScheme | null;
+    touchSink: {
+        onCodeDown: (code: string) => void;
+        onCodeUp: (code: string) => void;
+    };
+    touchStyle: TouchStyle;
+    orientationGate: boolean;
+    orientationGateEl: React.ReactNode;
+    coarsePointer: boolean;
+    compact: boolean;
+    graphics: {
+        shadows: boolean;
+        dpr: number;
+        uiScale: number;
+        quality: GraphicsQuality;
+    };
+    settingsStore: SettingsStore;
+    bindingOverrides: BindingOverrides;
+    rebindAction: (action: string, code: string) => void;
+    resetActionBinding: (action: string) => void;
+    diagnostics: RuntimeDiagnostic[];
+    devtoolsEnabled: boolean;
+    devtoolsOpen: boolean;
+    setDevtoolsOpen: Dispatch<SetStateAction<boolean>>;
+    reportRuntimeError: (error: unknown, phase: string, componentStack?: string) => void;
+    trackPointerAxis: (event: {
+        clientX: number;
+        clientY: number;
+    }) => void;
+    deactivatePointerAxis: () => void;
+    audioEngine: AudioEngine;
+    poster: boolean;
+    posterFrozen: boolean;
+    onPosterSettled: () => void;
+}): import("react").JSX.Element;