@jgengine/shell 0.10.0 → 0.11.0

package/dist/cartridge/spec.d.ts

@@ -0,0 +1,188 @@
+import type { SpawnDirectorConfig } from "@jgengine/core/ai/spawnDirector";
+import type { Curve } from "@jgengine/core/game/progression";
+import type { ActionCodesMap } from "@jgengine/core/input/actionBindings";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+export type Leveled = number | {
+    base: number;
+    perLevel: number;
+    min?: number;
+    max?: number;
+} | {
+    table: readonly number[];
+};
+export declare function leveled(value: Leveled, level: number): number;
+export interface CartridgePlayer {
+    kind: string;
+    health: number;
+    walkSpeed: number;
+    spawnAt?: readonly [number, number, number];
+}
+export interface CartridgeEnemy {
+    label: string;
+    health: number;
+    walkSpeed: number;
+    xp: number;
+    contact: {
+        damage: number;
+        intervalSeconds: number;
+    };
+    behavior?: "chase" | "none";
+}
+export interface CartridgeFlow {
+    start?: "auto" | "gate";
+    countdownSeconds?: number;
+    restart?: boolean;
+}
+export interface WeaponCommon {
+    label: string;
+    damage: Leveled;
+    cooldownMs: Leveled;
+    maxLevel: number;
+    fxColor?: string;
+    fxEmissive?: string;
+}
+export type CartridgeWeapon = (WeaponCommon & {
+    kind: "projectile";
+    range: number;
+    speed: number;
+}) | (WeaponCommon & {
+    kind: "orbit";
+    blades: Leveled;
+    radius: Leveled;
+    hitRadius: number;
+    angularSpeed: number;
+}) | (WeaponCommon & {
+    kind: "pulse";
+    radius: Leveled;
+    durationSeconds: number;
+}) | (WeaponCommon & {
+    kind: "custom";
+    fire(ctx: GameContext, run: CartridgeRun, args: WeaponFireArgs): void;
+});
+export interface WeaponFireArgs {
+    weaponId: string;
+    level: number;
+    damage: number;
+    playerId: string;
+    playerPosition: readonly [number, number, number];
+    enemyIds: readonly string[];
+    dt: number;
+}
+export type UpgradeEffect = {
+    kind: "weaponLevel";
+    weapon: string;
+} | {
+    kind: "statBonus";
+    stat: string;
+    amount: number;
+} | {
+    kind: "fieldAdd";
+    field: string;
+    amount: number;
+} | {
+    kind: "fieldMultiply";
+    field: string;
+    factor: number;
+} | {
+    kind: "custom";
+    apply(ctx: GameContext, run: CartridgeRun, stacks: number): void;
+};
+export interface CartridgeUpgrade {
+    id: string;
+    label: string;
+    weight: number;
+    maxStacks: number;
+    effect: UpgradeEffect;
+}
+export interface CartridgeProgression {
+    xp: Curve;
+    maxLevel: number;
+    draft: {
+        choices: number;
+        upgrades: readonly CartridgeUpgrade[];
+    };
+}
+export interface CartridgeSpawning {
+    director: SpawnDirectorConfig;
+    placement: {
+        kind: "ring";
+        radius: number;
+    } | {
+        kind: "custom";
+        position(ctx: GameContext, run: CartridgeRun): readonly [number, number, number];
+    };
+}
+export interface CartridgeXpGems {
+    collectRadius: number;
+    pullSpeed: number;
+    rarityThresholds: readonly (readonly [number, string])[];
+    defaultRarity: string;
+}
+export interface CartridgeRules {
+    win?: {
+        kind: "survive";
+        seconds: number;
+    } | {
+        kind: "custom";
+        check(ctx: GameContext, run: CartridgeRun): boolean;
+    };
+    lose?: {
+        kind: "playerDeath";
+    } | {
+        kind: "custom";
+        check(ctx: GameContext, run: CartridgeRun): boolean;
+    };
+    killLeaderboardStat?: string;
+}
+export interface CartridgeSpec {
+    seed?: string | number;
+    flow?: CartridgeFlow;
+    player: CartridgePlayer;
+    enemies: Record<string, CartridgeEnemy>;
+    combat: {
+        contactRadius: number;
+    };
+    spawning: CartridgeSpawning;
+    weapons: Record<string, CartridgeWeapon>;
+    progression: CartridgeProgression;
+    xpGems: CartridgeXpGems;
+    rules: CartridgeRules;
+    fields?: Record<string, number>;
+    input?: ActionCodesMap;
+    systems?: readonly ((ctx: GameContext, run: CartridgeRun, dt: number) => void)[];
+}
+export interface BoltFx {
+    id: number;
+    weaponId: string;
+    origin: readonly [number, number, number];
+    target: readonly [number, number, number];
+    firedAt: number;
+    travelSeconds: number;
+}
+export interface PulseFx {
+    id: number;
+    weaponId: string;
+    at: readonly [number, number, number];
+    firedAt: number;
+    durationSeconds: number;
+    maxRadius: number;
+}
+export type CartridgePhase = "start" | "countdown" | "playing" | "won" | "lost";
+export interface CartridgeRun {
+    phase: CartridgePhase;
+    playingSeconds: number;
+    countdownRemaining: number;
+    kills: number;
+    weaponLevel(weaponId: string): number;
+    field(name: string): number;
+    pendingOffers: readonly {
+        id: string;
+        label: string;
+    }[] | null;
+    bolts: readonly BoltFx[];
+    pulses: readonly PulseFx[];
+    subscribe(listener: () => void): () => void;
+}
+export declare const WASD_KEYBINDS: ActionCodesMap;
+export declare const XP_GEM_BASE_TYPE = "xp_gem";
+export declare const HIT_EFFECT = "hit";

