@jgengine/shell 0.8.0 → 0.10.0

package/dist/camera/rigMath.d.ts

@@ -11,6 +11,7 @@ export declare function clamp(value: number, min: number, max: number): number;
 export declare function lerp(from: number, to: number, blend: number): number;
 export declare function smoothstep(t: number): number;
 export declare function forwardVector(yaw: number): Vec3;
+/** Screen-right of a yaw: `forward × up` with up = +Y. */
 export declare function rightVector(yaw: number): Vec3;
 export interface ResolvedTopDown {
     height: number;
@@ -87,8 +88,17 @@ export interface ResolvedChase {
     lookHeight: number;
     springDamping: number;
     shakePerSpeed: number;
+    leadTime: number;
+    leadMax: number;
+    bankPerYawRate: number;
+    bankMax: number;
+    bankDamping: number;
 }
 export declare function resolveChase(config: ChaseCameraConfig | undefined): ResolvedChase;
+/** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`. */
+export declare function leadFollowPoint(follow: Vec3, previous: Vec3, dt: number, resolved: ResolvedChase): Vec3;
+/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped. */
+export declare function bankRollStep(currentRoll: number, yaw: number, previousYaw: number, dt: number, resolved: ResolvedChase): number;
 export interface ResolvedObserver {
     distance: number;
     height: number;

package/dist/camera/rigMath.js

@@ -24,8 +24,9 @@ export function smoothstep(t) {
 export function forwardVector(yaw) {
     return { x: Math.sin(yaw), y: 0, z: Math.cos(yaw) };
 }
+/** Screen-right of a yaw: `forward × up` with up = +Y. */
 export function rightVector(yaw) {
-    return { x: Math.cos(yaw), y: 0, z: -Math.sin(yaw) };
+    return { x: -Math.cos(yaw), y: 0, z: Math.sin(yaw) };
 }
 export function resolveTopDown(config) {
     return {
@@ -207,8 +208,42 @@ export function resolveChase(config) {
         lookHeight: config?.lookHeight ?? 1.2,
         springDamping: config?.springDamping ?? 6,
         shakePerSpeed: config?.shakePerSpeed ?? 0,
+        leadTime: config?.lead?.time ?? 0,
+        leadMax: config?.lead?.max ?? 4,
+        bankPerYawRate: config?.bank?.perYawRate ?? 0,
+        bankMax: config?.bank?.max ?? 0.35,
+        bankDamping: config?.bank?.damping ?? 8,
     };
 }
+/** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`. */
+export function leadFollowPoint(follow, previous, dt, resolved) {
+    if (resolved.leadTime <= 0 || dt <= 0)
+        return follow;
+    let leadX = ((follow.x - previous.x) / dt) * resolved.leadTime;
+    let leadZ = ((follow.z - previous.z) / dt) * resolved.leadTime;
+    const magnitude = Math.hypot(leadX, leadZ);
+    if (magnitude > resolved.leadMax) {
+        leadX *= resolved.leadMax / magnitude;
+        leadZ *= resolved.leadMax / magnitude;
+    }
+    return { x: follow.x + leadX, y: follow.y, z: follow.z + leadZ };
+}
+function wrapAngle(angle) {
+    let wrapped = angle;
+    while (wrapped > Math.PI)
+        wrapped -= Math.PI * 2;
+    while (wrapped < -Math.PI)
+        wrapped += Math.PI * 2;
+    return wrapped;
+}
+/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped. */
+export function bankRollStep(currentRoll, yaw, previousYaw, dt, resolved) {
+    if (resolved.bankPerYawRate <= 0)
+        return 0;
+    const yawRate = dt > 0 ? wrapAngle(yaw - previousYaw) / dt : 0;
+    const target = clamp(-yawRate * resolved.bankPerYawRate, -resolved.bankMax, resolved.bankMax);
+    return currentRoll + (target - currentRoll) * Math.min(1, resolved.bankDamping * dt);
+}
 export function resolveObserver(config) {
     return {
         distance: config?.distance ?? 8,

package/dist/camera/shakeChannel.d.ts

@@ -1,20 +1,6 @@
-import { shakeOffset, type ShakeOffset } from "./rigMath.js";
-export interface CameraShakeChannel {
-    /**
-     * Add a trauma impulse. `amplitude` is a 0..1 fraction (1 = a full boss slam);
-     * `decayPerSecond` optionally overrides how fast this and subsequent trauma
-     * bleed off. Any gameplay system (combat hitstop, explosions, vehicle crashes)
-     * can call this — the active rig reads the resulting shake every frame.
-     */
-    shake(amplitude: number, decayPerSecond?: number): void;
-    /** Advance decay + the shake clock (called once per frame by the mounted rig). */
-    step(dt: number): void;
-    /** Current positional + roll shake for the given tuning. */
-    sample(config?: Parameters<typeof shakeOffset>[1]): ShakeOffset;
-    /** Live trauma in [0,1] (for HUD/debug). */
-    trauma(): number;
-}
-export declare function createCameraShakeChannel(defaultDecayPerSecond?: number): CameraShakeChannel;
+import { type CameraShakeChannel } from "./shakeChannelMath.js";
+export type { CameraShakeChannel } from "./shakeChannelMath.js";
+export { createCameraShakeChannel } from "./shakeChannelMath.js";
 /**
  * Process-wide default channel. A shell mounts its own channel via
  * `CameraShakeContext`, but game systems that have no React context (e.g. a

package/dist/camera/shakeChannel.js

@@ -1,25 +1,6 @@
 import { createContext, useContext } from "react";
-import { addTrauma, createTrauma, shakeOffset, stepTrauma } from "./rigMath.js";
-export function createCameraShakeChannel(defaultDecayPerSecond = 1.6) {
-    const state = createTrauma();
-    let decay = defaultDecayPerSecond;
-    return {
-        shake(amplitude, decayPerSecond) {
-            if (decayPerSecond !== undefined)
-                decay = decayPerSecond;
-            addTrauma(state, amplitude);
-        },
-        step(dt) {
-            stepTrauma(state, decay, dt);
-        },
-        sample(config) {
-            return shakeOffset(state, config);
-        },
-        trauma() {
-            return state.trauma;
-        },
-    };
-}
+import { createCameraShakeChannel, } from "./shakeChannelMath.js";
+export { createCameraShakeChannel } from "./shakeChannelMath.js";
 /**
  * Process-wide default channel. A shell mounts its own channel via
  * `CameraShakeContext`, but game systems that have no React context (e.g. a

package/dist/camera/shakeChannelMath.d.ts

@@ -0,0 +1,8 @@
+import { shakeOffset, type ShakeOffset } from "./rigMath.js";
+export interface CameraShakeChannel {
+    shake(amplitude: number, decayPerSecond?: number): void;
+    step(dt: number): void;
+    sample(config?: Parameters<typeof shakeOffset>[1]): ShakeOffset;
+    trauma(): number;
+}
+export declare function createCameraShakeChannel(defaultDecayPerSecond?: number): CameraShakeChannel;

package/dist/camera/shakeChannelMath.js

@@ -0,0 +1,21 @@
+import { addTrauma, createTrauma, shakeOffset, stepTrauma } from "./rigMath.js";
+export function createCameraShakeChannel(defaultDecayPerSecond = 1.6) {
+    const state = createTrauma();
+    let decay = defaultDecayPerSecond;
+    return {
+        shake(amplitude, decayPerSecond) {
+            if (decayPerSecond !== undefined)
+                decay = decayPerSecond;
+            addTrauma(state, amplitude);
+        },
+        step(dt) {
+            stepTrauma(state, decay, dt);
+        },
+        sample(config) {
+            return shakeOffset(state, config);
+        },
+        trauma() {
+            return state.trauma;
+        },
+    };
+}

package/dist/cartridge.d.ts

@@ -0,0 +1,145 @@
+import { type ComponentType } from "react";
+import { type CartridgeSpec } from "@jgengine/core/cartridge/spec";
+import type { AbilitySlotState } from "@jgengine/core/combat/abilityKit";
+import type { HudAnchor } from "@jgengine/core/ui/hudLayout";
+import { type GameConfig } from "./defineGame.js";
+import type { PlayableGame } from "./registry.js";
+export type CartridgePanelItem = {
+    kind: "vital";
+    stat: string;
+    label: string;
+    tone?: string;
+    width?: number;
+} | {
+    kind: "xp";
+    width?: number;
+} | {
+    kind: "timer";
+    label: string;
+} | {
+    kind: "score";
+    source: "kills";
+    label: string;
+    digits?: number;
+} | {
+    kind: "abilityBar";
+    icons: Record<string, string>;
+} | {
+    kind: "component";
+    Component: ComponentType;
+};
+export interface CartridgeHudPanelSpec {
+    id: string;
+    anchor: HudAnchor;
+    inset?: {
+        x: number;
+        y: number;
+    };
+    items: readonly CartridgePanelItem[];
+}
+export type CartridgeResultLine = {
+    label: string;
+    accent?: boolean;
+} & ({
+    source: "kills" | "level";
+} | {
+    value: string | number;
+});
+export interface CartridgeScreens {
+    start?: {
+        title: string;
+        subtitle?: string;
+        buttonLabel?: string;
+    };
+    win?: {
+        title: string;
+        lines: readonly CartridgeResultLine[];
+    };
+    lose?: {
+        title: string;
+        subtitle?: string;
+    };
+}
+export interface CartridgeAbilitySlot {
+    id: string;
+    icon: string;
+    state: AbilitySlotState;
+    cooldownFraction: number;
+    justCast: boolean;
+}
+export interface CartridgePanels {
+    Vital: ComponentType<{
+        value: {
+            current: number;
+            max: number;
+            min?: number;
+        };
+        label: string;
+        tone?: string;
+        width?: number;
+    }>;
+    Xp: ComponentType<{
+        fraction: number;
+        level?: number;
+        width?: number;
+    }>;
+    Timer: ComponentType<{
+        seconds: number;
+        label: string;
+    }>;
+    Score: ComponentType<{
+        value: number;
+        label: string;
+        digits?: number;
+    }>;
+    AbilityBar: ComponentType<{
+        slots: readonly CartridgeAbilitySlot[];
+    }>;
+    DraftModal: ComponentType<{
+        offers: readonly {
+            id: string;
+            label: string;
+        }[];
+        choose(id: string): void;
+    }>;
+    StartScreen: ComponentType<{
+        title: string;
+        subtitle?: string;
+        buttonLabel?: string;
+        begin(): void;
+    }>;
+    Countdown: ComponentType<{
+        seconds: number;
+    }>;
+    WinScreen: ComponentType<{
+        title: string;
+        lines: readonly {
+            label: string;
+            value: string | number;
+            accent?: boolean;
+        }[];
+    }>;
+    LoseScreen: ComponentType<{
+        title: string;
+        subtitle?: string;
+    }>;
+}
+export type CartridgeConfig = CartridgeSpec & {
+    name: string;
+    panels: CartridgePanels;
+    hud: {
+        storageKey?: string;
+        panels: readonly CartridgeHudPanelSpec[];
+    };
+    screens: CartridgeScreens;
+    theme?: Record<string, string>;
+    world?: GameConfig["world"];
+    physics?: GameConfig["physics"];
+    assets?: GameConfig["assets"];
+    save?: GameConfig["save"];
+    camera?: GameConfig["camera"];
+    entitySprites?: GameConfig["entitySprites"];
+    worldItem?: GameConfig["worldItem"];
+    settings?: GameConfig["settings"];
+};
+export declare function cartridge(config: CartridgeConfig): PlayableGame;

package/dist/cartridge.js

@@ -0,0 +1,246 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { useFrame } from "@react-three/fiber";
+import { createCartridge } from "@jgengine/core/cartridge/runtime";
+import { WASD_KEYBINDS, leveled } from "@jgengine/core/cartridge/spec";
+import { validateCartridge } from "@jgengine/core/cartridge/validate";
+import { HudCanvas, HudPanel, useHudLayout } from "@jgengine/react";
+import { useAbilitySlots, useEntityStat } from "@jgengine/react/hooks";
+import { useGameContext } from "@jgengine/react/provider";
+import { defineGame } from "./defineGame.js";
+function useTick(intervalMs) {
+    const [, setTick] = useState(0);
+    useEffect(() => {
+        const id = window.setInterval(() => setTick((value) => value + 1), intervalMs);
+        return () => window.clearInterval(id);
+    }, [intervalMs]);
+}
+function useRunPhase(ctx, runtime) {
+    const run = runtime.run(ctx);
+    useSyncExternalStore(run.subscribe, () => `${run.phase}:${run.pendingOffers?.map((offer) => offer.id).join(",") ?? ""}`);
+}
+function winSeconds(config) {
+    return config.rules.win?.kind === "survive" ? config.rules.win.seconds : null;
+}
+function VitalItem({ config, item }) {
+    const ctx = useGameContext();
+    const value = useEntityStat(ctx.player.userId, item.stat);
+    if (value === null)
+        return null;
+    return _jsx(config.panels.Vital, { value: value, label: item.label, tone: item.tone, width: item.width });
+}
+function XpItem({ config, item }) {
+    const ctx = useGameContext();
+    const xp = useEntityStat(ctx.player.userId, "xp");
+    const level = useEntityStat(ctx.player.userId, "level");
+    if (xp === null)
+        return null;
+    const fraction = (xp.current - xp.min) / Math.max(1, xp.max - xp.min);
+    return _jsx(config.panels.Xp, { fraction: fraction, level: level?.current, width: item.width });
+}
+function TimerItem({ config, runtime, item, }) {
+    const ctx = useGameContext();
+    const target = winSeconds(config);
+    const elapsed = runtime.run(ctx).playingSeconds;
+    const seconds = target === null ? elapsed : Math.max(0, target - elapsed);
+    return _jsx(config.panels.Timer, { seconds: seconds, label: item.label });
+}
+function ScoreItem({ config, runtime, item, }) {
+    const ctx = useGameContext();
+    return _jsx(config.panels.Score, { value: runtime.run(ctx).kills, label: item.label, digits: item.digits });
+}
+function AbilityBarItem({ config, runtime, item, }) {
+    const ctx = useGameContext();
+    const slots = useAbilitySlots(runtime.weaponKit(ctx));
+    return (_jsx(config.panels.AbilityBar, { slots: slots.map((slot) => ({
+            id: slot.id,
+            icon: item.icons[slot.id] ?? slot.id,
+            state: slot.state,
+            cooldownFraction: slot.cooldownFraction,
+            justCast: slot.justCast,
+        })) }));
+}
+function PanelItems({ config, runtime, items, }) {
+    return (_jsx(_Fragment, { children: items.map((item, index) => {
+            switch (item.kind) {
+                case "vital":
+                    return _jsx(VitalItem, { config: config, item: item }, index);
+                case "xp":
+                    return _jsx(XpItem, { config: config, item: item }, index);
+                case "timer":
+                    return _jsx(TimerItem, { config: config, runtime: runtime, item: item }, index);
+                case "score":
+                    return _jsx(ScoreItem, { config: config, runtime: runtime, item: item }, index);
+                case "abilityBar":
+                    return _jsx(AbilityBarItem, { config: config, runtime: runtime, item: item }, index);
+                case "component":
+                    return _jsx(item.Component, {}, index);
+            }
+        }) }));
+}
+function WinScreenHost({ config, runtime }) {
+    const ctx = useGameContext();
+    const level = useEntityStat(ctx.player.userId, "level");
+    const win = config.screens.win;
+    if (win === undefined)
+        return null;
+    const run = runtime.run(ctx);
+    const lines = win.lines.map((line) => ({
+        label: line.label,
+        accent: line.accent,
+        value: "value" in line ? line.value : line.source === "kills" ? run.kills : (level?.current ?? 1),
+    }));
+    return _jsx(config.panels.WinScreen, { title: win.title, lines: lines });
+}
+function DraftModalHost({ config, runtime }) {
+    const ctx = useGameContext();
+    const offers = runtime.run(ctx).pendingOffers;
+    if (offers === null)
+        return null;
+    return _jsx(config.panels.DraftModal, { offers: offers, choose: (id) => runtime.chooseUpgrade(ctx, id) });
+}
+function CartridgeUI({ config, runtime }) {
+    const ctx = useGameContext();
+    const layout = useHudLayout({ storageKey: config.hud.storageKey ?? config.name });
+    useRunPhase(ctx, runtime);
+    useTick(200);
+    const run = runtime.run(ctx);
+    return (_jsxs("div", { style: { ...config.theme, display: "contents" }, children: [run.phase === "start" && (_jsx(config.panels.StartScreen, { title: config.screens.start?.title ?? config.name, subtitle: config.screens.start?.subtitle, buttonLabel: config.screens.start?.buttonLabel, begin: () => runtime.begin(ctx) })), run.phase === "countdown" && _jsx(config.panels.Countdown, { seconds: Math.ceil(run.countdownRemaining) }), run.phase === "lost" && config.screens.lose !== undefined && (_jsx(config.panels.LoseScreen, { title: config.screens.lose.title, subtitle: config.screens.lose.subtitle })), run.phase === "won" && _jsx(WinScreenHost, { config: config, runtime: runtime }), run.phase === "playing" && (_jsxs(HudCanvas, { layout: layout, children: [_jsx(DraftModalHost, { config: config, runtime: runtime }), config.hud.panels.map((panel) => (_jsx(HudPanel, { id: panel.id, anchor: panel.anchor, inset: panel.inset, style: panel.items.length > 1
+                            ? { display: "flex", flexDirection: "column", alignItems: "center", gap: 6 }
+                            : undefined, children: _jsx(PanelItems, { config: config, runtime: runtime, items: panel.items }) }, panel.id)))] }))] }));
+}
+const MAX_BOLTS = 10;
+const MAX_PULSES = 6;
+function hideMesh(mesh) {
+    if (mesh !== null)
+        mesh.visible = false;
+}
+function BoltPool({ runtime, weaponId, weapon, }) {
+    const ctx = useGameContext();
+    const refs = useRef(new Array(MAX_BOLTS).fill(null));
+    useFrame(() => {
+        const run = runtime.run(ctx);
+        const now = ctx.time.now();
+        const bolts = run.bolts.filter((bolt) => bolt.weaponId === weaponId);
+        for (let i = 0; i < MAX_BOLTS; i += 1) {
+            const mesh = refs.current[i];
+            const bolt = bolts[i];
+            if (mesh === null)
+                continue;
+            if (bolt === undefined) {
+                hideMesh(mesh);
+                continue;
+            }
+            const t = Math.min(1, Math.max(0, (now - bolt.firedAt) / bolt.travelSeconds));
+            mesh.visible = true;
+            mesh.position.set(bolt.origin[0] + (bolt.target[0] - bolt.origin[0]) * t, bolt.origin[1] + 0.9, bolt.origin[2] + (bolt.target[2] - bolt.origin[2]) * t);
+        }
+    });
+    return (_jsx(_Fragment, { children: Array.from({ length: MAX_BOLTS }, (_, i) => (_jsxs("mesh", { ref: (mesh) => {
+                refs.current[i] = mesh;
+            }, visible: false, children: [_jsx("sphereGeometry", { args: [0.16, 8, 8] }), _jsx("meshStandardMaterial", { color: weapon.fxColor ?? "#8be9f0", emissive: weapon.fxEmissive ?? weapon.fxColor ?? "#8be9f0", emissiveIntensity: 1.6 })] }, i))) }));
+}
+function PulsePool({ runtime, weaponId, weapon, }) {
+    const ctx = useGameContext();
+    const refs = useRef(new Array(MAX_PULSES).fill(null));
+    useFrame(() => {
+        const run = runtime.run(ctx);
+        const now = ctx.time.now();
+        const pulses = run.pulses.filter((pulse) => pulse.weaponId === weaponId);
+        for (let i = 0; i < MAX_PULSES; i += 1) {
+            const mesh = refs.current[i];
+            const pulse = pulses[i];
+            if (mesh === null)
+                continue;
+            if (pulse === undefined) {
+                hideMesh(mesh);
+                continue;
+            }
+            const t = Math.min(1, Math.max(0, (now - pulse.firedAt) / pulse.durationSeconds));
+            const radius = Math.max(0.01, pulse.maxRadius * t);
+            mesh.visible = true;
+            mesh.position.set(pulse.at[0], pulse.at[1] + 0.05, pulse.at[2]);
+            mesh.scale.set(radius, radius, radius);
+            const material = mesh.material;
+            if (!Array.isArray(material))
+                material.opacity = 0.55 * (1 - t);
+        }
+    });
+    return (_jsx(_Fragment, { children: Array.from({ length: MAX_PULSES }, (_, i) => (_jsxs("mesh", { ref: (mesh) => {
+                refs.current[i] = mesh;
+            }, rotation: [-Math.PI / 2, 0, 0], visible: false, children: [_jsx("ringGeometry", { args: [0.85, 1, 48] }), _jsx("meshBasicMaterial", { color: weapon.fxColor ?? "#a566d9", transparent: true, opacity: 0.5 })] }, i))) }));
+}
+function OrbitPool({ runtime, weaponId, weapon, }) {
+    const ctx = useGameContext();
+    const maxBlades = Math.ceil(leveled(weapon.blades, weapon.maxLevel));
+    const groupRef = useRef(null);
+    const refs = useRef(new Array(maxBlades).fill(null));
+    useFrame(() => {
+        const run = runtime.run(ctx);
+        const player = ctx.scene.entity.get(ctx.player.userId);
+        if (player === null || run.phase !== "playing") {
+            if (groupRef.current !== null)
+                groupRef.current.visible = false;
+            return;
+        }
+        const level = run.weaponLevel(weaponId);
+        const blades = leveled(weapon.blades, level);
+        const radius = leveled(weapon.radius, level);
+        const angle = ctx.time.now() * weapon.angularSpeed;
+        if (groupRef.current !== null)
+            groupRef.current.visible = true;
+        for (let i = 0; i < maxBlades; i += 1) {
+            const mesh = refs.current[i];
+            if (mesh === null)
+                continue;
+            if (i >= blades) {
+                hideMesh(mesh);
+                continue;
+            }
+            const theta = angle + (i * Math.PI * 2) / blades;
+            mesh.visible = true;
+            mesh.position.set(player.position[0] + Math.cos(theta) * radius, player.position[1] + 0.55, player.position[2] + Math.sin(theta) * radius);
+        }
+    });
+    return (_jsx("group", { ref: groupRef, children: Array.from({ length: maxBlades }, (_, i) => (_jsxs("mesh", { ref: (mesh) => {
+                refs.current[i] = mesh;
+            }, visible: false, children: [_jsx("boxGeometry", { args: [0.32, 0.08, 0.14] }), _jsx("meshStandardMaterial", { color: weapon.fxColor ?? "#dfe9ea", emissive: weapon.fxEmissive ?? weapon.fxColor ?? "#dfe9ea", emissiveIntensity: 0.8 })] }, i))) }));
+}
+function CartridgeFxOverlay({ config, runtime }) {
+    return (_jsx("group", { children: Object.entries(config.weapons).map(([weaponId, weapon]) => {
+            if (weapon.kind === "projectile") {
+                return _jsx(BoltPool, { runtime: runtime, weaponId: weaponId, weapon: weapon }, weaponId);
+            }
+            if (weapon.kind === "pulse") {
+                return _jsx(PulsePool, { runtime: runtime, weaponId: weaponId, weapon: weapon }, weaponId);
+            }
+            if (weapon.kind === "orbit") {
+                return _jsx(OrbitPool, { runtime: runtime, weaponId: weaponId, weapon: weapon }, weaponId);
+            }
+            return null;
+        }) }));
+}
+export function cartridge(config) {
+    const problems = validateCartridge(config);
+    if (problems.length > 0) {
+        throw new Error(`cartridge "${config.name}": invalid spec:\n${problems.map((p) => `  - ${p}`).join("\n")}`);
+    }
+    const runtime = createCartridge(config);
+    return defineGame({
+        name: config.name,
+        assets: config.assets,
+        features: { leaderboard: config.rules.killLeaderboardStat !== undefined },
+        world: config.world,
+        physics: config.physics,
+        input: config.input ?? WASD_KEYBINDS,
+        save: config.save ?? "none",
+        content: runtime.content,
+        loop: runtime.loop,
+        GameUI: () => _jsx(CartridgeUI, { config: config, runtime: runtime }),
+        WorldOverlay: () => _jsx(CartridgeFxOverlay, { config: config, runtime: runtime }),
+        camera: config.camera,
+        entitySprites: config.entitySprites,
+        worldItem: config.worldItem,
+        settings: config.settings,
+    });
+}

package/dist/commandSink.d.ts

@@ -0,0 +1,20 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { LiveGameBackend } from "@jgengine/core/runtime/transport";
+/** Where a gameplay command goes when the shell dispatches it — run locally, or sent to the authoritative host. */
+export interface CommandSink {
+    run(name: string, input: unknown): void;
+}
+/** Runs commands on the local `ctx` — the default, client-authoritative path. */
+export declare function localCommandSink(ctx: GameContext): CommandSink;
+/** Sends commands to the authoritative host over the transport; the result replicates back through world sync. */
+export declare function remoteCommandSink(backend: Pick<LiveGameBackend, "transport">, serverId: string): CommandSink;
+/**
+ * The sink a server-authoritative shell should dispatch gameplay commands through: remote when the game opts into
+ * `authority: "server"` and a server is joined, local otherwise. Client-only UI commands (targeting, hotbar
+ * scroll) keep calling `ctx.game.commands.run` directly — only authoritative gameplay verbs route to the host.
+ */
+export declare function resolveCommandSink(ctx: GameContext, opts: {
+    serverAuthoritative: boolean;
+    backend: Pick<LiveGameBackend, "transport"> | null;
+    serverId: string | null;
+}): CommandSink;

package/dist/commandSink.js

@@ -0,0 +1,27 @@
+/** Runs commands on the local `ctx` — the default, client-authoritative path. */
+export function localCommandSink(ctx) {
+    return {
+        run(name, input) {
+            ctx.game.commands.run(name, input);
+        },
+    };
+}
+/** Sends commands to the authoritative host over the transport; the result replicates back through world sync. */
+export function remoteCommandSink(backend, serverId) {
+    return {
+        run(name, input) {
+            void backend.transport.runCommand({ serverId, command: name, input }).catch(() => undefined);
+        },
+    };
+}
+/**
+ * The sink a server-authoritative shell should dispatch gameplay commands through: remote when the game opts into
+ * `authority: "server"` and a server is joined, local otherwise. Client-only UI commands (targeting, hotbar
+ * scroll) keep calling `ctx.game.commands.run` directly — only authoritative gameplay verbs route to the host.
+ */
+export function resolveCommandSink(ctx, opts) {
+    if (opts.serverAuthoritative && opts.backend !== null && opts.serverId !== null) {
+        return remoteCommandSink(opts.backend, opts.serverId);
+    }
+    return localCommandSink(ctx);
+}

package/dist/defineGame.js

@@ -10,7 +10,7 @@ function worldBackdrop(feature) {
 }
 const emptyUi = () => null;
 export function defineGame(config) {
-    const { content, loop, GameUI, environment, camera, multiplayer, WorldOverlay, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, worldHealthBars, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, shadows, presentation, objectStyles, devtools, ...engineFields } = config;
+    const { content, loop, GameUI, environment, camera, multiplayer, WorldOverlay, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, presentation, objectStyles, devtools, ...engineFields } = config;
     const game = defineEngineGame({ ...engineFields, multiplayer: multiplayer ?? offline() });
     return {
         game,
@@ -19,6 +19,7 @@ export function defineGame(config) {
             onInit: loop?.onInit ?? noop,
             onNewPlayer: loop?.onNewPlayer ?? noop,
             onTick: loop?.onTick ?? noop,
+            onPlayerLeave: loop?.onPlayerLeave ?? noop,
         },
         GameUI: GameUI ?? emptyUi,
         environment: environment ??
@@ -34,6 +35,7 @@ export function defineGame(config) {
         prompts,
         pointer,
         touch,
+        orientation,
         worldHealthBars,
         audio,
         entitySounds,
@@ -43,6 +45,7 @@ export function defineGame(config) {
         movement,
         lighting,
         backdrop,
+        postProcessing,
         shadows,
         presentation,
         objectStyles,

package/dist/devtools/CollisionDebugWorld.d.ts

@@ -0,0 +1,5 @@
+/**
+ * World-space collision debugger. Performs zero scene scans and zero raycasts
+ * when every layer is off. Mount only when shell devtools are enabled.
+ */
+export declare function CollisionDebugWorld(): import("react").JSX.Element | null;