@jgengine/shell 0.1.0

package/dist/camera/orbitCameraMath.d.ts

@@ -0,0 +1,96 @@
+/** Horizontal facing derived from an orbit camera orbiting a target on the XZ plane. */
+export declare function orbitYawFromCamera(cameraX: number, cameraZ: number, targetX: number, targetZ: number): number;
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface CameraFollowState {
+    entityId: string;
+    target: Vec3;
+    camera: Vec3;
+    distance: number;
+}
+export interface OrbitCameraConfig {
+    minDistance?: number;
+    maxDistance?: number;
+    targetHeight?: number;
+    initialDistance?: number;
+    initialHeight?: number;
+    /** Extra offset applied on top of entity position for the orbit target. */
+    targetOffset?: Partial<Vec3>;
+    /** Keep orbit radius locked while the follow target moves. */
+    followLock?: boolean;
+    /** When false, orbit target stays fixed (cinematic / debug). Default true. */
+    followEnabled?: boolean;
+    /** Orbit drag sensitivity (lower = smoother). Default OrbitControls is 1. */
+    rotateSpeed?: number;
+    zoomSpeed?: number;
+    /** Inertia decay while orbiting (lower = longer coast). */
+    dampingFactor?: number;
+    /** Exponential smoothing when the follow target moves. Higher = snappier. */
+    targetSmoothing?: number;
+    /** Faster target follow while orbiting (defaults to ~1.8× targetSmoothing). */
+    dragTargetSmoothing?: number;
+    /** Exponential smoothing when re-locking orbit distance. */
+    distanceSmoothing?: number;
+}
+/** Fully resolved shell config after merging with DEFAULT_ORBIT_CAMERA. */
+export interface ResolvedOrbitCameraConfig {
+    minDistance: number;
+    maxDistance: number;
+    targetHeight: number;
+    initialDistance: number;
+    initialHeight: number;
+    targetOffset?: Partial<Vec3>;
+    followLock: boolean;
+    followEnabled: boolean;
+    rotateSpeed: number;
+    zoomSpeed: number;
+    dampingFactor: number;
+    targetSmoothing: number;
+    dragTargetSmoothing: number;
+    distanceSmoothing: number;
+}
+export declare const DEFAULT_ORBIT_CAMERA: ResolvedOrbitCameraConfig;
+/** Run simulation/movement before orbit follow so poses are current. */
+export declare const GAME_SIM_FRAME_PRIORITY = 0;
+/** Orbit follow reads the latest entity pose after GAME_SIM_FRAME_PRIORITY. */
+export declare const ORBIT_CAMERA_FRAME_PRIORITY = -1;
+export interface OrbitFollowRuntimeState {
+    target: Vec3;
+    camera: Vec3;
+    lockedDistance: number | null;
+}
+/** Frame-rate independent exponential smoothing factor in [0, 1]. */
+export declare function smoothBlend(deltaSeconds: number, speed: number): number;
+export declare function resolveOrbitCameraConfig(patch?: OrbitCameraConfig): ResolvedOrbitCameraConfig;
+export declare function resolveTargetSmoothing(config: ResolvedOrbitCameraConfig, dragging: boolean): number;
+export declare function resolveFollowTargetFromPosition(position: readonly [number, number, number], config: Pick<ResolvedOrbitCameraConfig, "targetHeight" | "targetOffset">): Vec3;
+export declare function lerpVec3(from: Vec3, to: Vec3, blend: number): Vec3;
+export declare function distanceBetween(a: Vec3, b: Vec3): number;
+export declare function seedOrbitFollowState(input: {
+    entityPosition: readonly [number, number, number];
+    config: Pick<ResolvedOrbitCameraConfig, "targetHeight" | "targetOffset" | "initialDistance" | "initialHeight">;
+}): OrbitFollowRuntimeState;
+/**
+ * Pure orbit follow step — smooth target tracking, camera carries target delta
+ * (OrbitControls alone keeps camera fixed when only target moves), optional
+ * distance lock. Call each frame before OrbitControls.update() in the shell.
+ */
+export declare function orbitFollowStep(input: {
+    state: OrbitFollowRuntimeState;
+    desiredTarget: Vec3;
+    deltaSeconds: number;
+    config: ResolvedOrbitCameraConfig;
+    dragging: boolean;
+}): OrbitFollowRuntimeState & {
+    distance: number;
+};
+/** @deprecated Use orbitFollowStep — kept for older call sites. */
+export declare function cameraFollowStep(input: {
+    camera: Vec3;
+    target: Vec3;
+    previousTarget: Vec3 | null;
+    lockedDistance: number | null;
+}): CameraFollowState;