package/dist/cartridge/spec.js

@@ -0,0 +1,19 @@
+export function leveled(value, level) {
+    if (typeof value === "number")
+        return value;
+    if ("table" in value) {
+        const index = Math.min(value.table.length - 1, Math.max(0, level - 1));
+        return value.table[index] ?? 0;
+    }
+    const raw = value.base + value.perLevel * (level - 1);
+    const floored = value.min === undefined ? raw : Math.max(value.min, raw);
+    return value.max === undefined ? floored : Math.min(value.max, floored);
+}
+export const WASD_KEYBINDS = {
+    moveForward: ["KeyW"],
+    moveBack: ["KeyS"],
+    moveLeft: ["KeyA"],
+    moveRight: ["KeyD"],
+};
+export const XP_GEM_BASE_TYPE = "xp_gem";
+export const HIT_EFFECT = "hit";

package/dist/cartridge/validate.d.ts

@@ -0,0 +1,2 @@
+import { type CartridgeSpec } from "./spec.js";
+export declare function validateCartridge(spec: CartridgeSpec): string[];

package/dist/cartridge/validate.js

@@ -0,0 +1,78 @@
+import { leveled } from "./spec.js";
+export function validateCartridge(spec) {
+    const problems = [];
+    const enemyIds = new Set(Object.keys(spec.enemies));
+    const weaponIds = new Set(Object.keys(spec.weapons));
+    if (spec.player.health <= 0)
+        problems.push(`player "${spec.player.kind}": health must be positive`);
+    if (spec.player.walkSpeed <= 0)
+        problems.push(`player "${spec.player.kind}": walkSpeed must be positive`);
+    if (enemyIds.has(spec.player.kind))
+        problems.push(`player kind "${spec.player.kind}" collides with an enemy id`);
+    if (spec.flow?.countdownSeconds !== undefined && spec.flow.countdownSeconds < 0) {
+        problems.push("flow.countdownSeconds must not be negative");
+    }
+    for (const [id, enemy] of Object.entries(spec.enemies)) {
+        if (enemy.health <= 0)
+            problems.push(`enemy "${id}": health must be positive`);
+        if (enemy.walkSpeed <= 0)
+            problems.push(`enemy "${id}": walkSpeed must be positive`);
+        if (enemy.xp <= 0)
+            problems.push(`enemy "${id}": xp must be positive`);
+        if (enemy.contact.damage <= 0)
+            problems.push(`enemy "${id}": contact.damage must be positive`);
+        if (enemy.contact.intervalSeconds <= 0)
+            problems.push(`enemy "${id}": contact.intervalSeconds must be positive`);
+    }
+    for (const wave of spec.spawning.director.waves) {
+        for (const entry of wave.entries) {
+            if (!enemyIds.has(entry.id))
+                problems.push(`spawning wave references unknown enemy "${entry.id}"`);
+        }
+    }
+    for (const [id, weapon] of Object.entries(spec.weapons)) {
+        for (let level = 1; level <= weapon.maxLevel; level += 1) {
+            if (leveled(weapon.damage, level) <= 0)
+                problems.push(`weapon "${id}": damage at level ${level} must be positive`);
+            if (leveled(weapon.cooldownMs, level) <= 0)
+                problems.push(`weapon "${id}": cooldownMs at level ${level} must be positive`);
+        }
+    }
+    const seenUpgrades = new Set();
+    for (const upgrade of spec.progression.draft.upgrades) {
+        if (seenUpgrades.has(upgrade.id))
+            problems.push(`upgrade "${upgrade.id}": duplicate id`);
+        seenUpgrades.add(upgrade.id);
+        if (upgrade.maxStacks <= 0)
+            problems.push(`upgrade "${upgrade.id}": maxStacks must be positive`);
+        const effect = upgrade.effect;
+        if (effect.kind === "weaponLevel") {
+            if (!weaponIds.has(effect.weapon)) {
+                problems.push(`upgrade "${upgrade.id}": references unknown weapon "${effect.weapon}"`);
+            }
+            else {
+                const weapon = spec.weapons[effect.weapon];
+                if (1 + upgrade.maxStacks > weapon.maxLevel) {
+                    problems.push(`upgrade "${upgrade.id}": maxStacks ${upgrade.maxStacks} exceeds weapon "${effect.weapon}" maxLevel ${weapon.maxLevel}`);
+                }
+            }
+        }
+        if ((effect.kind === "fieldAdd" || effect.kind === "fieldMultiply") && spec.fields?.[effect.field] === undefined) {
+            problems.push(`upgrade "${upgrade.id}": references undeclared field "${effect.field}"`);
+        }
+    }
+    if (spec.progression.draft.choices <= 0)
+        problems.push("progression.draft.choices must be positive");
+    if (spec.progression.maxLevel <= 1)
+        problems.push("progression.maxLevel must exceed 1");
+    const thresholds = spec.xpGems.rarityThresholds;
+    for (let i = 1; i < thresholds.length; i += 1) {
+        if (thresholds[i][0] >= thresholds[i - 1][0]) {
+            problems.push("xpGems.rarityThresholds must be sorted by descending value");
+        }
+    }
+    if (spec.rules.win?.kind === "survive" && spec.rules.win.seconds <= 0) {
+        problems.push("rules.win.seconds must be positive");
+    }
+    return problems;
+}

