@jgengine/shell 0.1.0

package/dist/GamePlayerShell.d.ts

@@ -0,0 +1,6 @@
+import type { ShellMultiplayer } from "./multiplayer.js";
+import type { PlayableGame } from "./registry.js";
+export declare function GamePlayerShell({ playable, multiplayer, }: {
+    playable: PlayableGame;
+    multiplayer?: ShellMultiplayer | null;
+}): import("react").JSX.Element;

package/dist/GamePlayerShell.js

@@ -0,0 +1,383 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Canvas, useFrame, useLoader } from "@react-three/fiber";
+import { Component, useEffect, useMemo, useRef, useState } from "react";
+import * as THREE from "three";
+import { createActionStateTracker, toActionStateBindingMap, } from "@jgengine/core/input/actionBindings";
+import { advancePlayerMotion, createEmptyMovementKeys, createPlayerMotionState, resolveMovementIntent, } from "@jgengine/core/movement/movementModel";
+import { createGameContext } from "@jgengine/core/runtime/gameContext";
+import { useGameContext } from "@jgengine/react/provider";
+import { useSceneEntities, useSceneObjects, usePlayer, useTarget } from "@jgengine/react/hooks";
+import { GameProvider } from "@jgengine/react/provider";
+import { GAME_SIM_FRAME_PRIORITY, GameOrbitCamera } from "./camera/index.js";
+const DEV_USER_ID = "dev-player";
+const TURN_SPEED = 2.4;
+const PRIMARY_CLICK_MOVE_THRESHOLD_PX = 6;
+const GROUND_SIZE = 160;
+const GROUND_SEGMENTS = 80;
+function errorToDiagnostic(error, phase) {
+    if (error instanceof Error) {
+        return { phase, message: error.message, stack: error.stack };
+    }
+    return { phase, message: typeof error === "string" ? error : JSON.stringify(error) };
+}
+function logRuntimeError(error, phase) {
+    const diagnostic = errorToDiagnostic(error, phase);
+    console.error(`[jgengine:${phase}] ${diagnostic.message}`, error);
+    return diagnostic;
+}
+function findHotbarSlotActions(input) {
+    return Object.keys(input ?? {}).flatMap((action) => {
+        const match = /^(?:hotbar)?slot(\d+)$/i.exec(action);
+        return match === null ? [] : [{ action, slot: Number(match[1]) - 1 }];
+    });
+}
+function hotbarIdFor(playable) {
+    const declarations = Object.entries(playable.game.inventories ?? {});
+    const hud = declarations.find(([, declaration]) => declaration.hud === "hotbar");
+    return (hud ?? declarations[0])?.[0] ?? null;
+}
+function executeHotbarSlot(ctx, hotbarId, slot, yaw) {
+    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: ctx.player.userId,
+        itemId: stack.itemId,
+        inventoryId: hotbarId,
+        aim: { yaw, pitch: 0 },
+    });
+    return result.error === undefined ? { ok: true } : { ok: false, error: result.error };
+}
+function colorFromId(id) {
+    let hash = 0;
+    for (let index = 0; index < id.length; index += 1)
+        hash = (hash * 31 + id.charCodeAt(index)) >>> 0;
+    return `hsl(${hash % 360}, 65%, 55%)`;
+}
+function EntitySprite({ sprite }) {
+    const texture = useLoader(THREE.TextureLoader, sprite.url);
+    useEffect(() => {
+        texture.colorSpace = THREE.SRGBColorSpace;
+        texture.anisotropy = 4;
+        texture.needsUpdate = true;
+    }, [texture]);
+    return (_jsx("sprite", { "position-y": sprite.y, scale: [sprite.width, sprite.height, 1], children: _jsx("spriteMaterial", { map: texture, transparent: true, alphaTest: 0.08, depthWrite: false }) }));
+}
+function EntityMarker({ entity, sprite, isLocal, targeted, onSelect, }) {
+    const color = isLocal ? "#4ade80" : entity.role === "npc" ? colorFromId(entity.name) : "#9ca3af";
+    return (_jsxs("group", { position: [entity.position[0], entity.position[1], entity.position[2]], "rotation-y": entity.rotationY, onPointerDown: (event) => {
+            event.stopPropagation();
+            if (!isLocal)
+                onSelect(entity);
+        }, children: [sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : entity.role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, children: [_jsx("sphereGeometry", { args: [0.45, 16, 16] }), _jsx("meshStandardMaterial", { color: color })] })) : (_jsxs(_Fragment, { children: [_jsxs("mesh", { "position-y": 0.95, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx("meshStandardMaterial", { color: color })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] })), targeted ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.6, 0.75, 28] }), _jsx("meshBasicMaterial", { color: "#f87171" })] })) : null] }));
+}
+function GroundPlane() {
+    const geometry = useMemo(() => {
+        const next = new THREE.PlaneGeometry(GROUND_SIZE, GROUND_SIZE, GROUND_SEGMENTS, GROUND_SEGMENTS);
+        const positions = next.attributes.position;
+        for (let index = 0; index < positions.count; index += 1) {
+            const x = positions.getX(index);
+            const y = positions.getY(index);
+            const height = Math.sin(x * 0.16) * 0.12 +
+                Math.cos(y * 0.11) * 0.1 +
+                Math.sin((x + y) * 0.05) * 0.16;
+            positions.setZ(index, height);
+        }
+        next.computeVertexNormals();
+        return next;
+    }, []);
+    return (_jsx("mesh", { "rotation-x": -Math.PI / 2, geometry: geometry, children: _jsx("meshStandardMaterial", { color: "#283729", roughness: 0.9, metalness: 0 }) }));
+}
+function RockField() {
+    const rocks = useMemo(() => Array.from({ length: 18 }, (_, index) => {
+        const angle = index * 2.399963229728653;
+        const radius = 10 + ((index * 17) % 58);
+        return {
+            id: `rock-${index}`,
+            x: Math.cos(angle) * radius,
+            z: Math.sin(angle) * radius,
+            scale: 0.45 + ((index * 13) % 11) / 10,
+            rotation: angle,
+        };
+    }), []);
+    return (_jsx(_Fragment, { children: rocks.map((rock) => (_jsxs("mesh", { position: [rock.x, 0.25 * rock.scale, rock.z], rotation: [0.1, rock.rotation, -0.08], scale: [rock.scale * 1.4, rock.scale * 0.7, rock.scale], children: [_jsx("dodecahedronGeometry", { args: [0.8, 0] }), _jsx("meshStandardMaterial", { color: "#6b6f63", roughness: 1 })] }, rock.id))) }));
+}
+function WorldView({ entitySprites }) {
+    const ctx = useGameContext();
+    const entities = useSceneEntities();
+    const objects = useSceneObjects();
+    const player = usePlayer();
+    const targetId = useTarget(player.userId);
+    const handleSelect = (entity) => {
+        const relation = ctx.scene.entity.canReceive(entity.id, "damage") === null ? "hostile" : "friendly";
+        ctx.scene.entity.setTarget(player.userId, relation === "hostile" || entity.role === "npc" ? entity.id : null);
+    };
+    return (_jsxs(_Fragment, { children: [_jsx(GroundPlane, {}), _jsx("gridHelper", { args: [160, 80, "#3a3f4a", "#2b2f38"], "position-y": 0.01 }), _jsx(RockField, {}), entities.map((entity) => (_jsx(EntityMarker, { entity: entity, sprite: entitySprites?.[entity.name], isLocal: entity.id === player.userId, targeted: entity.id === targetId, onSelect: handleSelect }, entity.id))), objects.map((object) => (_jsxs("mesh", { position: [object.position[0], object.position[1] + 0.5, object.position[2]], "rotation-y": object.rotationY, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx("meshStandardMaterial", { color: colorFromId(object.catalogId) })] }, object.instanceId)))] }));
+}
+function RemotePlayers({ rows }) {
+    return (_jsx(_Fragment, { children: rows.map((row) => (_jsxs("group", { position: [row.position.x, row.position.y, row.position.z], "rotation-y": row.rotationY, children: [_jsxs("mesh", { "position-y": 0.95, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx("meshStandardMaterial", { color: colorFromId(row.userId) })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] }, row.userId))) }));
+}
+function FrameDriver({ ctx, playable, tracker, yawRef, primaryClickRef, onRuntimeError, multiplayer, serverIdRef, }) {
+    const motionRef = useRef(createPlayerMotionState());
+    const hasReportedTickError = useRef(false);
+    const slotActions = useMemo(() => findHotbarSlotActions(playable.game.input), [playable]);
+    const hotbarId = useMemo(() => hotbarIdFor(playable), [playable]);
+    useFrame((_state, rawDt) => {
+        try {
+            const dt = Math.min(rawDt, 0.05);
+            if (tracker.isDown("turnLeft"))
+                yawRef.current += TURN_SPEED * dt;
+            if (tracker.isDown("turnRight"))
+                yawRef.current -= TURN_SPEED * dt;
+            const playerId = ctx.player.userId;
+            const player = ctx.scene.entity.get(playerId);
+            const forwardX = Math.sin(yawRef.current);
+            const forwardZ = Math.cos(yawRef.current);
+            if (player !== null) {
+                const keys = createEmptyMovementKeys();
+                keys.w = tracker.isDown("moveForward");
+                keys.s = tracker.isDown("moveBack");
+                keys.a = tracker.isDown("moveLeft");
+                keys.d = tracker.isDown("moveRight");
+                keys.shift = tracker.isDown("sprint");
+                keys.space = tracker.isDown("jump");
+                const intent = resolveMovementIntent(keys, true);
+                const motion = motionRef.current;
+                const step = advancePlayerMotion(motion, intent, forwardX, forwardZ, player.movement.walkSpeed ?? 2, rawDt);
+                ctx.scene.entity.setPose(playerId, {
+                    position: [player.position[0] + step.stepX, motion.jumpOffset, player.position[2] + step.stepZ],
+                    rotationY: intent.moving
+                        ? Math.atan2(motion.horizontalVelocityX, motion.horizontalVelocityZ)
+                        : player.rotationY,
+                });
+            }
+            playable.loop.onTick(ctx, dt);
+            if (tracker.wasPressed("tabTarget")) {
+                if (ctx.game.commands.has("target.cycle"))
+                    ctx.game.commands.run("target.cycle", {});
+                else
+                    ctx.scene.entity.cycleTarget(playerId, { filter: "hostile" });
+            }
+            if (tracker.wasPressed("clearTarget")) {
+                if (ctx.game.commands.has("target.clear"))
+                    ctx.game.commands.run("target.clear", {});
+                else
+                    ctx.scene.entity.setTarget(playerId, null);
+            }
+            const uiActions = {
+                openBackpack: "ui.openBackpack",
+                openCharacter: "ui.openCharacter",
+                openAbilities: "ui.openAbilities",
+            };
+            for (const [action, command] of Object.entries(uiActions)) {
+                if (tracker.wasPressed(action) && ctx.game.commands.has(command)) {
+                    ctx.game.commands.run(command, {});
+                }
+            }
+            if (hotbarId !== null) {
+                for (const { action, slot } of slotActions) {
+                    if (!tracker.wasPressed(action))
+                        continue;
+                    const result = executeHotbarSlot(ctx, hotbarId, slot, yawRef.current);
+                    if (!result.ok)
+                        console.warn(`[jgengine:item-use] ${result.error}`);
+                }
+                const usePrimary = tracker.wasPressed("useAbility") || (primaryClickRef.current && hotbarId !== null);
+                if (usePrimary) {
+                    primaryClickRef.current = false;
+                    const slots = ctx.player.inventory.state(hotbarId).slots;
+                    const preferred = playable.hotbarSelection?.() ?? -1;
+                    const slot = preferred >= 0 && slots[preferred] !== null && slots[preferred] !== undefined
+                        ? preferred
+                        : slots.findIndex((stack) => stack !== null);
+                    if (slot >= 0) {
+                        const result = executeHotbarSlot(ctx, hotbarId, slot, yawRef.current);
+                        if (!result.ok)
+                            console.warn(`[jgengine:item-use] ${result.error}`);
+                    }
+                }
+            }
+            tracker.endFrame();
+            const serverId = serverIdRef.current;
+            if (multiplayer !== null && serverId !== null) {
+                const focus = ctx.scene.entity.get(playerId);
+                if (focus !== null) {
+                    multiplayer.backend.presenceSync.syncPose(serverId, {
+                        x: focus.position[0],
+                        y: focus.position[1],
+                        z: focus.position[2],
+                        rotationY: focus.rotationY,
+                        rotationPitch: 0,
+                    });
+                }
+            }
+        }
+        catch (error) {
+            if (!hasReportedTickError.current) {
+                hasReportedTickError.current = true;
+                onRuntimeError(error, "tick");
+            }
+        }
+    }, GAME_SIM_FRAME_PRIORITY);
+    return null;
+}
+class GameUiErrorBoundary extends Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error) {
+        this.props.onRuntimeError(error, "ui-render");
+    }
+    render() {
+        if (this.state.failed)
+            return null;
+        return this.props.children;
+    }
+}
+function DiagnosticOverlay({ diagnostics }) {
+    if (diagnostics.length === 0)
+        return null;
+    const latest = diagnostics[diagnostics.length - 1];
+    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] }), 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] }));
+}
+export function GamePlayerShell({ playable, multiplayer = null, }) {
+    const [ctx, setCtx] = useState(null);
+    const [diagnostics, setDiagnostics] = useState([]);
+    const [remotePlayers, setRemotePlayers] = useState([]);
+    const wrapperRef = useRef(null);
+    const yawRef = useRef(0);
+    const serverIdRef = useRef(null);
+    const cameraDraggingRef = useRef(false);
+    const primaryClickRef = useRef(false);
+    const pointerDownRef = useRef(null);
+    const tracker = useMemo(() => createActionStateTracker(toActionStateBindingMap(playable.game.input ?? {})), [playable]);
+    const userId = multiplayer?.userId ?? DEV_USER_ID;
+    const reportRuntimeError = (error, phase) => {
+        const diagnostic = logRuntimeError(error, phase);
+        setDiagnostics((current) => [...current.slice(-4), { ...diagnostic, id: Date.now() + current.length }]);
+    };
+    useEffect(() => {
+        playable.game.scene.clear();
+        setDiagnostics([]);
+        try {
+            const context = createGameContext({
+                definition: playable.game,
+                content: playable.content,
+                player: { userId, isNew: true },
+            });
+            playable.loop.onInit(context);
+            playable.loop.onNewPlayer(context);
+            setCtx(context);
+        }
+        catch (error) {
+            reportRuntimeError(error, "init");
+            setCtx(null);
+        }
+        return () => {
+            playable.game.scene.clear();
+            setCtx(null);
+        };
+    }, [playable, userId]);
+    useEffect(() => {
+        if (ctx === null || multiplayer === null)
+            return;
+        let disposed = false;
+        const cleanups = [];
+        void multiplayer.backend.transport
+            .joinServer({ gameId: multiplayer.gameId })
+            .then((joined) => {
+            if (disposed) {
+                void multiplayer.backend.transport.leaveServer({ serverId: joined.serverId });
+                return;
+            }
+            serverIdRef.current = joined.serverId;
+            cleanups.push(multiplayer.backend.presenceSync.subscribe(joined.serverId, (rows) => {
+                setRemotePlayers(rows.filter((row) => row.userId !== multiplayer.userId));
+            }));
+            const seen = new Set();
+            let injecting = false;
+            for (const action of multiplayer.feedActions) {
+                cleanups.push(ctx.game.feed.subscribe(action, (entry) => {
+                    if (injecting)
+                        return;
+                    void multiplayer.backend
+                        .pushFeedEntry({
+                        serverId: joined.serverId,
+                        action,
+                        entry: { at: entry.at, data: entry.data, from: multiplayer.userId },
+                    })
+                        .catch(() => undefined);
+                }));
+                const remoteUnsub = multiplayer.backend.feeds?.subscribeFeed({ serverId: joined.serverId, action }, (view) => {
+                    for (const raw of view.entries) {
+                        const remote = raw;
+                        if (typeof remote.from !== "string" || remote.from === multiplayer.userId)
+                            continue;
+                        const key = `${action}|${remote.from}|${remote.at ?? 0}`;
+                        if (seen.has(key))
+                            continue;
+                        seen.add(key);
+                        injecting = true;
+                        ctx.game.feed.push(action, remote.data);
+                        injecting = false;
+                    }
+                });
+                if (remoteUnsub !== undefined)
+                    cleanups.push(remoteUnsub);
+            }
+        })
+            .catch(() => undefined);
+        return () => {
+            disposed = true;
+            for (const cleanup of cleanups)
+                cleanup();
+            const serverId = serverIdRef.current;
+            serverIdRef.current = null;
+            setRemotePlayers([]);
+            if (serverId !== null) {
+                void multiplayer.backend.transport.leaveServer({ serverId }).catch(() => undefined);
+            }
+        };
+    }, [ctx, multiplayer]);
+    useEffect(() => {
+        wrapperRef.current?.focus();
+    }, [ctx]);
+    if (ctx === null)
+        return _jsx("div", { className: "h-full w-full bg-neutral-950" });
+    const GameUI = playable.GameUI;
+    const WorldOverlay = playable.WorldOverlay;
+    return (_jsxs("div", { ref: wrapperRef, tabIndex: 0, className: "relative h-full w-full bg-neutral-950 outline-none", onKeyDown: (event) => {
+            if (event.code === "Tab" || event.code === "Space")
+                event.preventDefault();
+            tracker.handleDown(event.code);
+        }, onKeyUp: (event) => tracker.handleUp(event.code), onBlur: () => tracker.reset(), onPointerDown: (event) => {
+            wrapperRef.current?.focus();
+            if (event.button === 0) {
+                pointerDownRef.current = { x: event.clientX, y: event.clientY };
+            }
+        }, onPointerUp: (event) => {
+            if (event.button !== 0 || pointerDownRef.current === null)
+                return;
+            const start = pointerDownRef.current;
+            pointerDownRef.current = null;
+            const dx = event.clientX - start.x;
+            const dy = event.clientY - start.y;
+            const moved = dx * dx + dy * dy;
+            if (!cameraDraggingRef.current && moved <= PRIMARY_CLICK_MOVE_THRESHOLD_PX * PRIMARY_CLICK_MOVE_THRESHOLD_PX) {
+                primaryClickRef.current = true;
+            }
+        }, 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(Canvas, { camera: { fov: 55, near: 0.1, far: 300 }, children: [_jsx("color", { attach: "background", args: ["#14161b"] }), _jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 }), _jsxs(GameProvider, { context: ctx, children: [_jsx(WorldView, { entitySprites: playable.entitySprites }), WorldOverlay !== undefined ? _jsx(WorldOverlay, {}) : null, _jsx(GameOrbitCamera, { yawRef: yawRef, config: playable.camera, followEntityId: playable.camera?.followEntityId, onCameraFollow: playable.camera?.onCameraFollow, onDragChange: (dragging) => {
+                                    cameraDraggingRef.current = dragging;
+                                } })] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, primaryClickRef: primaryClickRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef })] }), _jsx(GameUiErrorBoundary, { onRuntimeError: reportRuntimeError, children: _jsx(GameProvider, { context: ctx, children: _jsx(GameUI, {}) }) }), _jsx(DiagnosticOverlay, { diagnostics: diagnostics })] }));
+}

