@jgengine/core 0.14.0 → 0.15.0

package/dist/economy/shopStock.js

@@ -0,0 +1,157 @@
+import { canAfford, charge, grant } from "./wallet.js";
+function assertPrice(price) {
+    if (typeof price.currency !== "string" || price.currency.length === 0) {
+        throw new TypeError(`price.currency must be a non-empty string, got ${String(price.currency)}`);
+    }
+    if (!Number.isFinite(price.amount) || price.amount < 0) {
+        throw new RangeError(`price.amount must be a non-negative finite number, got ${price.amount}`);
+    }
+}
+function assertQty(qty) {
+    if (qty === null)
+        return;
+    if (!Number.isInteger(qty) || qty < 0) {
+        throw new RangeError(`qty must be null or a non-negative integer, got ${qty}`);
+    }
+}
+/** Deep-copy an entry so live internal records are never handed out or retained by callers. */
+function cloneEntry(entry) {
+    const copy = {
+        id: entry.id,
+        kind: entry.kind,
+        price: { currency: entry.price.currency, amount: entry.price.amount },
+        qty: entry.qty,
+    };
+    if (entry.sellPrice !== undefined) {
+        copy.sellPrice = { currency: entry.sellPrice.currency, amount: entry.sellPrice.amount };
+    }
+    return copy;
+}
+function validateEntry(entry) {
+    if (typeof entry.id !== "string" || entry.id.length === 0) {
+        throw new TypeError(`entry.id must be a non-empty string, got ${String(entry.id)}`);
+    }
+    if (typeof entry.kind !== "string") {
+        throw new TypeError(`entry.kind must be a string, got ${String(entry.kind)}`);
+    }
+    assertPrice(entry.price);
+    assertQty(entry.qty);
+    if (entry.sellPrice !== undefined)
+        assertPrice(entry.sellPrice);
+}
+/**
+ * A serializable, observable vendor/shop stock. Each entry carries a game-owned free-string `kind`, a
+ * `price` in a free-string `currency`, a finite or unlimited (`qty: null`) count, and an optional
+ * `sellPrice` buy-back. All currency math is delegated to the existing pure `wallet` model — `buy`
+ * charges and `sell` grants a **caller-owned** {@link WalletState} (the shop never holds the wallet, it
+ * returns the new wallet for the caller to adopt), so the same stock composes with any wallet the game
+ * owns. Nothing here is genre-specific: `kind` and `currency` are free labels the game styles and the
+ * model never branches on. `restock`/`setPrice`/`add`/`remove` mutate the catalog, `subscribe` observes
+ * every change, and `snapshot`/`restore` round-trips the whole stock through a save.
+ *
+ * @capability shop-grid serializable vendor/shop stock with buy/sell over a caller-owned wallet — finite/unlimited qty, sell-back, restock/setPrice, snapshot/restore
+ */
+export function createShopStock(config = {}) {
+    // Insertion-ordered map of live records (Map preserves insertion order for list()/snapshot()).
+    const entries = new Map();
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function ingest(entry) {
+        validateEntry(entry);
+        if (entries.has(entry.id))
+            throw new Error(`duplicate shop entry id: ${entry.id}`);
+        entries.set(entry.id, cloneEntry(entry));
+    }
+    for (const entry of config.entries ?? [])
+        ingest(entry);
+    return {
+        buy(id, wallet) {
+            const entry = entries.get(id);
+            if (entry === undefined)
+                return { ok: false, reason: "unknown-item" };
+            if (entry.qty !== null && entry.qty <= 0)
+                return { ok: false, reason: "out-of-stock" };
+            let nextWallet = wallet;
+            if (entry.price.amount > 0) {
+                const result = charge(wallet, entry.price.currency, entry.price.amount);
+                if (result.status === "rejected")
+                    return { ok: false, reason: "insufficient-funds" };
+                nextWallet = result.state;
+            }
+            if (entry.qty !== null)
+                entry.qty -= 1;
+            notify();
+            return { ok: true, wallet: nextWallet, entry: cloneEntry(entry) };
+        },
+        sell(id, wallet) {
+            const entry = entries.get(id);
+            if (entry === undefined)
+                return { ok: false, reason: "unknown-item" };
+            if (entry.sellPrice === undefined)
+                return { ok: false, reason: "not-sellable" };
+            const nextWallet = entry.sellPrice.amount > 0 ? grant(wallet, entry.sellPrice.currency, entry.sellPrice.amount) : wallet;
+            if (entry.qty !== null)
+                entry.qty += 1;
+            notify();
+            return { ok: true, wallet: nextWallet, entry: cloneEntry(entry) };
+        },
+        canAfford(id, wallet) {
+            const entry = entries.get(id);
+            if (entry === undefined)
+                return false;
+            if (entry.qty !== null && entry.qty <= 0)
+                return false;
+            if (entry.price.amount <= 0)
+                return true;
+            return canAfford(wallet, { [entry.price.currency]: entry.price.amount });
+        },
+        restock(id, n) {
+            if (!Number.isInteger(n) || n < 0)
+                throw new RangeError(`restock count must be a non-negative integer, got ${n}`);
+            const entry = entries.get(id);
+            if (entry === undefined || entry.qty === null || n === 0)
+                return;
+            entry.qty += n;
+            notify();
+        },
+        setPrice(id, price) {
+            const entry = entries.get(id);
+            if (entry === undefined)
+                return;
+            assertPrice(price);
+            entry.price = { currency: price.currency, amount: price.amount };
+            notify();
+        },
+        add(entry) {
+            ingest(entry);
+            notify();
+        },
+        remove(id) {
+            if (entries.delete(id))
+                notify();
+        },
+        list() {
+            return Array.from(entries.values(), cloneEntry);
+        },
+        get(id) {
+            const entry = entries.get(id);
+            return entry === undefined ? null : cloneEntry(entry);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { entries: Array.from(entries.values(), cloneEntry) };
+        },
+        restore(snapshot) {
+            entries.clear();
+            for (const entry of snapshot.entries)
+                ingest(entry);
+            notify();
+        },
+    };
+}

