@jgengine/core 0.9.0 → 0.11.0

package/dist/game/events.d.ts

@@ -1,18 +1,8 @@
+import type { DeathReason } from "../combat/deathReason.js";
 import type { TelegraphShape } from "../combat/telegraph.js";
 import type { CameraShake } from "../combat/hitReaction.js";
-export type DeathReason = {
-    kind: "player_kill";
-    killerUserId: string;
-    via?: {
-        item?: string;
-    };
-} | {
-    kind: "environment";
-    source: string;
-} | {
-    kind: "self";
-    source: string;
-};
+import type { CombatVfxInstanceEvent } from "./vfxInstance.js";
+export type { DeathReason };
 export interface EntityDiedEvent {
     instanceId: string;
     catalogId: string;
@@ -22,6 +12,11 @@ export interface EntityDiedEvent {
     position: [number, number, number];
     serverId?: string;
 }
+/** Request that an entity's rig play a one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an "attack" swing); the shell resolves the clip and plays it once over the locomotion state. */
+export interface EntityAnimationEvent {
+    instanceId: string;
+    event: string;
+}
 export interface LootGrantedEvent {
     userId: string;
     drops: {
@@ -101,6 +96,29 @@ export interface EntityFloatTextEvent {
     crit?: boolean;
     scale?: number;
 }
+/** The visual archetype of a spell/ability effect burst: a traveling bolt, a connecting beam, an expanding ground nova, a soft aura glow, or a scattering impact spark. */
+export type VfxKind = "projectile" | "beam" | "nova" | "glow" | "spark";
+/** A transient sprite-particle effect the shell renders once and expires — one burst of `kind`, tinted `color`, anchored at `from` (and `to` for travel/beam effects). */
+export interface CombatVfxEvent {
+    id: number;
+    kind: VfxKind;
+    color: number;
+    from: [number, number, number];
+    to?: [number, number, number];
+    radius?: number;
+    durationMs: number;
+}
+/**
+ * An endpoint of a retained VFX instance: either an entity instance id (a renderer resolves and follows its live
+ * pose each frame) or a fixed `[x, y, z]` world point. Kept serializable so the effect replicates as plain data.
+ */
+export type VfxRef = string | readonly [number, number, number];
+/**
+ * The archetype of a retained (long-lived, updatable) VFX effect — an open string, not a closed union, so a
+ * renderer registers new kinds (beam, tether, zone, target line, looping emitter) without a central branch.
+ * `"beam"` is the first shipped retained renderer.
+ */
+export type RetainedVfxKind = string;
 export interface CombatTelegraphEvent {
     id: number;
     shape: TelegraphShape;
@@ -118,6 +136,8 @@ export interface CombatHitReactionEvent {
     position: [number, number, number];
     hitstopMs: number;
     shake?: CameraShake;
+    /** Trauma (0..1) for a trauma² shake channel — set when the reaction resolved from `trauma` instead of `shake`. */
+    trauma?: number;
 }
 export interface ProjectileSettledEvent {
     from: string;
@@ -164,10 +184,19 @@ export interface AudioPlayEvent {
     sound: string;
     at?: readonly [number, number, number];
 }
+/** Request that the shell's audio engine resume its (browser-gesture-suspended) context; carries no payload. */
+export type AudioResumeEvent = Record<string, never>;
+/** Crossfade the procedural soundtrack to `theme` (null fades out), optionally transposing the incoming theme by `transpose` semitones. */
+export interface AudioMusicEvent {
+    theme: string | null;
+    transpose?: number;
+}
 export interface GameEventMap {
     "entity.died": EntityDiedEvent;
     "entity.floatText": EntityFloatTextEvent;
     "combat.telegraph": CombatTelegraphEvent;
+    "combat.vfx": CombatVfxEvent;
+    "combat.vfxInstance": CombatVfxInstanceEvent;
     "combat.telegraphCancelled": CombatTelegraphCancelledEvent;
     "combat.hitReaction": CombatHitReactionEvent;
     "loot.granted": LootGrantedEvent;
@@ -190,6 +219,9 @@ export interface GameEventMap {
     "possession.swapped": PossessionSwappedEvent;
     "form.changed": FormChangedEvent;
     "audio.play": AudioPlayEvent;
+    "audio.music": AudioMusicEvent;
+    "audio.resume": AudioResumeEvent;
+    "entity.animation": EntityAnimationEvent;
 }
 export type GameEventHandler<TPayload> = (payload: TPayload) => void;
 export interface GameEvents<TMap extends GameEventMap = GameEventMap> {
@@ -197,4 +229,9 @@ export interface GameEvents<TMap extends GameEventMap = GameEventMap> {
     subscribe<TName extends keyof TMap>(name: TName, handler: GameEventHandler<TMap[TName]>): () => void;
     emit<TName extends keyof TMap>(name: TName, payload: TMap[TName]): void;
 }
+/**
+ * A typed publish/subscribe bus for gameplay events that systems and HUDs subscribe to.
+ *
+ * @capability event-bus typed publish/subscribe bus for gameplay events
+ */
 export declare function createGameEvents<TMap extends GameEventMap = GameEventMap>(): GameEvents<TMap>;

package/dist/game/events.js

@@ -1,3 +1,8 @@
+/**
+ * A typed publish/subscribe bus for gameplay events that systems and HUDs subscribe to.
+ *
+ * @capability event-bus typed publish/subscribe bus for gameplay events
+ */
 export function createGameEvents() {
     const listeners = new Map();
     function on(name, handler) {

package/dist/game/feed.d.ts

@@ -3,9 +3,37 @@ export interface FeedEntry<T = unknown> {
     at: number;
     data: T;
 }
+/** Any feed entry carrying a game-time (or wall-clock) `at` stamp for age-based pruning. */
+export interface TimedFeedEntry {
+    at: number;
+}
+/** Bounds for {@link appendFeed} / {@link pruneFeed}: newest-`limit` cap and/or `ttl` age window. */
+export interface FeedWindow {
+    /** Keep only the newest `limit` entries. Omit for no count cap. */
+    limit?: number;
+    /** Drop entries older than `ttl` game-seconds before the newest `at`. Omit for no age cap. */
+    ttl?: number;
+}
 export interface GameFeedOptions {
     limit?: number;
 }
+/**
+ * Append `entry` to a flat, serializable feed list, then bound it by age (`ttl`, relative to the
+ * appended entry's `at`) and/or count (`limit`, newest kept). Works on the game's own flat entry
+ * shape — anything with an `at` stamp — so `{ id, text, tone, at }`-style notice lists and event
+ * logs drop into serialized state with no `{ at, data }` envelope. Returns a new array.
+ *
+ * @capability notice-feed serializable tone-tagged notice/event feed bounded by count and age (toasts, life events, killfeed)
+ */
+export declare function appendFeed<T extends TimedFeedEntry>(list: readonly T[], entry: T, options?: FeedWindow): T[];
+/**
+ * Drop feed entries older than `ttl` game-seconds before `now`. Returns the same array reference
+ * when nothing expired, so equality checks skip a redundant state write. The tick-time counterpart
+ * to {@link appendFeed}'s age bound.
+ *
+ * @capability notice-feed serializable tone-tagged notice/event feed bounded by count and age (toasts, life events, killfeed)
+ */
+export declare function pruneFeed<T extends TimedFeedEntry>(list: readonly T[], now: number, ttl: number): T[];
 export declare function appendFeedEntry<T>(buffer: readonly FeedEntry<T>[], entry: FeedEntry<T>, limit: number): FeedEntry<T>[];
 export declare function recentFeedEntries<T>(buffer: readonly FeedEntry<T>[], limit?: number): FeedEntry<T>[];
 export interface GameFeed {
@@ -18,4 +46,9 @@ export interface GameFeed {
     snapshot(): Record<string, FeedEntry[]>;
     hydrate(data: Record<string, FeedEntry[]>): void;
 }
+/**
+ * A rolling per-action feed of recent gameplay events, bindable to the event bus — the HUD ticker and killfeed history.
+ *
+ * @capability event-feed a rolling feed of recent gameplay events for a HUD ticker or killfeed
+ */
 export declare function createGameFeed(options?: GameFeedOptions): GameFeed;

package/dist/game/feed.js

@@ -1,11 +1,44 @@
+/**
+ * Append `entry` to a flat, serializable feed list, then bound it by age (`ttl`, relative to the
+ * appended entry's `at`) and/or count (`limit`, newest kept). Works on the game's own flat entry
+ * shape — anything with an `at` stamp — so `{ id, text, tone, at }`-style notice lists and event
+ * logs drop into serialized state with no `{ at, data }` envelope. Returns a new array.
+ *
+ * @capability notice-feed serializable tone-tagged notice/event feed bounded by count and age (toasts, life events, killfeed)
+ */
+export function appendFeed(list, entry, options) {
+    let next = [...list, entry];
+    if (options?.ttl !== undefined) {
+        const cutoff = entry.at - options.ttl;
+        next = next.filter((item) => item.at > cutoff);
+    }
+    const limit = options?.limit;
+    return limit !== undefined && next.length > limit ? next.slice(next.length - limit) : next;
+}
+/**
+ * Drop feed entries older than `ttl` game-seconds before `now`. Returns the same array reference
+ * when nothing expired, so equality checks skip a redundant state write. The tick-time counterpart
+ * to {@link appendFeed}'s age bound.
+ *
+ * @capability notice-feed serializable tone-tagged notice/event feed bounded by count and age (toasts, life events, killfeed)
+ */
+export function pruneFeed(list, now, ttl) {
+    const cutoff = now - ttl;
+    const kept = list.filter((item) => item.at > cutoff);
+    return kept.length === list.length ? list : kept;
+}
 export function appendFeedEntry(buffer, entry, limit) {
-    const next = [...buffer, entry];
-    return next.length > limit ? next.slice(next.length - limit) : next;
+    return appendFeed(buffer, entry, { limit });
 }
 export function recentFeedEntries(buffer, limit) {
     const count = limit ?? buffer.length;
     return buffer.slice(Math.max(0, buffer.length - count));
 }
+/**
+ * A rolling per-action feed of recent gameplay events, bindable to the event bus — the HUD ticker and killfeed history.
+ *
+ * @capability event-feed a rolling feed of recent gameplay events for a HUD ticker or killfeed
+ */
 export function createGameFeed(options) {
     const limit = options?.limit ?? 20;
     const buffers = new Map();

package/dist/game/gamePhase.d.ts

@@ -1,4 +1,5 @@
 import type { GameContext } from "../runtime/gameContext.js";
+import type { LifecycleConfig } from "./defineGame.js";
 /**
  * Canonical run phase every game moves through. `menu` (title/main menu),
  * `playing` (live), `paused` (mid-run pause), `ended` (win/lose/results).
@@ -18,3 +19,13 @@ export declare function setGamePhase(ctx: GameContext, phase: GamePhase): void;
 /** Current phase; defaults to `playing` when unset so always-live games need no wiring. */
 export declare function gamePhase(ctx: GameContext): GamePhase;
 export declare function isPlaying(ctx: GameContext): boolean;
+/**
+ * Derive the canonical phase from a game's own run state via its {@link LifecycleConfig.phaseOf} and
+ * publish it when it changed — the runtime calls this after every loop hook so a game never hand-writes
+ * a per-tick `setGamePhase(ctx, state.phase === … ? … : …)` ternary or its own previous-phase diff. The
+ * guard makes it idempotent: the phase store is only rewritten (and touch controls re-gated) on an actual
+ * transition, so a busy `onTick` costs one `phaseOf` read, not a store write per frame.
+ *
+ * @internal
+ */
+export declare function syncLifecyclePhase(ctx: GameContext, lifecycle: LifecycleConfig | undefined): void;

package/dist/game/gamePhase.js

@@ -19,3 +19,19 @@ export function gamePhase(ctx) {
 export function isPlaying(ctx) {
     return gamePhase(ctx) === "playing";
 }
+/**
+ * Derive the canonical phase from a game's own run state via its {@link LifecycleConfig.phaseOf} and
+ * publish it when it changed — the runtime calls this after every loop hook so a game never hand-writes
+ * a per-tick `setGamePhase(ctx, state.phase === … ? … : …)` ternary or its own previous-phase diff. The
+ * guard makes it idempotent: the phase store is only rewritten (and touch controls re-gated) on an actual
+ * transition, so a busy `onTick` costs one `phaseOf` read, not a store write per frame.
+ *
+ * @internal
+ */
+export function syncLifecyclePhase(ctx, lifecycle) {
+    if (lifecycle === undefined)
+        return;
+    const desired = lifecycle.phaseOf(lifecycle.store.read(ctx));
+    if (gamePhase(ctx) !== desired)
+        setGamePhase(ctx, desired);
+}

package/dist/game/keyValueStore.d.ts

@@ -0,0 +1,25 @@
+/** Structural, DOM-free storage backend: the browser `localStorage` satisfies it, as does a test stub or `null`. The one storage seam core primitives target so persistence code never needs the DOM `Storage` lib. */
+export interface KeyValueStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** The ambient `localStorage` as a {@link KeyValueStorage} when one exists (browser), otherwise `null` (server/tests) — never references the DOM `Storage` type, so it is safe in core. */
+export declare function defaultKeyValueStorage(): KeyValueStorage | null;
+/** A single persisted, mutable cell: read the current value, overwrite it, or read-modify-write with {@link KeyValueStore.update}. Unlike a record book it has no monotonic guard — the value goes wherever you set it. */
+export interface KeyValueStore<T> {
+    get(): T;
+    set(value: T): void;
+    update(mutate: (previous: T) => T): T;
+    clear(): void;
+}
+/** Config for {@link createKeyValueStore}: the storage `key`, the `initial` value used before anything is saved, an optional `storage` backend (defaults to `localStorage`, pass `null` for memory-only), and optional custom `serialize`/`deserialize` (default JSON). */
+export interface KeyValueStoreConfig<T> {
+    readonly key: string;
+    readonly initial: T;
+    readonly storage?: KeyValueStorage | null;
+    readonly serialize?: (value: T) => string;
+    readonly deserialize?: (raw: string) => T;
+}
+/** A lightweight mutable local save cell for single-player state (a credit bank, a settings blob, level progress) — the read-modify-write counterpart to the monotonic `recordBook`. Persists through a {@link KeyValueStorage} (browser `localStorage` by default); corrupt or unavailable storage degrades to in-memory and never throws into a game tick. */
+export declare function createKeyValueStore<T>(config: KeyValueStoreConfig<T>): KeyValueStore<T>;

package/dist/game/keyValueStore.js

@@ -0,0 +1,61 @@
+/** The ambient `localStorage` as a {@link KeyValueStorage} when one exists (browser), otherwise `null` (server/tests) — never references the DOM `Storage` type, so it is safe in core. */
+export function defaultKeyValueStorage() {
+    try {
+        if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+            return globalThis.localStorage ?? null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/** A lightweight mutable local save cell for single-player state (a credit bank, a settings blob, level progress) — the read-modify-write counterpart to the monotonic `recordBook`. Persists through a {@link KeyValueStorage} (browser `localStorage` by default); corrupt or unavailable storage degrades to in-memory and never throws into a game tick. */
+export function createKeyValueStore(config) {
+    const storage = config.storage === undefined ? defaultKeyValueStorage() : config.storage;
+    const serialize = config.serialize ?? ((value) => JSON.stringify(value));
+    const deserialize = config.deserialize ?? ((raw) => JSON.parse(raw));
+    const read = () => {
+        if (storage === null)
+            return config.initial;
+        try {
+            const raw = storage.getItem(config.key);
+            return raw === null ? config.initial : deserialize(raw);
+        }
+        catch {
+            return config.initial;
+        }
+    };
+    let current = read();
+    const write = (value) => {
+        current = value;
+        if (storage === null)
+            return;
+        try {
+            storage.setItem(config.key, serialize(value));
+        }
+        catch {
+            // storage rejected the write; keep the value in memory for this session
+        }
+    };
+    return {
+        get: () => current,
+        set: (value) => write(value),
+        update: (mutate) => {
+            const next = mutate(current);
+            write(next);
+            return next;
+        },
+        clear: () => {
+            current = config.initial;
+            if (storage === null)
+                return;
+            try {
+                storage.removeItem(config.key);
+            }
+            catch {
+                // ignore removal failure; in-memory value already reset
+            }
+        },
+    };
+}

package/dist/game/leaderboard.d.ts

@@ -41,6 +41,11 @@ export interface Leaderboard {
     snapshot(): LeaderboardRow[];
     hydrate(rows: LeaderboardRow[]): void;
 }
+/**
+ * Ranked score tracking across global, server, and per-profile scopes, with top-N queries and per-profile lookups.
+ *
+ * @capability leaderboard ranked score tracking across global, server, and per-profile scopes
+ */
 export declare function createLeaderboard(sink?: {
     onIncrement?(row: LeaderboardRow): void;
 }): Leaderboard;

package/dist/game/leaderboard.js

@@ -11,6 +11,11 @@ function trackKey(stat, scope) {
 function rowKey(stat, scope, serverId, userId) {
     return `${scope}:${stat}:${serverId ?? ""}:${userId}`;
 }
+/**
+ * Ranked score tracking across global, server, and per-profile scopes, with top-N queries and per-profile lookups.
+ *
+ * @capability leaderboard ranked score tracking across global, server, and per-profile scopes
+ */
 export function createLeaderboard(sink) {
     const trackedPairs = new Map();
     const rows = new Map();

package/dist/game/levelSequence.d.ts

@@ -1,11 +1,23 @@
+import { type KeyValueStorage } from "./keyValueStore.js";
 export interface LevelDescriptor<TLevelConfig> {
     id: string;
     config: TLevelConfig;
 }
+/** A level's star rating, 0 (cleared, no stars) to 3. */
+export type LevelStars = 0 | 1 | 2 | 3;
+/** Persisted per-level outcome: whether it has ever been cleared and the best star rating achieved. */
+export interface LevelRecord {
+    cleared: boolean;
+    stars: LevelStars;
+}
 export interface LevelSequenceConfig<TLevelConfig> {
     levels: readonly LevelDescriptor<TLevelConfig>[];
     /** Extra attempts granted after the first per level. Defaults to 0 (a single attempt, no retries). */
     retriesPerLevel?: number;
+    /** Persistence key for per-level completion/stars. Omit to keep records in-memory only. */
+    key?: string;
+    /** Storage backend for the records (browser `localStorage` by default when `key` is set); pass `null` for memory-only. */
+    storage?: KeyValueStorage | null;
 }
 export type LevelSequenceStatus = "idle" | "playing" | "cleared" | "failed" | "complete";
 export interface CurrentLevel<TLevelConfig> {
@@ -24,15 +36,25 @@ export interface LevelSequence<TLevelConfig> {
     status(): LevelSequenceStatus;
     /** Enters level 0. A no-op on an empty level list, which leaves `status()` at "idle" forever. */
     start(): void;
-    /** Marks the current level cleared; call `advance()` to move to the next one. */
-    clear(): void;
+    /** Marks the current level cleared, recording its best star rating; call `advance()` to move to the next one. */
+    clear(stars?: LevelStars): void;
     /** Consumes an attempt on the current level. Returns "retry" while attempts remain, else "failed". */
     fail(): "retry" | "failed";
     /** Restarts the current level after a "retry"-eligible failure. Returns false if there was nothing to retry. */
     retry(): boolean;
     /** Moves past a cleared level, or to "complete" if it was the last one. Returns false unless status is "cleared". */
     advance(): boolean;
+    /** Jumps directly to an unlocked level and starts it. Returns false for an unknown or still-locked level. */
+    select(level: string): boolean;
+    /** Whether a level can be entered: the first level always, later ones once the preceding level has a cleared record. */
+    isUnlocked(level: string): boolean;
+    /** The persisted record for a level, or `null` if it has never been cleared. */
+    record(level: string): LevelRecord | null;
+    /** A snapshot of every persisted level record, keyed by level id. */
+    records(): Readonly<Record<string, LevelRecord>>;
     reset(): void;
+    /** Wipes all persisted completion/star records (and the frontier), returning to a fresh campaign. */
+    clearRecords(): void;
     progress(): LevelSequenceProgress;
 }
 /**

package/dist/game/levelSequence.js

@@ -1,3 +1,4 @@
+import { createKeyValueStore } from "./keyValueStore.js";
 /**
  * A pure, deterministic level campaign: an ordered list of levels, each with its own opaque config, played
  * through a `start` → (`clear` → `advance`)* → `complete` happy path, with `fail`/`retry` handling per-level
@@ -7,10 +8,32 @@
 export function createLevelSequence(config) {
     const levels = config.levels;
     const maxAttempts = 1 + Math.max(0, Math.floor(config.retriesPerLevel ?? 0));
+    const store = config.key === undefined
+        ? null
+        : createKeyValueStore({
+            key: config.key,
+            initial: {},
+            storage: config.storage,
+        });
     let index = 0;
     let attempt = 1;
     let status = "idle";
     const clearedIds = [];
+    const levelRecords = store === null ? {} : { ...store.get() };
+    function persistRecords() {
+        store?.set({ ...levelRecords });
+    }
+    function indexOfLevel(id) {
+        return levels.findIndex((level) => level.id === id);
+    }
+    function isUnlocked(id) {
+        const idx = indexOfLevel(id);
+        if (idx < 0)
+            return false;
+        if (idx === 0)
+            return true;
+        return levelRecords[levels[idx - 1].id]?.cleared === true;
+    }
     function current() {
         if (status === "idle" || status === "complete")
             return null;
@@ -30,12 +53,38 @@ export function createLevelSequence(config) {
             clearedIds.length = 0;
             status = "playing";
         },
-        clear() {
+        clear(stars) {
             if (status !== "playing" || current() === null)
                 return;
-            clearedIds.push(levels[index].id);
+            const id = levels[index].id;
+            clearedIds.push(id);
+            const previousStars = levelRecords[id]?.stars ?? 0;
+            const bestStars = Math.max(previousStars, stars ?? 0);
+            levelRecords[id] = { cleared: true, stars: bestStars };
+            persistRecords();
             status = "cleared";
         },
+        select(level) {
+            const idx = indexOfLevel(level);
+            if (idx < 0 || !isUnlocked(level))
+                return false;
+            index = idx;
+            attempt = 1;
+            status = "playing";
+            return true;
+        },
+        isUnlocked,
+        record: (level) => levelRecords[level] ?? null,
+        records: () => ({ ...levelRecords }),
+        clearRecords() {
+            for (const id of Object.keys(levelRecords))
+                delete levelRecords[id];
+            store?.clear();
+            index = 0;
+            attempt = 1;
+            clearedIds.length = 0;
+            status = "idle";
+        },
         fail() {
             if (status !== "playing" || current() === null)
                 return "failed";

package/dist/game/loadout.d.ts

@@ -44,4 +44,9 @@ export interface Loadouts {
         reason: string;
     } | null;
 }
+/**
+ * Save, name, and swap equipment loadouts.
+ *
+ * @capability loadouts save and swap named equipment loadouts
+ */
 export declare function createLoadouts(deps: LoadoutDeps): Loadouts;

package/dist/game/loadout.js

@@ -1,3 +1,8 @@
+/**
+ * Save, name, and swap equipment loadouts.
+ *
+ * @capability loadouts save and swap named equipment loadouts
+ */
 export function createLoadouts(deps) {
     const definitions = new Map();
     return {

package/dist/game/lootFilter.d.ts

@@ -27,6 +27,8 @@ export interface LootFilterOverride {
  * First matching rule wins (PoE/Last Epoch block semantics) — later rules
  * never override an earlier match. Returns overrides only; fields the rule
  * doesn't set are left for the caller's baseline (rarity style) to fill in.
+ *
+ * @capability loot-filter filter and highlight drops by rarity/name rules
  */
 export declare function evaluateLootFilter(rules: readonly LootFilterRule[], item: LootFilterItem): LootFilterOverride;
 /** Validating factory — rule ids must be unique so authoring mistakes fail loudly. */

package/dist/game/lootFilter.js

@@ -18,6 +18,8 @@ function matchesCondition(when, item) {
  * First matching rule wins (PoE/Last Epoch block semantics) — later rules
  * never override an earlier match. Returns overrides only; fields the rule
  * doesn't set are left for the caller's baseline (rarity style) to fill in.
+ *
+ * @capability loot-filter filter and highlight drops by rarity/name rules
  */
 export function evaluateLootFilter(rules, item) {
     for (const rule of rules) {