package/dist/GameUiPreview.d.ts

@@ -0,0 +1,8 @@
+import { type GameContext } from "@jgengine/core/runtime/gameContext";
+import type { PlayableGame } from "./registry.js";
+export type UiPreviewScenario = (ctx: GameContext, playable: PlayableGame) => void;
+export declare const defaultUiScenario: UiPreviewScenario;
+export declare function GameUiPreview({ playable, scenario, }: {
+    playable: PlayableGame;
+    scenario?: UiPreviewScenario;
+}): import("react").JSX.Element;

package/dist/GameUiPreview.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { createGameContext } from "@jgengine/core/runtime/gameContext";
+import { GameProvider } from "@jgengine/react/provider";
+const PREVIEW_USER_ID = "ui-preview";
+const TICK_STEP = 1 / 60;
+function runTicks(ctx, playable, seconds) {
+    const steps = Math.round(seconds / TICK_STEP);
+    for (let index = 0; index < steps; index += 1) {
+        playable.loop.onTick(ctx, TICK_STEP);
+    }
+}
+export const defaultUiScenario = (ctx, playable) => {
+    runTicks(ctx, playable, 4);
+    if (ctx.game.commands.has("target.cycle"))
+        ctx.game.commands.run("target.cycle", {});
+    else
+        ctx.scene.entity.cycleTarget(PREVIEW_USER_ID, { filter: "hostile" });
+    const declarations = Object.entries(playable.game.inventories ?? {});
+    const hotbarId = (declarations.find(([, declaration]) => declaration.hud === "hotbar") ??
+        declarations[0])?.[0];
+    if (hotbarId !== undefined) {
+        const slots = ctx.player.inventory.state(hotbarId).slots;
+        const slot = slots.findIndex((stack) => stack !== null && stack !== undefined);
+        if (slot >= 0) {
+            ctx.item.use.use({
+                from: PREVIEW_USER_ID,
+                itemId: slots[slot].itemId,
+                inventoryId: hotbarId,
+                aim: { yaw: 0, pitch: 0 },
+            });
+        }
+    }
+    runTicks(ctx, playable, 0.5);
+};
+export function GameUiPreview({ playable, scenario = defaultUiScenario, }) {
+    const [ctx, setCtx] = useState(null);
+    useEffect(() => {
+        playable.game.scene.clear();
+        const context = createGameContext({
+            definition: playable.game,
+            content: playable.content,
+            player: { userId: PREVIEW_USER_ID, isNew: true },
+        });
+        playable.loop.onInit(context);
+        playable.loop.onNewPlayer(context);
+        try {
+            scenario(context, playable);
+        }
+        catch (error) {
+            console.error("[jgengine:ui-preview] scenario failed", error);
+        }
+        setCtx(context);
+        return () => {
+            playable.game.scene.clear();
+            setCtx(null);
+        };
+    }, [playable, scenario]);
+    if (ctx === null)
+        return _jsx("div", { className: "h-full w-full bg-neutral-900" });
+    const GameUI = playable.GameUI;
+    return (_jsx("div", { "data-ui-preview-ready": true, className: "relative h-full w-full overflow-hidden", style: { background: "linear-gradient(180deg, #2a3d33 0%, #1a2320 55%, #141b18 100%)" }, children: _jsx(GameProvider, { context: ctx, children: _jsx(GameUI, {}) }) }));
+}