package/dist/economy/wallet.d.ts

@@ -1,6 +1,11 @@
 export interface WalletState {
     balances: Readonly<Record<string, number>>;
 }
+/**
+ * Outcome of a {@link charge}/{@link chargeAll} attempt: `status: "ok"` carries the debited
+ * {@link WalletState}, while `status: "rejected"` leaves the wallet untouched and reports why
+ * (currently only `"insufficient-funds"`). Discriminate on `status` before reading `state`.
+ */
 export type ChargeResult = {
     status: "ok";
     state: WalletState;
@@ -36,5 +41,6 @@ export declare function grant(state: WalletState, currency: string, amount: numb
 export declare function charge(state: WalletState, currency: string, amount: number, options?: ChargeOptions): ChargeResult;
 /** True once `balance(state, currency)` has gone negative under an overdraft-enabled charge. */
 export declare function isOverdrawn(state: WalletState, currency: string): boolean;
+/** True when every currency in `costs` has at least that much balance (a pure, non-mutating check). */
 export declare function canAfford(state: WalletState, costs: Readonly<Record<string, number>>): boolean;
 export declare function chargeAll(state: WalletState, costs: Readonly<Record<string, number>>, options?: ChargeOptions): ChargeResult;

package/dist/economy/wallet.js

@@ -58,6 +58,7 @@ export function charge(state, currency, amount, options) {
 export function isOverdrawn(state, currency) {
     return balance(state, currency) < 0;
 }
+/** True when every currency in `costs` has at least that much balance (a pure, non-mutating check). */
 export function canAfford(state, costs) {
     return Object.entries(costs).every(([currency, amount]) => balance(state, currency) >= amount);
 }

package/dist/game/achievements.d.ts

@@ -0,0 +1,80 @@
+/** Definition of one achievement. Content-agnostic — the game supplies names, targets, and icons. */
+export interface AchievementDef {
+    id: string;
+    name: string;
+    description?: string;
+    /**
+     * Counter goal: the achievement unlocks when accumulated progress reaches it.
+     * Omit for a boolean achievement unlocked directly with `unlock(id)`.
+     */
+    target?: number;
+    /** Hide the name/description in UI until unlocked (a spoiler-guarded achievement). */
+    secret?: boolean;
+    /** Optional score weight (gamerscore-style), summed by {@link AchievementTracker.score}. */
+    points?: number;
+    category?: string;
+    /** Optional icon id / glyph the game renders; the engine never picks art. */
+    icon?: string;
+}
+/** A definition plus its live unlock/progress state — what UI renders. */
+export interface AchievementView extends AchievementDef {
+    unlocked: boolean;
+    /** Unlock time from the injected clock, or null while locked. */
+    unlockedAt: number | null;
+    /** Current counter value (0 for untouched or boolean achievements). */
+    progress: number;
+    /** `progress / target` in `[0, 1]`; 1 when unlocked or when there is no target. */
+    fraction: number;
+}
+/** Emitted the instant an achievement unlocks — wire to a toast, feed, or sound. */
+export interface AchievementUnlock {
+    id: string;
+    def: AchievementDef;
+    at: number;
+}
+/** Whole serializable state of a tracker — drop into a save blob. */
+export interface AchievementSnapshot {
+    /** Achievement id → unlock timestamp. */
+    unlocked: Record<string, number>;
+    /** Achievement id → counter progress. */
+    counters: Record<string, number>;
+}
+/** Live achievement state over a fixed definition set — drives progress, unlocks, score, and a UI view list. */
+export interface AchievementTracker {
+    /** Add `amount` (default 1) to a counter achievement; unlocks on reaching `target`. Returns the unlock if it just crossed, else null. */
+    progress(id: string, amount?: number): AchievementUnlock | null;
+    /** Set a counter achievement's absolute value; unlocks on reaching `target`. Returns the unlock if it just crossed, else null. */
+    setProgress(id: string, value: number): AchievementUnlock | null;
+    /** Unlock directly (boolean or counter). Returns the unlock, or null if unknown or already unlocked. */
+    unlock(id: string): AchievementUnlock | null;
+    isUnlocked(id: string): boolean;
+    get(id: string): AchievementView | null;
+    /** All achievements with live state, in definition order. Stable identity between changes (safe for `useSyncExternalStore`). */
+    list(): readonly AchievementView[];
+    unlocked(): readonly AchievementView[];
+    /** Total `points` across unlocked achievements. */
+    score(): number;
+    /** Fraction of achievements unlocked, `[0, 1]`. */
+    completion(): number;
+    subscribe(listener: () => void): () => void;
+    snapshot(): AchievementSnapshot;
+    restore(snapshot: AchievementSnapshot): void;
+}
+/** Options for {@link createAchievementTracker}. */
+export interface AchievementTrackerOptions {
+    defs: readonly AchievementDef[];
+    /** Injected clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Fires whenever an achievement unlocks — the seam for toasts, kill-feed lines, sounds, or telemetry. */
+    onUnlock?: (unlock: AchievementUnlock) => void;
+}
+/**
+ * Tracks achievement/trophy unlocks over caller-driven events — counter goals
+ * (`progress`/`setProgress`) and boolean flags (`unlock`) — with score,
+ * completion, an `onUnlock` seam, and serializable `snapshot`/`restore`. State
+ * is plain data; the view list keeps a stable identity between changes so React
+ * can read it through `useSyncExternalStore` without re-projecting every frame.
+ *
+ * @capability achievements track achievement/trophy unlocks over counter goals and boolean flags, with score, completion, an onUnlock seam, and serializable snapshot/restore
+ */
+export declare function createAchievementTracker(options: AchievementTrackerOptions): AchievementTracker;

package/dist/game/achievements.js

@@ -0,0 +1,124 @@
+/**
+ * Tracks achievement/trophy unlocks over caller-driven events — counter goals
+ * (`progress`/`setProgress`) and boolean flags (`unlock`) — with score,
+ * completion, an `onUnlock` seam, and serializable `snapshot`/`restore`. State
+ * is plain data; the view list keeps a stable identity between changes so React
+ * can read it through `useSyncExternalStore` without re-projecting every frame.
+ *
+ * @capability achievements track achievement/trophy unlocks over counter goals and boolean flags, with score, completion, an onUnlock seam, and serializable snapshot/restore
+ */
+export function createAchievementTracker(options) {
+    const now = options.now ?? Date.now;
+    const order = [];
+    const defs = new Map();
+    for (const def of options.defs) {
+        if (defs.has(def.id))
+            continue;
+        defs.set(def.id, def);
+        order.push(def.id);
+    }
+    const unlockedAt = new Map();
+    const counters = new Map();
+    const listeners = new Set();
+    let cache = null;
+    function notify() {
+        cache = null;
+        for (const listener of listeners)
+            listener();
+    }
+    function viewOf(id) {
+        const def = defs.get(id);
+        const at = unlockedAt.get(id) ?? null;
+        const progress = counters.get(id) ?? 0;
+        const fraction = at !== null ? 1 : def.target !== undefined && def.target > 0 ? Math.min(1, progress / def.target) : 0;
+        return { ...def, unlocked: at !== null, unlockedAt: at, progress, fraction };
+    }
+    function doUnlock(id) {
+        const at = now();
+        unlockedAt.set(id, at);
+        const def = defs.get(id);
+        if (def.target !== undefined)
+            counters.set(id, def.target);
+        const unlock = { id, def, at };
+        options.onUnlock?.(unlock);
+        return unlock;
+    }
+    function applyCounter(id, value) {
+        const def = defs.get(id);
+        if (def === undefined || def.target === undefined)
+            return null;
+        if (unlockedAt.has(id))
+            return null;
+        const clamped = Math.max(0, Math.min(def.target, value));
+        counters.set(id, clamped);
+        if (clamped >= def.target) {
+            const unlock = doUnlock(id);
+            notify();
+            return unlock;
+        }
+        notify();
+        return null;
+    }
+    const tracker = {
+        progress(id, amount = 1) {
+            return applyCounter(id, (counters.get(id) ?? 0) + amount);
+        },
+        setProgress(id, value) {
+            return applyCounter(id, value);
+        },
+        unlock(id) {
+            if (!defs.has(id) || unlockedAt.has(id))
+                return null;
+            const unlock = doUnlock(id);
+            notify();
+            return unlock;
+        },
+        isUnlocked(id) {
+            return unlockedAt.has(id);
+        },
+        get(id) {
+            return defs.has(id) ? viewOf(id) : null;
+        },
+        list() {
+            if (cache === null)
+                cache = order.map(viewOf);
+            return cache;
+        },
+        unlocked() {
+            return tracker.list().filter((view) => view.unlocked);
+        },
+        score() {
+            let total = 0;
+            for (const id of unlockedAt.keys())
+                total += defs.get(id)?.points ?? 0;
+            return total;
+        },
+        completion() {
+            return order.length === 0 ? 0 : unlockedAt.size / order.length;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return {
+                unlocked: Object.fromEntries(unlockedAt),
+                counters: Object.fromEntries(counters),
+            };
+        },
+        restore(snapshot) {
+            unlockedAt.clear();
+            counters.clear();
+            for (const [id, at] of Object.entries(snapshot.counters)) {
+                if (defs.has(id))
+                    counters.set(id, at);
+            }
+            for (const [id, at] of Object.entries(snapshot.unlocked)) {
+                if (defs.has(id))
+                    unlockedAt.set(id, at);
+            }
+            notify();
+        },
+    };
+    return tracker;
+}

package/dist/game/cameraConfig.d.ts

@@ -198,6 +198,13 @@ export interface ChaseCameraConfig {
         minSpeed?: number;
         response?: number;
     };
+    /**
+     * Exponential response (`1-exp(-response*dt)`) the chase yaw follows the target's facing with
+     * (#1370). The default (5) arcs the boom smoothly behind a body whose facing flips from a strafe
+     * or direction change instead of teleporting it to the far side; `Infinity` restores the legacy
+     * rigid follow (yaw exactly equals body facing every frame).
+     */
+    yawResponse?: number;
     /** Which view to mount. Default "chase". */
     view?: ChaseView;
     /** Local offset for cockpit/hood/rear seats (relative to the vehicle, +z forward). */

package/dist/game/codex.d.ts

@@ -0,0 +1,60 @@
+/** A codex/bestiary/lorebook entry the game defines. Discovery state is tracked separately. */
+export interface CodexEntryDef<TMeta = unknown> {
+    id: string;
+    name: string;
+    category?: string;
+    description?: string;
+    /** Longer lore for a detail pane. */
+    lore?: string;
+    /** Icon/image id or glyph the game renders; the engine never picks art. */
+    icon?: string;
+    /** Hide name/description/lore until discovered (a spoiler-guarded entry). */
+    secret?: boolean;
+    meta?: TMeta;
+}
+/** A definition plus its discovery state — what UI renders. */
+export interface CodexEntryView<TMeta = unknown> extends CodexEntryDef<TMeta> {
+    discovered: boolean;
+    /** Discovery time from the injected clock, or null. */
+    discoveredAt: number | null;
+}
+/** Serializable discovery state — a save blob. */
+export interface CodexSnapshot {
+    /** Entry id → discovery timestamp. */
+    discovered: Record<string, number>;
+}
+/** A codex/bestiary of defined entries with per-player discovery tracking. */
+export interface Codex<TMeta = unknown> {
+    /** Mark an entry discovered; returns the newly-discovered view, or null if unknown or already discovered. */
+    discover(id: string): CodexEntryView<TMeta> | null;
+    isDiscovered(id: string): boolean;
+    get(id: string): CodexEntryView<TMeta> | null;
+    /** All entries (optionally filtered to a category) with discovery state, in definition order. Stable identity between changes. */
+    list(category?: string): readonly CodexEntryView<TMeta>[];
+    categories(): readonly string[];
+    discoveredCount(): number;
+    total(): number;
+    /** Fraction discovered, `[0, 1]`. */
+    completion(): number;
+    subscribe(listener: () => void): () => void;
+    snapshot(): CodexSnapshot;
+    restore(snapshot: CodexSnapshot): void;
+}
+/** Options for {@link createCodex}. */
+export interface CodexOptions<TMeta = unknown> {
+    entries: readonly CodexEntryDef<TMeta>[];
+    /** Injected clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Fires when an entry is discovered for the first time — wire to a toast/notification. */
+    onDiscover?: (entry: CodexEntryView<TMeta>) => void;
+}
+/**
+ * A codex / bestiary / lorebook: a fixed set of defined entries plus per-player
+ * discovery tracking, with categories, secret masking, completion, an
+ * `onDiscover` seam, and serializable `snapshot`/`restore`. The view `list()`
+ * keeps a stable identity between changes so React reads it through
+ * `useSyncExternalStore` without re-projecting each frame.
+ *
+ * @capability codex codex/bestiary/lorebook of defined entries with discovery tracking, categories, secret masking, completion, an onDiscover seam, and serializable state
+ */
+export declare function createCodex<TMeta = unknown>(options: CodexOptions<TMeta>): Codex<TMeta>;

package/dist/game/codex.js

@@ -0,0 +1,89 @@
+/**
+ * A codex / bestiary / lorebook: a fixed set of defined entries plus per-player
+ * discovery tracking, with categories, secret masking, completion, an
+ * `onDiscover` seam, and serializable `snapshot`/`restore`. The view `list()`
+ * keeps a stable identity between changes so React reads it through
+ * `useSyncExternalStore` without re-projecting each frame.
+ *
+ * @capability codex codex/bestiary/lorebook of defined entries with discovery tracking, categories, secret masking, completion, an onDiscover seam, and serializable state
+ */
+export function createCodex(options) {
+    const now = options.now ?? Date.now;
+    const order = [];
+    const defs = new Map();
+    for (const def of options.entries) {
+        if (defs.has(def.id))
+            continue;
+        defs.set(def.id, def);
+        order.push(def.id);
+    }
+    const discoveredAt = new Map();
+    const listeners = new Set();
+    let cache = null;
+    function notify() {
+        cache = null;
+        for (const listener of listeners)
+            listener();
+    }
+    function viewOf(id) {
+        const def = defs.get(id);
+        const at = discoveredAt.get(id) ?? null;
+        return { ...def, discovered: at !== null, discoveredAt: at };
+    }
+    const codex = {
+        discover(id) {
+            if (!defs.has(id) || discoveredAt.has(id))
+                return null;
+            discoveredAt.set(id, now());
+            const view = viewOf(id);
+            options.onDiscover?.(view);
+            notify();
+            return view;
+        },
+        isDiscovered(id) {
+            return discoveredAt.has(id);
+        },
+        get(id) {
+            return defs.has(id) ? viewOf(id) : null;
+        },
+        list(category) {
+            if (cache === null)
+                cache = order.map(viewOf);
+            return category === undefined ? cache : cache.filter((view) => view.category === category);
+        },
+        categories() {
+            const seen = [];
+            for (const id of order) {
+                const category = defs.get(id).category;
+                if (category !== undefined && !seen.includes(category))
+                    seen.push(category);
+            }
+            return seen;
+        },
+        discoveredCount() {
+            return discoveredAt.size;
+        },
+        total() {
+            return order.length;
+        },
+        completion() {
+            return order.length === 0 ? 0 : discoveredAt.size / order.length;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { discovered: Object.fromEntries(discoveredAt) };
+        },
+        restore(snapshot) {
+            discoveredAt.clear();
+            for (const [id, at] of Object.entries(snapshot.discovered)) {
+                if (defs.has(id))
+                    discoveredAt.set(id, at);
+            }
+            notify();
+        },
+    };
+    return codex;
+}

package/dist/game/credits.d.ts

@@ -0,0 +1,36 @@
+/** One credited line — a person, a studio, an asset pack, a tool. */
+export interface CreditsEntry {
+    /** Who or what is credited. */
+    label: string;
+    /** Free-string qualifier shown beside the label — a role, a license, a pack title. */
+    detail?: string;
+    /** Where the work came from. Never fetched; the view decides whether to link it. */
+    href?: string;
+}
+/** A titled group of entries — "Design", "Music", "3D Assets". */
+export interface CreditsSection {
+    heading: string;
+    entries: readonly CreditsEntry[];
+}
+/** Everything a credits screen shows. `notice` is the closing line (a license summary, a thank-you). */
+export interface CreditsDocument {
+    title?: string;
+    sections: readonly CreditsSection[];
+    notice?: string;
+}
+/**
+ * Merges credit documents into one, concatenating same-heading sections in first-seen order and
+ * dropping exact duplicate entries. Use it to fold generated credits (asset packs, dependencies)
+ * into the game's hand-authored ones without curating the overlap by hand.
+ *
+ * @capability merge-credits fold generated and hand-authored credit documents into one, deduped by entry
+ */
+export declare function mergeCredits(...documents: readonly (CreditsDocument | null | undefined)[]): CreditsDocument;
+/**
+ * Groups entries into sections by a caller-supplied key — the shape most generated credits arrive
+ * in (a flat list of things used, grouped by license, provider, or role). Section order follows
+ * first appearance, so a stable input gives a stable screen.
+ *
+ * @capability group-credits turn a flat list of credited things into ordered credit sections
+ */
+export declare function groupCredits<T>(items: readonly T[], heading: (item: T) => string, entry: (item: T) => CreditsEntry): CreditsSection[];

package/dist/game/defineGame.d.ts

@@ -15,7 +15,7 @@ import type { TimeConfig } from "../time/simClock.js";
 import type { WorldFeature } from "../world/features.js";
 /** Tunes offline whole-world save (`defineGameDefinition({ persist })`). Offline games already autosave to `localStorage` by default — pass this only to tune it (or `persist: false` to opt out). Defaults: continuous `autosave` to `localStorage`, one slot, no version. */
 export interface PersistConfig {
-    /** `"autosave"` (default) writes on a debounce after any change; `"manual"` writes only on `ctx.game.save.checkpoint()` (save points / quest triggers). */
+    /** `"autosave"` (default) writes on a trailing timer while the world changes — at most once per `autosaveMs`, so a never-idle world (AI, physics, day/night) still persists; `"manual"` writes only on `ctx.game.save.checkpoint()` (save points / quest triggers). */
     mode?: RuntimeSaveMode;
     /** `"local"` (default) persists to `localStorage`; `"memory"` keeps saves in-session only (tests, "no persistence" mode). */
     storage?: "local" | "memory";
@@ -140,6 +140,20 @@ export interface LifecycleConfig<TState = unknown> {
         restart?: string;
     };
 }
+/**
+ * How a game declares its run-phase story to {@link defineGameDefinition}. Every game states this
+ * explicitly so the shell never has to guess — a silent game used to default to `"playing"`, which
+ * painted the touch dock over title/menu/results screens (#1337, Vice Isle #1329).
+ *
+ * - A {@link LifecycleConfig} — the game moves through menu/playing/paused/ended run states; the
+ *   runtime owns the command glue and phase sync.
+ * - `"always-live"` — an explicit, truthful declaration that the game has **no** menu/pause/end
+ *   screens and runs live from boot. Runtime behaviour is identical to declaring no lifecycle at all
+ *   (no phase sync, no start/restart commands), but the intent is now *stated*, not implied by
+ *   silence. Games that instead drive phases by hand call {@link setGamePhase} directly and leave
+ *   this unset.
+ */
+export type GameLifecycle<TState = unknown> = LifecycleConfig<TState> | "always-live";
 /** Fully-resolved game description produced by {@link defineGameDefinition} — assets, scene, and opted-in subsystems. */
 export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> {
     name: string;
@@ -177,7 +191,12 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     persist?: boolean | PersistConfig;
     ui?: unknown;
     loop?: GameLoop<GameContext>;
-    /** Declarative start/restart run lifecycle — see {@link LifecycleConfig}. Omitted games keep hand-rolling their own commands. */
+    /**
+     * Resolved run lifecycle — see {@link LifecycleConfig}. The config boundary also accepts the
+     * `"always-live"` sentinel ({@link GameLifecycle}); {@link defineGameDefinition} resolves that to
+     * `undefined` here, so a resolved definition only ever carries a real {@link LifecycleConfig} or
+     * nothing.
+     */
     lifecycle?: LifecycleConfig;
     /**
      * Host-side per-viewer replication policy — private-state and area-of-interest projection over the
@@ -188,8 +207,14 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     replication?: ReplicationPolicy;
 }
 /** Input to {@link defineGameDefinition} — a `GameDefinition` with `scene` derived and `assets` optional. */
-export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & {
+export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets" | "lifecycle"> & {
     assets?: AssetCatalog<TAssetRef>;
+    /**
+     * The game's run-phase story — a {@link LifecycleConfig} or the `"always-live"` sentinel. Every
+     * game must state one (or drive phases by hand via {@link setGamePhase}); `check-game-shape`
+     * enforces it. See {@link GameLifecycle}.
+     */
+    lifecycle?: GameLifecycle;
 };
 /**
  * Host-level constructor for a bare `GameDefinition`: fills in `scene` and default `assets`, validates

package/dist/game/defineGame.js

@@ -43,11 +43,16 @@ export function defineGameDefinition(config) {
     // A place world carries the laws of that place: its physics resolves over the game-level default,
     // so every consumer of definition.physics (movement, combat, shell) sees the active world's laws.
     const physics = resolveWorldPhysics(config.world, config.physics);
+    // `"always-live"` is an explicit "no lifecycle sync" declaration — resolve the sentinel to
+    // `undefined` so every downstream consumer only ever sees a real LifecycleConfig or nothing,
+    // exactly as before the sentinel existed. The statement was for the gate, not the runtime.
+    const lifecycle = config.lifecycle === "always-live" ? undefined : config.lifecycle;
     return {
         ...config,
         ...(physics === undefined ? {} : { physics }),
         features,
         loop,
+        lifecycle,
         scene: createEntityStore(),
         assets: config.assets ?? createAssetCatalog(),
     };