package/dist/cartridge.d.ts

@@ -1,7 +1,7 @@
 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 CartridgeSpec } from "./cartridge/spec.js";
 import { type GameConfig } from "./defineGame.js";
 import type { PlayableGame } from "./registry.js";
 export type CartridgePanelItem = {

package/dist/cartridge.js

@@ -1,12 +1,12 @@
 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 { createCartridge } from "./cartridge/runtime.js";
+import { WASD_KEYBINDS, leveled } from "./cartridge/spec.js";
+import { validateCartridge } from "./cartridge/validate.js";
 import { defineGame } from "./defineGame.js";
 function useTick(intervalMs) {
     const [, setTick] = useState(0);

package/dist/commandSink.d.ts

@@ -4,15 +4,20 @@ import type { LiveGameBackend } from "@jgengine/core/runtime/transport";
 export interface CommandSink {
     run(name: string, input: unknown): void;
 }
-/** Runs commands on the local `ctx` — the default, client-authoritative path. */
+/** Runs commands on the local `ctx` — the default, client-authoritative path.
+ * @internal
+ */
 export declare function localCommandSink(ctx: GameContext): CommandSink;
-/** Sends commands to the authoritative host over the transport; the result replicates back through world sync. */
+/** Sends commands to the authoritative host over the transport; the result replicates back through world sync.
+ * @internal
+ */
 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.
- */
+  * @internal
+  */
 export declare function resolveCommandSink(ctx: GameContext, opts: {
     serverAuthoritative: boolean;
     backend: Pick<LiveGameBackend, "transport"> | null;

package/dist/commandSink.js

@@ -1,4 +1,6 @@
-/** Runs commands on the local `ctx` — the default, client-authoritative path. */
+/** Runs commands on the local `ctx` — the default, client-authoritative path.
+ * @internal
+ */
 export function localCommandSink(ctx) {
     return {
         run(name, input) {
@@ -6,7 +8,9 @@ export function localCommandSink(ctx) {
         },
     };
 }
-/** Sends commands to the authoritative host over the transport; the result replicates back through world sync. */
+/** Sends commands to the authoritative host over the transport; the result replicates back through world sync.
+ * @internal
+ */
 export function remoteCommandSink(backend, serverId) {
     return {
         run(name, input) {
@@ -18,7 +22,8 @@ export function remoteCommandSink(backend, serverId) {
  * 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.
- */
+  * @internal
+  */
 export function resolveCommandSink(ctx, opts) {
     if (opts.serverAuthoritative && opts.backend !== null && opts.serverId !== null) {
         return remoteCommandSink(opts.backend, opts.serverId);

package/dist/defineGame.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { defineGame as defineEngineGame, } from "@jgengine/core/game/defineGame";
+import { syncLifecyclePhase } from "@jgengine/core/game/gamePhase";
 import { offline } from "@jgengine/core/runtime/adapter";
 import { EnvironmentScene } from "./environment.js";
 const noop = () => { };
@@ -10,22 +11,36 @@ 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, orientation, worldHealthBars, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, presentation, objectStyles, devtools, ...engineFields } = config;
-    const game = defineEngineGame({ ...engineFields, multiplayer: multiplayer ?? offline() });
+    const { content, loop, GameUI, environment, camera, multiplayer, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, nameplates, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
+    const game = defineEngineGame({
+        ...engineFields,
+        multiplayer: multiplayer ?? offline(),
+        loop,
+    });
+    function withPhaseSync(inner) {
+        return (ctx, ...args) => {
+            inner?.(ctx, ...args);
+            syncLifecyclePhase(ctx, game.lifecycle);
+        };
+    }
+    const composed = game.loop;
     return {
         game,
         content: content ?? {},
         loop: {
-            onInit: loop?.onInit ?? noop,
-            onNewPlayer: loop?.onNewPlayer ?? noop,
-            onTick: loop?.onTick ?? noop,
-            onPlayerLeave: loop?.onPlayerLeave ?? noop,
+            onInit: withPhaseSync(composed?.onInit),
+            onNewPlayer: withPhaseSync(composed?.onNewPlayer),
+            onTick: withPhaseSync(composed?.onTick),
+            onPlayerLeave: composed?.onPlayerLeave ?? noop,
+            onReset: composed?.onReset?.bind(composed) ?? noop,
+            onDispose: composed?.onDispose?.bind(composed) ?? noop,
         },
         GameUI: GameUI ?? emptyUi,
         environment: environment ??
             (game.world?.kind === "environment" ? worldBackdrop(game.world) : undefined),
         camera: camera ?? { perspective: "third" },
         WorldOverlay,
+        viewmodel,
         renderEntity,
         renderObject,
         entitySprites,
@@ -37,6 +52,7 @@ export function defineGame(config) {
         touch,
         orientation,
         worldHealthBars,
+        nameplates,
         audio,
         entitySounds,
         objectSounds,
@@ -50,5 +66,8 @@ export function defineGame(config) {
         presentation,
         objectStyles,
         devtools,
+        capture,
+        platforms,
+        hudFit,
     };
 }

package/dist/devtools/ColPanel.d.ts

@@ -0,0 +1 @@
+export declare function ColPanel(): import("react").JSX.Element;

package/dist/devtools/ColPanel.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+import { COLLISION_DEBUG_LAYERS, collisionDebug } from "./collisionDebug.js";
+const LAYER_LABELS = {
+    hitboxes: "Damage hitboxes",
+    bodies: "Physical bodies",
+    projectiles: "Projectile paths",
+    muzzles: "Muzzle / shot origins",
+    aimLaser: "Aim laser (authoritative)",
+};
+export function ColPanel() {
+    const state = useSyncExternalStore(collisionDebug.subscribe, () => collisionDebug.getState(), () => collisionDebug.getState());
+    return (_jsxs("div", { className: "space-y-2", children: [_jsx("div", { className: "text-[10px] text-neutral-500", children: "F2+D world collision debugger \u00B7 layers stay on when panel closes \u00B7 zero cost when all off" }), _jsxs("div", { className: "flex gap-1", children: [_jsx("button", { type: "button", className: "rounded-md bg-white/[0.04] px-2 py-0.5 text-neutral-300 ring-1 ring-inset ring-white/[0.08] transition-colors hover:bg-white/10", onClick: () => collisionDebug.setAllLayers(true), children: "All on" }), _jsx("button", { type: "button", className: "rounded-md bg-white/[0.04] px-2 py-0.5 text-neutral-300 ring-1 ring-inset ring-white/[0.08] transition-colors hover:bg-white/10", onClick: () => collisionDebug.setAllLayers(false), children: "All off" })] }), _jsx("div", { className: "space-y-1", children: COLLISION_DEBUG_LAYERS.map((layer) => (_jsxs("label", { className: "flex cursor-pointer items-center gap-2 text-neutral-200", children: [_jsx("input", { type: "checkbox", checked: state.layers[layer], onChange: (event) => collisionDebug.setLayer(layer, event.target.checked) }), _jsx("span", { children: LAYER_LABELS[layer] })] }, layer))) }), _jsx("div", { className: "border-t border-neutral-800 pt-1.5 font-mono text-[9px] text-neutral-500", children: "hitbox pink \u00B7 body cyan \u00B7 muzzle red \u00B7 laser lime \u00B7 X damage \u00B7 \u25CB solid \u00B7 \u00B7 miss" })] }));
+}

package/dist/devtools/DevtoolsOverlay.d.ts

@@ -1,11 +1,13 @@
-import { type DevtoolsOverrides, type DevtoolsSnapshot } from "@jgengine/core/devtools/devtools";
+import { type DevtoolsSnapshot } from "@jgengine/core/devtools/devtools";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import type { ShellMultiplayer } from "../multiplayer.js";
 import type { PlayableGame } from "../registry.js";
-export declare function persistDevtoolsOverrides(gameName: string): DevtoolsOverrides;
-export declare function applyStoredDevtoolsOverrides(gameName: string): void;
+export { applyStoredDevtoolsOverrides, persistDevtoolsOverrides } from "./devtoolsOverrides.js";
+/** @internal */
 export declare function withDevtoolsLatency(multiplayer: ShellMultiplayer): ShellMultiplayer;
+/** @internal */
 export declare function DevtoolsRendererProbe(): null;
+/** @internal */
 export declare function buildLeanReport(playable: PlayableGame): {
     game: string;
     at: number;
@@ -67,9 +69,11 @@ export declare function buildLeanReport(playable: PlayableGame): {
     }[] | undefined;
     discoveredCount: number;
 };
+/** @internal */
 export declare function buildFullReport(playable: PlayableGame): DevtoolsSnapshot & {
     game: string;
 };
+/** @internal */
 export declare function DevtoolsOverlay({ open, ctx, playable, multiplayer, }: {
     open: boolean;
     ctx: GameContext;