package/dist/camera/GameOrbitCamera.d.ts

@@ -0,0 +1,17 @@
+import { type MutableRefObject } from "react";
+import { type Camera, Vector3 } from "three";
+import type { SceneEntity } from "@jgengine/core/scene/entityStore";
+import { type CameraFollowState, type OrbitCameraConfig, type Vec3 } from "./orbitCameraMath.js";
+export type CameraFollowListener = (state: CameraFollowState) => void;
+export interface GameOrbitCameraProps {
+    yawRef: MutableRefObject<number>;
+    config?: Partial<OrbitCameraConfig>;
+    followEntityId?: string;
+    /** Override orbit target derived from the followed entity. */
+    resolveFollowTarget?: (entity: SceneEntity) => Vec3;
+    onDragChange?: (dragging: boolean) => void;
+    onCameraFollow?: CameraFollowListener;
+}
+export declare function GameOrbitCamera({ yawRef, config: configPatch, followEntityId, resolveFollowTarget, onDragChange, onCameraFollow, }: GameOrbitCameraProps): import("react").JSX.Element;
+/** Seed orbit target before controls mount (demo spawn at origin). */
+export declare function seedOrbitCameraTarget(camera: Camera, target: Vector3, distance: number, height: number): void;

package/dist/camera/GameOrbitCamera.js