package/dist/camera/orbitCameraMath.js

@@ -0,0 +1,130 @@
+/** Horizontal facing derived from an orbit camera orbiting a target on the XZ plane. */
+export function orbitYawFromCamera(cameraX, cameraZ, targetX, targetZ) {
+    const dx = targetX - cameraX;
+    const dz = targetZ - cameraZ;
+    return Math.atan2(dx, dz);
+}
+export const DEFAULT_ORBIT_CAMERA = {
+    minDistance: 4,
+    maxDistance: 28,
+    targetHeight: 1.2,
+    initialDistance: 9,
+    initialHeight: 5.5,
+    followLock: true,
+    followEnabled: true,
+    rotateSpeed: 0.22,
+    zoomSpeed: 0.45,
+    dampingFactor: 0.035,
+    targetSmoothing: 8,
+    dragTargetSmoothing: 11,
+    distanceSmoothing: 5,
+};
+/** Run simulation/movement before orbit follow so poses are current. */
+export const GAME_SIM_FRAME_PRIORITY = 0;
+/** Orbit follow reads the latest entity pose after GAME_SIM_FRAME_PRIORITY. */
+export const ORBIT_CAMERA_FRAME_PRIORITY = -1;
+/** Frame-rate independent exponential smoothing factor in [0, 1]. */
+export function smoothBlend(deltaSeconds, speed) {
+    return 1 - Math.exp(-speed * deltaSeconds);
+}
+export function resolveOrbitCameraConfig(patch) {
+    return { ...DEFAULT_ORBIT_CAMERA, ...patch };
+}
+export function resolveTargetSmoothing(config, dragging) {
+    if (dragging) {
+        return config.dragTargetSmoothing;
+    }
+    return config.targetSmoothing;
+}
+export function resolveFollowTargetFromPosition(position, config) {
+    const offset = config.targetOffset;
+    return {
+        x: position[0] + (offset?.x ?? 0),
+        y: position[1] + config.targetHeight + (offset?.y ?? 0),
+        z: position[2] + (offset?.z ?? 0),
+    };
+}
+export function lerpVec3(from, to, blend) {
+    return {
+        x: from.x + (to.x - from.x) * blend,
+        y: from.y + (to.y - from.y) * blend,
+        z: from.z + (to.z - from.z) * blend,
+    };
+}
+export function distanceBetween(a, b) {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    const dz = a.z - b.z;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+export function seedOrbitFollowState(input) {
+    const target = resolveFollowTargetFromPosition(input.entityPosition, input.config);
+    return {
+        target,
+        camera: {
+            x: target.x,
+            y: input.config.initialHeight,
+            z: target.z - input.config.initialDistance,
+        },
+        lockedDistance: input.config.initialDistance,
+    };
+}
+/**
+ * Pure orbit follow step — smooth target tracking, camera carries target delta
+ * (OrbitControls alone keeps camera fixed when only target moves), optional
+ * distance lock. Call each frame before OrbitControls.update() in the shell.
+ */
+export function orbitFollowStep(input) {
+    const target = { ...input.state.target };
+    const camera = { ...input.state.camera };
+    let lockedDistance = input.state.lockedDistance;
+    const followEnabled = input.config.followEnabled !== false;
+    const desiredTarget = followEnabled ? input.desiredTarget : target;
+    const previousTarget = { ...target };
+    const targetBlend = smoothBlend(input.deltaSeconds, resolveTargetSmoothing(input.config, input.dragging));
+    const lerpedTarget = lerpVec3(target, desiredTarget, targetBlend);
+    target.x = lerpedTarget.x;
+    target.y = lerpedTarget.y;
+    target.z = lerpedTarget.z;
+    // OrbitControls preserves camera world position when only the target moves.
+    camera.x += target.x - previousTarget.x;
+    camera.y += target.y - previousTarget.y;
+    camera.z += target.z - previousTarget.z;
+    const followLock = input.config.followLock !== false;
+    if (followLock && !input.dragging && lockedDistance !== null) {
+        const currentDistance = distanceBetween(camera, target);
+        if (currentDistance > 0.0001) {
+            const scale = lockedDistance / currentDistance;
+            const idealCamera = {
+                x: target.x + (camera.x - target.x) * scale,
+                y: target.y + (camera.y - target.y) * scale,
+                z: target.z + (camera.z - target.z) * scale,
+            };
+            const distanceBlend = smoothBlend(input.deltaSeconds, input.config.distanceSmoothing);
+            const smoothedCamera = lerpVec3(camera, idealCamera, distanceBlend);
+            camera.x = smoothedCamera.x;
+            camera.y = smoothedCamera.y;
+            camera.z = smoothedCamera.z;
+        }
+    }
+    if (!input.dragging) {
+        lockedDistance = distanceBetween(camera, target);
+    }
+    return { target, camera, lockedDistance, distance: distanceBetween(camera, target) };
+}
+/** @deprecated Use orbitFollowStep — kept for older call sites. */
+export function cameraFollowStep(input) {
+    const state = {
+        target: input.previousTarget ?? input.target,
+        camera: input.camera,
+        lockedDistance: input.lockedDistance,
+    };
+    const stepped = orbitFollowStep({
+        state,
+        desiredTarget: input.target,
+        deltaSeconds: 1,
+        config: { ...DEFAULT_ORBIT_CAMERA, targetSmoothing: 1000, distanceSmoothing: 1000 },
+        dragging: false,
+    });
+    return { entityId: "", target: stepped.target, camera: stepped.camera, distance: stepped.distance };
+}

package/dist/demo/demoGame.d.ts

@@ -0,0 +1,2 @@
+import type { PlayableGame } from "../registry.js";
+export declare const demoGame: PlayableGame;

package/dist/demo/demoGame.js

@@ -0,0 +1,200 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { defineGame } from "@jgengine/core/game/defineGame";
+import { createAssetCatalog } from "@jgengine/core/scene/assetCatalog";
+import { CurrencyPill, HealthBar, SlotGrid } from "@jgengine/react/components";
+import { useFeed, useGameStore, usePlayer, useTarget } from "@jgengine/react/hooks";
+const HERO = "hero";
+const MOB = "gloomSlime";
+const LOOT_TABLE = "slime-drops";
+const GOLD = "gold";
+const HOTBAR = "hotbar";
+const MELEE_DAMAGE = 6;
+const MELEE_RANGE = 1.9;
+const MELEE_COOLDOWN = 1.2;
+const AGGRO_RADIUS = 11;
+const MOB_SPAWNS = [
+    [7, 0, -6],
+    [-8, 0, 5],
+    [6, 0, 8],
+];
+const entityCatalog = {
+    [HERO]: {
+        stats: { health: { max: 100 }, mana: { max: 60 } },
+        receive: { damage: { order: ["health"] } },
+        movement: { poses: ["standing", "running", "crouch"], walkSpeed: 2.4 },
+    },
+    [MOB]: {
+        stats: { health: { max: 60 } },
+        receive: { damage: { order: ["health"] } },
+        onDeath: { drops: LOOT_TABLE },
+        role: "enemy",
+    },
+};
+const itemCatalog = {
+    sword: { use: "swingSword", weapon: { damage: 22 } },
+    zap: { use: "castZap", weapon: { damage: 35, manaCost: 12, range: 18 } },
+};
+const game = defineGame({
+    name: "gameplayer-demo",
+    assets: createAssetCatalog(),
+    multiplayer: null,
+    inventories: { [HOTBAR]: { slots: 4, hud: "hotbar" } },
+    input: {
+        moveForward: ["KeyW"],
+        moveBack: ["KeyS"],
+        moveLeft: ["KeyA"],
+        moveRight: ["KeyD"],
+        jump: ["Space"],
+        sprint: ["Shift"],
+        turnLeft: ["KeyQ"],
+        turnRight: ["KeyE"],
+        tabTarget: ["Tab"],
+        clearTarget: ["Escape"],
+        slot1: ["Digit1"],
+        slot2: ["Digit2"],
+    },
+});
+let elapsed = 0;
+let nextSpawnIndex = 0;
+const meleeReadyAt = new Map();
+function spawnMob(ctx) {
+    const at = MOB_SPAWNS[nextSpawnIndex % MOB_SPAWNS.length];
+    nextSpawnIndex += 1;
+    ctx.scene.entity.spawn(MOB, { position: at, role: "npc" });
+}
+function spawnHero(ctx) {
+    ctx.scene.entity.spawn(HERO, {
+        id: ctx.player.userId,
+        position: [0, 0, 0],
+        role: "player",
+    });
+}
+function onInit(ctx) {
+    elapsed = 0;
+    nextSpawnIndex = 0;
+    meleeReadyAt.clear();
+    ctx.game.loot.register({ id: LOOT_TABLE, entries: [{ currency: GOLD, count: [2, 5], weight: 1 }] });
+    ctx.game.feed.bind("entity.died");
+    ctx.game.events.on("entity.died", (event) => {
+        if (event.catalogId === MOB) {
+            meleeReadyAt.delete(event.instanceId);
+            spawnMob(ctx);
+        }
+    });
+    ctx.item.use.register({
+        swingSword: {
+            apply(state, input) {
+                const hits = state.scene.entity
+                    .queryArc({ from: input.from, aim: input.aim ?? { yaw: 0, pitch: 0 }, radius: 3.2, halfAngleDeg: 70 })
+                    .filter((id) => state.scene.entity.get(id)?.name === MOB);
+                for (const id of hits) {
+                    state.scene.entity.effect({ from: input.from, to: id, effect: "damage", via: { item: input.itemId } });
+                }
+                return { state };
+            },
+        },
+        castZap: {
+            can(state, input) {
+                const targetId = state.scene.entity.getTarget(input.from);
+                if (targetId === null)
+                    return { reason: "no-target" };
+                const range = state.item.weapon.getStat(input.itemId, "range") ?? Number.POSITIVE_INFINITY;
+                const distance = state.scene.entity.distance(input.from, targetId);
+                if (distance === null || distance > range)
+                    return { reason: "out-of-range" };
+                const cost = state.item.weapon.getStat(input.itemId, "manaCost") ?? 0;
+                const mana = state.scene.entity.stats.get(input.from, "mana");
+                if (mana === null || mana.current < cost)
+                    return { reason: "no-mana" };
+                return null;
+            },
+            apply(state, input) {
+                const targetId = state.scene.entity.getTarget(input.from);
+                if (targetId === null)
+                    return { state, error: "no-target" };
+                const cost = state.item.weapon.getStat(input.itemId, "manaCost") ?? 0;
+                state.scene.entity.stats.delta(input.from, "mana", -cost);
+                state.scene.entity.effect({ from: input.from, to: targetId, effect: "damage", via: { item: input.itemId } });
+                return { state };
+            },
+        },
+    });
+}
+function onNewPlayer(ctx) {
+    spawnHero(ctx);
+    ctx.player.inventory.put(HOTBAR, "sword", 1);
+    ctx.player.inventory.put(HOTBAR, "zap", 1);
+    ctx.game.economy.grant(ctx.player.userId, GOLD, 10);
+    for (let index = 0; index < MOB_SPAWNS.length; index += 1)
+        spawnMob(ctx);
+}
+function onTick(ctx, dt) {
+    elapsed += dt;
+    const playerId = ctx.player.userId;
+    const player = ctx.scene.entity.get(playerId);
+    if (player === null) {
+        spawnHero(ctx);
+        return;
+    }
+    const mana = ctx.scene.entity.stats.get(playerId, "mana");
+    if (mana !== null && mana.current < mana.max)
+        ctx.scene.entity.stats.delta(playerId, "mana", 5 * dt);
+    for (const mob of ctx.scene.entity.list()) {
+        if (mob.name !== MOB)
+            continue;
+        const distance = ctx.scene.entity.distance(mob.id, playerId);
+        if (distance === null || distance > AGGRO_RADIUS)
+            continue;
+        if (distance > MELEE_RANGE) {
+            const next = ctx.scene.entity.moveToward(mob.id, playerId, {
+                speed: 2,
+                stopDistance: MELEE_RANGE * 0.8,
+                dt,
+            });
+            if (next !== null) {
+                ctx.scene.entity.setPose(mob.id, {
+                    position: next,
+                    rotationY: Math.atan2(player.position[0] - next[0], player.position[2] - next[2]),
+                });
+            }
+        }
+        else if ((meleeReadyAt.get(mob.id) ?? 0) <= elapsed) {
+            meleeReadyAt.set(mob.id, elapsed + MELEE_COOLDOWN);
+            ctx.scene.entity.effect({ from: mob.id, to: playerId, effect: "damage", via: { amount: MELEE_DAMAGE } });
+        }
+    }
+}
+function VitalsPanel({ userId }) {
+    return (_jsxs("div", { className: "rounded bg-black/60 p-2", children: [_jsx(HealthBar, { instanceId: userId, statId: "health", className: "h-2.5 overflow-hidden rounded bg-white/15", fillClassName: "bg-emerald-400" }), _jsx(HealthBar, { instanceId: userId, statId: "mana", className: "mt-1 h-1.5 overflow-hidden rounded bg-white/15", fillClassName: "bg-sky-400" })] }));
+}
+function TargetPanel({ userId }) {
+    const targetId = useTarget(userId);
+    const targetName = useGameStore((ctx) => targetId === null ? null : (ctx.scene.entity.get(targetId)?.name ?? null));
+    if (targetId === null || targetName === null) {
+        return _jsx("p", { className: "rounded bg-black/50 px-2 py-1 text-center text-xs text-white/50", children: "Tab: target a mob" });
+    }
+    return (_jsxs("div", { className: "rounded bg-black/60 p-2", children: [_jsx("p", { className: "text-xs uppercase tracking-wide text-red-300", children: targetName }), _jsx(HealthBar, { instanceId: targetId, statId: "health", className: "mt-1 h-2 overflow-hidden rounded bg-white/15", fillClassName: "bg-red-400" })] }));
+}
+function KillFeedPanel() {
+    const kills = useFeed({ action: "entity.died", limit: 5 });
+    return (_jsx("ul", { className: "space-y-0.5 text-right text-xs text-white/70", children: kills
+            .slice()
+            .reverse()
+            .map((entry, index) => (_jsxs("li", { children: [entry.data.catalogId ?? "?", " down"] }, `${entry.at}-${index}`))) }));
+}
+function HotbarPanel() {
+    return (_jsx(SlotGrid, { inventoryId: HOTBAR, className: "flex gap-1.5", renderSlot: (slot, index) => (_jsxs("div", { className: "w-16 rounded border border-white/20 bg-black/60 px-1.5 py-1 text-center text-[11px]", children: [_jsx("span", { className: "text-white/50", children: index + 1 }), _jsx("p", { className: "truncate text-white", children: slot === null ? "—" : slot.itemId })] })) }));
+}
+function DemoGameUI() {
+    const player = usePlayer();
+    return (_jsxs("div", { className: "pointer-events-none absolute inset-0 font-mono text-white", children: [_jsx("div", { className: "absolute left-1/2 top-4 w-56 -translate-x-1/2", children: _jsx(TargetPanel, { userId: player.userId }) }), _jsxs("div", { className: "absolute right-4 top-4 flex flex-col items-end gap-2", children: [_jsx(CurrencyPill, { currencyId: GOLD, className: "rounded bg-black/60 px-2 py-1 text-sm text-amber-300" }), _jsx(KillFeedPanel, {})] }), _jsx("div", { className: "absolute bottom-4 left-4 w-64", children: _jsx(VitalsPanel, { userId: player.userId }) }), _jsx("div", { className: "absolute bottom-4 left-1/2 -translate-x-1/2", children: _jsx(HotbarPanel, {}) }), _jsx("div", { className: "absolute bottom-4 right-4 max-w-[220px] text-right text-[11px] leading-4 text-white/40", children: "WASD move \u00B7 Space jump \u00B7 Shift sprint \u00B7 Q/E turn \u00B7 Tab target \u00B7 Esc clear \u00B7 1 sword \u00B7 2 zap" })] }));
+}
+export const demoGame = {
+    game,
+    content: {
+        itemById: (itemId) => itemCatalog[itemId] ?? null,
+        entityById: (catalogId) => entityCatalog[catalogId] ?? null,
+    },
+    loop: { onInit, onNewPlayer, onTick },
+    GameUI: DemoGameUI,
+};

package/dist/multiplayer.d.ts

@@ -0,0 +1,16 @@
+import type { GameDefinition } from "@jgengine/core/game/defineGame";
+import { type WsBackend } from "@jgengine/ws/createWsBackend";
+export type ShellMultiplayer = {
+    gameId: string;
+    userId: string;
+    backend: WsBackend;
+    feedActions: string[];
+};
+export declare function resolveShellMultiplayer(args: {
+    game: GameDefinition;
+    gameId: string;
+    url?: string;
+    userId?: string;
+    force?: boolean;
+    feedActions?: string[];
+}): ShellMultiplayer | null;

package/dist/multiplayer.js

@@ -0,0 +1,21 @@
+import { createWsBackend } from "@jgengine/ws/createWsBackend";
+function adapterKind(multiplayer) {
+    if (typeof multiplayer !== "object" || multiplayer === null)
+        return null;
+    const direct = multiplayer.kind;
+    if (typeof direct === "string")
+        return direct;
+    const nested = multiplayer.adapter?.kind;
+    return typeof nested === "string" ? nested : null;
+}
+export function resolveShellMultiplayer(args) {
+    if (args.force !== true && adapterKind(args.game.multiplayer) !== "ws")
+        return null;
+    const userId = args.userId ?? `player-${Math.random().toString(36).slice(2, 10)}`;
+    return {
+        gameId: args.gameId,
+        userId,
+        backend: createWsBackend({ url: args.url ?? "ws://localhost:8080/ws", userId }),
+        feedActions: args.feedActions ?? ["entity.died"],
+    };
+}

package/dist/registry.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentType } from "react";
+import type { PlayableGame as EnginePlayableGame } from "@jgengine/core/game/playableGame";
+export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType>;
+export type GameRegistry = Record<string, () => Promise<PlayableGame>>;

package/dist/registry.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@jgengine/shell",
+  "version": "0.1.0",
+  "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Noisemaker111/jgengine.git",
+    "directory": "packages/shell"
+  },
+  "files": ["dist"],
+  "exports": {
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun ../../scripts/fix-extensions.ts dist",
+    "check-types": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@jgengine/core": "^0.1.1",
+    "@jgengine/react": "^0.1.0",
+    "@jgengine/ws": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@react-three/drei": "^10.0.0",
+    "@react-three/fiber": "^9.0.0",
+    "react": "^19.0.0",
+    "three": ">=0.170.0",
+    "three-stdlib": "^2.0.0"
+  },
+  "devDependencies": {
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.5.0",
+    "@types/react": "^19",
+    "@types/three": "^0.182.0",
+    "react": "19.2.3",
+    "three": "^0.182.0",
+    "three-stdlib": "^2.35.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}