@@ -0,0 +1,86 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { OrbitControls } from "@react-three/drei";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useRef } from "react";
+import { MOUSE, Vector3 } from "three";
+import { useGameContext } from "@jgengine/react/provider";
+import { usePlayer } from "@jgengine/react/hooks";
+import { ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, seedOrbitFollowState, } from "./orbitCameraMath.js";
+export function GameOrbitCamera({ yawRef, config: configPatch, followEntityId, resolveFollowTarget, onDragChange, onCameraFollow, }) {
+    const config = resolveOrbitCameraConfig(configPatch);
+    const controlsRef = useRef(null);
+    const runtimeRef = useRef(null);
+    const draggingRef = useRef(false);
+    const { userId } = usePlayer();
+    const ctx = useGameContext();
+    const camera = useThree((state) => state.camera);
+    const followId = followEntityId ?? userId;
+    useEffect(() => {
+        const entity = ctx.scene.entity.get(followId);
+        if (entity === null || runtimeRef.current !== null)
+            return;
+        const seeded = seedOrbitFollowState({ entityPosition: entity.position, config });
+        runtimeRef.current = seeded;
+        camera.position.set(seeded.camera.x, seeded.camera.y, seeded.camera.z);
+        camera.lookAt(seeded.target.x, seeded.target.y, seeded.target.z);
+    }, [camera, config, ctx, followId]);
+    useFrame((_, delta) => {
+        const controls = controlsRef.current;
+        const entity = ctx.scene.entity.get(followId);
+        if (controls === null || entity === null)
+            return;
+        if (runtimeRef.current === null) {
+            runtimeRef.current = seedOrbitFollowState({ entityPosition: entity.position, config });
+            camera.position.set(runtimeRef.current.camera.x, runtimeRef.current.camera.y, runtimeRef.current.camera.z);
+            controls.target.set(runtimeRef.current.target.x, runtimeRef.current.target.y, runtimeRef.current.target.z);
+        }
+        const runtime = runtimeRef.current;
+        const previousTarget = runtime.target;
+        const desiredTarget = resolveFollowTarget?.(entity) ?? resolveFollowTargetFromPosition(entity.position, config);
+        const stepped = orbitFollowStep({
+            state: runtime,
+            desiredTarget,
+            deltaSeconds: delta,
+            config,
+            dragging: draggingRef.current,
+        });
+        controls.target.set(stepped.target.x, stepped.target.y, stepped.target.z);
+        if (draggingRef.current) {
+            camera.position.x += stepped.target.x - previousTarget.x;
+            camera.position.y += stepped.target.y - previousTarget.y;
+            camera.position.z += stepped.target.z - previousTarget.z;
+        }
+        else {
+            camera.position.set(stepped.camera.x, stepped.camera.y, stepped.camera.z);
+        }
+        controls.update();
+        runtimeRef.current = {
+            target: stepped.target,
+            camera: { x: camera.position.x, y: camera.position.y, z: camera.position.z },
+            lockedDistance: draggingRef.current ? controls.getDistance() : stepped.lockedDistance,
+        };
+        const [px, , pz] = entity.position;
+        yawRef.current = orbitYawFromCamera(camera.position.x, camera.position.z, px, pz);
+        onCameraFollow?.({
+            entityId: followId,
+            target: stepped.target,
+            camera: runtimeRef.current.camera,
+            distance: runtimeRef.current.lockedDistance ?? stepped.distance,
+        });
+    }, ORBIT_CAMERA_FRAME_PRIORITY);
+    return (_jsx(OrbitControls, { ref: controlsRef, enableDamping: true, dampingFactor: config.dampingFactor, rotateSpeed: config.rotateSpeed, zoomSpeed: config.zoomSpeed, enablePan: false, enableRotate: true, enableZoom: true, minDistance: config.minDistance, maxDistance: config.maxDistance, maxPolarAngle: Math.PI / 2.05, minPolarAngle: 0.12, screenSpacePanning: false, mouseButtons: { LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.DOLLY, RIGHT: undefined }, onStart: () => {
+            draggingRef.current = true;
+            onDragChange?.(true);
+        }, onEnd: () => {
+            draggingRef.current = false;
+            onDragChange?.(false);
+            if (controlsRef.current !== null && runtimeRef.current !== null) {
+                runtimeRef.current.lockedDistance = controlsRef.current.getDistance();
+            }
+        } }));
+}
+/** Seed orbit target before controls mount (demo spawn at origin). */
+export function seedOrbitCameraTarget(camera, target, distance, height) {
+    camera.position.set(target.x, height, target.z - distance);
+    camera.lookAt(target);
+}

package/dist/camera/index.d.ts

@@ -0,0 +1,2 @@
+export { GameOrbitCamera, type CameraFollowListener, type GameOrbitCameraProps } from "./GameOrbitCamera.js";
+export { cameraFollowStep, DEFAULT_ORBIT_CAMERA, distanceBetween, GAME_SIM_FRAME_PRIORITY, lerpVec3, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, resolveTargetSmoothing, seedOrbitFollowState, smoothBlend, type CameraFollowState, type OrbitCameraConfig, type OrbitFollowRuntimeState, type ResolvedOrbitCameraConfig, type Vec3, } from "./orbitCameraMath.js";

package/dist/camera/index.js

@@ -0,0 +1,2 @@
+export { GameOrbitCamera } from "./GameOrbitCamera.js";
+export { cameraFollowStep, DEFAULT_ORBIT_CAMERA, distanceBetween, GAME_SIM_FRAME_PRIORITY, lerpVec3, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, resolveTargetSmoothing, seedOrbitFollowState, smoothBlend, } from "./orbitCameraMath.js";