@jgengine/core 0.14.0 → 0.15.0

package/dist/game/lootTable.js

@@ -1,3 +1,4 @@
+import { resolveRng } from "../random/resolveRng.js";
 function assertValidEntry(entry, mode) {
     const kinds = [entry.item !== undefined, entry.currency !== undefined, entry.generate !== undefined].filter(Boolean).length;
     if (kinds !== 1) {
@@ -53,8 +54,9 @@ function rollEntry(entry, rng) {
  *
  * @capability loot-table register loot tables and roll weighted randomized drops
  */
-export function createLootRegistry() {
+export function createLootRegistry(options = {}) {
     const tables = new Map();
+    const defaultRng = resolveRng(options.rng, "createLootRegistry");
     return {
         register(def) {
             assertValidDef(def);
@@ -66,7 +68,7 @@ export function createLootRegistry() {
         has(id) {
             return tables.has(id);
         },
-        roll(id, rng = Math.random) {
+        roll(id, rng = defaultRng) {
             const table = tables.get(id);
             if (!table) {
                 throw new Error(`unknown loot table: ${id}`);

package/dist/game/notifications.d.ts

@@ -0,0 +1,57 @@
+/** One persistent notification — unlike a transient toast, it stays in the log until dismissed. */
+export interface NotificationEntry<TMeta = unknown> {
+    id: string;
+    /** Severity/category (`"info"`, `"success"`, `"warning"`, `"danger"`, or a game kind). */
+    kind: string;
+    title: string;
+    body?: string;
+    /** Creation time from the injected clock. */
+    at: number;
+    read: boolean;
+    meta?: TMeta;
+}
+/** Fields accepted by {@link NotificationStore.push}. */
+export interface NotificationInput<TMeta = unknown> {
+    id?: string;
+    kind?: string;
+    title: string;
+    body?: string;
+    at?: number;
+    meta?: TMeta;
+}
+/** Filter for {@link NotificationStore.list}. */
+export interface NotificationFilter {
+    kind?: string;
+    unreadOnly?: boolean;
+}
+/** Serializable, observable log of persistent notifications with read tracking. */
+export interface NotificationStore<TMeta = unknown> {
+    push(input: NotificationInput<TMeta>): NotificationEntry<TMeta>;
+    /** Newest-first; filter by kind and/or unread. Stable identity between changes for the unfiltered read. */
+    list(filter?: NotificationFilter): readonly NotificationEntry<TMeta>[];
+    unreadCount(): number;
+    markRead(id: string): void;
+    markAllRead(): void;
+    remove(id: string): boolean;
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    snapshot(): readonly NotificationEntry<TMeta>[];
+    restore(snapshot: readonly NotificationEntry<TMeta>[]): void;
+}
+/** Options for {@link createNotificationCenter}. */
+export interface NotificationCenterOptions {
+    /** Injected clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Keep only the newest `cap` notifications. Default 100; 0 = unbounded. */
+    cap?: number;
+}
+/**
+ * A persistent notification log with read/unread tracking — the "notification
+ * center" surface toasts don't cover. Newest-first, capped, serializable, and
+ * observable; a game pushes durable events (quest updates, trades, party news)
+ * here and a HUD renders the list + an unread badge. `snapshot`/`restore`
+ * round-trip through a save.
+ *
+ * @capability notification-center persistent, read-tracked notification log (newest-first, capped, serializable) behind an unread badge — the durable counterpart to transient toasts
+ */
+export declare function createNotificationCenter<TMeta = unknown>(options?: NotificationCenterOptions): NotificationStore<TMeta>;

package/dist/game/notifications.js

@@ -0,0 +1,107 @@
+/**
+ * A persistent notification log with read/unread tracking — the "notification
+ * center" surface toasts don't cover. Newest-first, capped, serializable, and
+ * observable; a game pushes durable events (quest updates, trades, party news)
+ * here and a HUD renders the list + an unread badge. `snapshot`/`restore`
+ * round-trip through a save.
+ *
+ * @capability notification-center persistent, read-tracked notification log (newest-first, capped, serializable) behind an unread badge — the durable counterpart to transient toasts
+ */
+export function createNotificationCenter(options = {}) {
+    const now = options.now ?? Date.now;
+    const cap = options.cap ?? 100;
+    let entries = []; // newest-first
+    const listeners = new Set();
+    let cache = null;
+    let counter = 0;
+    function notify() {
+        cache = null;
+        for (const listener of listeners)
+            listener();
+    }
+    function generateId() {
+        counter += 1;
+        return `notice-${counter}`;
+    }
+    return {
+        push(input) {
+            const entry = {
+                id: input.id ?? generateId(),
+                kind: input.kind ?? "info",
+                title: input.title,
+                at: input.at ?? now(),
+                read: false,
+                ...(input.body !== undefined ? { body: input.body } : {}),
+                ...(input.meta !== undefined ? { meta: input.meta } : {}),
+            };
+            entries = [entry, ...entries.filter((existing) => existing.id !== entry.id)];
+            if (cap > 0 && entries.length > cap)
+                entries = entries.slice(0, cap);
+            notify();
+            return entry;
+        },
+        list(filter) {
+            if (filter === undefined) {
+                if (cache === null)
+                    cache = [...entries];
+                return cache;
+            }
+            return entries.filter((entry) => (filter.kind === undefined || entry.kind === filter.kind) &&
+                (filter.unreadOnly !== true || !entry.read));
+        },
+        unreadCount() {
+            let count = 0;
+            for (const entry of entries)
+                if (!entry.read)
+                    count += 1;
+            return count;
+        },
+        markRead(id) {
+            const entry = entries.find((candidate) => candidate.id === id);
+            if (entry === undefined || entry.read)
+                return;
+            entry.read = true;
+            notify();
+        },
+        markAllRead() {
+            let changed = false;
+            for (const entry of entries) {
+                if (!entry.read) {
+                    entry.read = true;
+                    changed = true;
+                }
+            }
+            if (changed)
+                notify();
+        },
+        remove(id) {
+            const next = entries.filter((entry) => entry.id !== id);
+            if (next.length === entries.length)
+                return false;
+            entries = next;
+            notify();
+            return true;
+        },
+        clear() {
+            if (entries.length === 0)
+                return;
+            entries = [];
+            notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            if (cache === null)
+                cache = [...entries];
+            return cache;
+        },
+        restore(snapshot) {
+            entries = snapshot.map((entry) => ({ ...entry }));
+            if (cap > 0 && entries.length > cap)
+                entries = entries.slice(0, cap);
+            notify();
+        },
+    };
+}

package/dist/game/playableGame.d.ts

@@ -140,6 +140,22 @@ export interface ModelMaterialOverride {
     emissiveIntensity?: number;
     /** Real PBR texture maps applied over the model's material — see {@link ModelMaterialMaps}. */
     maps?: ModelMaterialMaps;
+    /**
+     * Fresnel rim light: a bright edge where the surface turns away from the viewer. This is what
+     * separates an actor from ground of the same value — a body lit only by the scene's own key sits
+     * in the terrain's tonal band at range and reads as a smudge, however well its albedo is chosen.
+     * Omit for no rim.
+     */
+    rim?: ModelRimLight;
+}
+/** Fresnel rim-light term added on top of a model's lighting — see {@link ModelMaterialOverride.rim}. */
+export interface ModelRimLight {
+    /** Rim colour. Default "#ffffff". */
+    color?: string;
+    /** Rim brightness. 0 disables it; ~0.3 is a subtle read, ~1.5 is a hard sci-fi edge. Default 0.6. */
+    strength?: number;
+    /** Falloff exponent: higher confines the rim to the extreme edge. Default 2.5. */
+    power?: number;
 }
 /** Parents a prop/weapon model to a named bone or node on the host model's rig — a sword on `handslot.r`, a spellbook offhand — following the bone's animated transform each frame. */
 export interface ModelAttachment {
@@ -221,6 +237,14 @@ export interface DirectionalLightingConfig {
     shadowMapSize?: number;
     /** Half-extent of the orthographic shadow camera in world units — sized to the shadowed area. Default 40. */
     shadowCameraSize?: number;
+    /**
+     * Cascade count for cascaded shadow maps (CSM). When `> 1` and `castShadow`, the shell mounts
+     * three.js CSM so outdoor scenes keep shadows past a single ortho frustum. Default `1` (legacy
+     * single map). Typical outdoor value: `3` or `4`.
+     */
+    cascades?: number;
+    /** Max far plane for CSM cascades in world units. Default 200. */
+    shadowMaxFar?: number;
     /** Shadow depth bias to fight acne. Default -0.0004. */
     shadowBias?: number;
     /** Shadow normal bias to fight peter-panning. Default 0.02. */
@@ -258,8 +282,16 @@ export interface PlayerMovementConfig {
     axis?: "x" | "z";
     /** Cell size for mode "grid". Default 1. */
     cellSize?: number;
-    /** Collide the walking player against placed scene objects (unit-box AABBs) even without `collision.voxel`. Default false. */
+    /**
+     * Collide the walking player against placed scene objects' blocking colliders even without
+     * `collision.voxel`. Default **true** — a placed object with a blocking physical collider stops,
+     * supports, and is stood upon by the player; set `false` to walk through everything (ghost/spectator
+     * modes, pure-board presentations). Objects that should never block should carry non-blocking
+     * colliders instead of relying on this switch.
+     */
     collideObjects?: boolean;
+    /** Tallest object ledge stepped up while walking (and largest drop still snapped down instead of falling). Default 0.4. */
+    stepHeight?: number;
     /** Intercepts each frame's resolved position before the pose commits (and before onTick): return a replacement [x,y,z] to constrain or redirect the step, or nothing to accept it. */
     beforeCommit?: (frame: MovementCommitFrame) => readonly [number, number, number] | undefined | void;
     /** Gates the built-in sprint (`runSpeedMultiplier`) behind live game state — a stamina stat, an encumbrance check (#282.3). Called each frame while sprint is held; `false` walks. */
@@ -297,7 +329,12 @@ export interface PresentationEffectsConfig {
     vfx?: boolean;
     /** Floating combat text (damage numbers, etc.). Default true. */
     floatText?: boolean;
-    /** Projectile tracer lines. Default true. */
+    /**
+     * Straight muzzle→impact tracer lines for direct-fire shots. Opt-in (default false): unlike the
+     * other channels, a missing `tracers` key leaves them OFF, because `fireProjectile` is a generic
+     * seam and a tracer is only meaningful for a game that fires direct, bullet-like projectiles.
+     * Arced/exploding shots (grenades, launchers) never draw a tracer even when this is on.
+     */
     tracers?: boolean;
     /** Trauma-driven combat camera shake. Default true. */
     shake?: boolean;

package/dist/game/quest.d.ts

@@ -99,6 +99,32 @@ export interface QuestJournal {
  * @capability quest-log track accepted quests and their per-objective progress
  */
 export declare function createQuestJournal(deps: QuestJournalDeps): QuestJournal;
+/** One objective as a tracker/HUD reads it — label + progress toward its count. */
+export interface TrackedObjectiveView {
+    id: string;
+    /** Human label (e.g. "Defeat 3 wraiths"); falls back to the objective id. */
+    label: string;
+    count: number;
+    progress: number;
+    complete: boolean;
+}
+/** A quest as a tracker/HUD reads it — title, status, and per-objective progress. */
+export interface TrackedQuestView {
+    id: string;
+    title: string;
+    status: QuestStatus;
+    objectives: TrackedObjectiveView[];
+}
+/** Default objective label: a readable "verb count noun" from a {@link QuestObjective}. */
+export declare function defaultObjectiveLabel(objective: QuestObjective): string;
+/**
+ * Join a quest's static {@link QuestDef} with a player's live {@link QuestInstance}
+ * into a flat, renderer-free view a HUD tracker draws (title, status, labelled
+ * objective progress). Pass `label` to override the derived objective text.
+ *
+ * @capability quest-tracker-view join a QuestDef + live QuestInstance into a flat labelled view for a quest/objective HUD tracker
+ */
+export declare function describeTrackedQuest(def: QuestDef, instance: QuestInstance, label?: (objective: QuestObjective) => string): TrackedQuestView;
 export interface QuestAcceptOptions {
     hasUnlock?(id: string): boolean;
 }

package/dist/game/quest.js

@@ -259,6 +259,37 @@ export function createQuestJournal(deps) {
         },
     };
 }
+/** Default objective label: a readable "verb count noun" from a {@link QuestObjective}. */
+export function defaultObjectiveLabel(objective) {
+    const noun = objective.target ?? objective.item ?? objective.id;
+    const verb = objective.kind === "kill" ? "Defeat" : objective.kind === "collect" ? "Collect" : objective.kind;
+    return `${verb} ${objective.count} ${noun}`;
+}
+/**
+ * Join a quest's static {@link QuestDef} with a player's live {@link QuestInstance}
+ * into a flat, renderer-free view a HUD tracker draws (title, status, labelled
+ * objective progress). Pass `label` to override the derived objective text.
+ *
+ * @capability quest-tracker-view join a QuestDef + live QuestInstance into a flat labelled view for a quest/objective HUD tracker
+ */
+export function describeTrackedQuest(def, instance, label = defaultObjectiveLabel) {
+    const defs = new Map(def.objectives.map((objective) => [objective.id, objective]));
+    return {
+        id: def.id,
+        title: def.title,
+        status: instance.status,
+        objectives: instance.objectives.map((progress) => {
+            const source = defs.get(progress.id);
+            return {
+                id: progress.id,
+                label: source === undefined ? progress.id : label(source),
+                count: progress.count,
+                progress: progress.progress,
+                complete: progress.complete,
+            };
+        }),
+    };
+}
 export function applyQuestRewards(rewards, appliers) {
     for (const entry of rewards.items ?? []) {
         const fail = appliers.grantItem?.(entry.inventory, entry.item, entry.count);

package/dist/game/runDraft.js

@@ -1,4 +1,5 @@
 import { pickWeighted } from "../world/scatterItems.js";
+import { resolveRng } from "../random/resolveRng.js";
 export function createRunModifierStack(offers) {
     const byId = new Map();
     for (const offer of offers) {
@@ -75,7 +76,7 @@ export function createRunModifierStack(offers) {
  */
 export function createRunDraft(config) {
     const stack = createRunModifierStack(config.offers);
-    const defaultRng = config.rng ?? Math.random;
+    const defaultRng = resolveRng(config.rng, "createRunDraft");
     return {
         present(count, rng = defaultRng) {
             const pool = config.offers.filter((offer) => !stack.atMax(offer.id));

package/dist/game/saveSlots.d.ts

@@ -0,0 +1,102 @@
+/**
+ * One entry in a {@link SaveSlots} index: a save/profile slot's *display*
+ * metadata, not its payload. The real save data lives in a `createSaveStore`
+ * slot; this record is only what a save-select menu renders — an id, an optional
+ * player-facing `name`, whether the slot is `empty`, when it was last written
+ * (`savedAt`), and a free-string `meta` bag the game fills with whatever the
+ * menu should show (level, playtime, location, chapter, a thumbnail ref, …).
+ * `meta` keys are opaque to this model — it never reads or branches on them.
+ */
+export interface SaveSlotMeta {
+    /** Stable slot id — pair it with the same slot in the game's `createSaveStore`. */
+    id: string;
+    /** Player-facing label (character name, save title). `undefined` until named. */
+    name?: string;
+    /** `true` when no save occupies this slot — the menu shows a "New Game" affordance. */
+    empty: boolean;
+    /** Clock time (ms) of the last {@link SaveSlots.write}, or `undefined` while empty. */
+    savedAt?: number;
+    /**
+     * Free-string display fields the game owns and the menu renders as chips —
+     * e.g. `{ chapter: "The Drowned Keep", playtime: "4h 12m", level: 8 }`. The
+     * model never interprets these keys; they are pure passthrough to the renderer.
+     */
+    meta: Record<string, string | number>;
+}
+/** What a {@link SaveSlots.write} stamps onto a slot — a name and/or a fresh `meta` bag. */
+export interface SaveSlotWrite {
+    /** Player-facing label for the slot. Omit to keep the existing name. */
+    name?: string;
+    /** Replacement free-string display fields. Omit to keep the existing `meta`. */
+    meta?: Record<string, string | number>;
+}
+/** How a {@link createSaveSlots} index is wired. */
+export interface SaveSlotsConfig {
+    /** Injected clock (ms) used to stamp `savedAt`. Default `Date.now`. */
+    now?: () => number;
+    /**
+     * Initial slots, in menu order. Any slot omitting `empty` is treated as empty.
+     * When `capacity` is set and this is shorter, the list is padded with empty
+     * slots (`slot-1`, `slot-2`, …) up to `capacity`.
+     */
+    slots?: SaveSlotMeta[];
+    /**
+     * Fixed number of slots the menu shows. When set, the index is padded with
+     * empty slots up to this count and never grows past it. Omit for an
+     * open-ended list that only holds the slots you seed.
+     */
+    capacity?: number;
+}
+/** Serializable state of a {@link SaveSlots} index, for save/restore. */
+export interface SaveSlotsSnapshot {
+    /** The slots in menu order. */
+    slots: SaveSlotMeta[];
+    /** The fixed capacity, or `undefined` for an open-ended list. */
+    capacity: number | undefined;
+}
+/**
+ * A serializable, observable index of save/profile slot *metadata* that a
+ * save-select menu renders. It complements `createSaveStore` (which owns the
+ * actual save payload and named slots) by carrying the per-slot display fields
+ * the store does not: name, empty flag, last-saved time, and a free-string
+ * `meta` bag the game fills. Nothing here is genre-specific.
+ */
+export interface SaveSlots {
+    /**
+     * Stamp a slot as written: sets `empty=false`, records `savedAt` via the
+     * injected clock, and applies the given `name`/`meta`. Creates the slot if it
+     * does not exist (subject to `capacity`). Returns the resulting slot record.
+     */
+    write(id: string, write?: SaveSlotWrite): SaveSlotMeta;
+    /** Mark a slot empty, dropping its `name`, `savedAt`, and `meta`. Returns the cleared record, or `null` if the id is unknown. */
+    clear(id: string): SaveSlotMeta | null;
+    /** Rename a slot without touching its `savedAt`/`meta`. Returns the updated record, or `null` if the id is unknown. */
+    rename(id: string, name: string): SaveSlotMeta | null;
+    /** The slot with this id, or `null`. The returned record is a copy — mutating it does not affect the index. */
+    get(id: string): SaveSlotMeta | null;
+    /** All slots in menu order (copies). Powers the save-select grid. */
+    list(): SaveSlotMeta[];
+    /** The newest non-empty slot (highest `savedAt`), or `null` when every slot is empty — powers "Continue". */
+    mostRecent(): SaveSlotMeta | null;
+    /** Observe any change (write/clear/rename/restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): SaveSlotsSnapshot;
+    /** Restore from a {@link SaveSlotsSnapshot}, replacing all slots. */
+    restore(snapshot: SaveSlotsSnapshot): void;
+}
+/**
+ * Create a {@link SaveSlots} index — the serializable, observable list of
+ * save/profile slot metadata a save-select menu renders. It is a thin companion
+ * to `createSaveStore`: the store owns the real save payload keyed by slot, this
+ * owns only the display fields (name, empty, last-saved, and a free-string
+ * `meta` bag) the menu shows. `write` stamps a slot saved on the injected clock,
+ * `clear` empties one, `rename` relabels one, `mostRecent()` returns the newest
+ * non-empty slot to power a "Continue" button, and `list()` feeds the New /
+ * Continue / Load / Delete grid. `meta` keys are free strings the game owns —
+ * the model never interprets them — and `snapshot`/`restore` round-trips the
+ * whole index through a save.
+ *
+ * @capability save-slots serializable save-slot / profile metadata index — write/clear/rename/mostRecent over free-string per-slot meta, powering New/Continue/Load/Delete menus, with snapshot/restore
+ */
+export declare function createSaveSlots(config?: SaveSlotsConfig): SaveSlots;

package/dist/game/saveSlots.js

@@ -0,0 +1,136 @@
+function emptySlot(id) {
+    return { id, empty: true, meta: {} };
+}
+function cloneSlot(slot) {
+    return {
+        id: slot.id,
+        name: slot.name,
+        empty: slot.empty,
+        savedAt: slot.savedAt,
+        meta: { ...slot.meta },
+    };
+}
+function normalizeSlot(slot) {
+    const empty = slot.empty ?? true;
+    return {
+        id: slot.id,
+        name: slot.name,
+        empty,
+        savedAt: empty ? undefined : slot.savedAt,
+        meta: empty ? {} : { ...(slot.meta ?? {}) },
+    };
+}
+/**
+ * Create a {@link SaveSlots} index — the serializable, observable list of
+ * save/profile slot metadata a save-select menu renders. It is a thin companion
+ * to `createSaveStore`: the store owns the real save payload keyed by slot, this
+ * owns only the display fields (name, empty, last-saved, and a free-string
+ * `meta` bag) the menu shows. `write` stamps a slot saved on the injected clock,
+ * `clear` empties one, `rename` relabels one, `mostRecent()` returns the newest
+ * non-empty slot to power a "Continue" button, and `list()` feeds the New /
+ * Continue / Load / Delete grid. `meta` keys are free strings the game owns —
+ * the model never interprets them — and `snapshot`/`restore` round-trips the
+ * whole index through a save.
+ *
+ * @capability save-slots serializable save-slot / profile metadata index — write/clear/rename/mostRecent over free-string per-slot meta, powering New/Continue/Load/Delete menus, with snapshot/restore
+ */
+export function createSaveSlots(config = {}) {
+    const now = config.now ?? Date.now;
+    let capacity = config.capacity;
+    const slots = (config.slots ?? []).map(normalizeSlot);
+    const seen = new Set(slots.map((slot) => slot.id));
+    if (capacity !== undefined) {
+        let n = 1;
+        while (slots.length < capacity) {
+            let id = `slot-${n}`;
+            while (seen.has(id)) {
+                n += 1;
+                id = `slot-${n}`;
+            }
+            seen.add(id);
+            slots.push(emptySlot(id));
+            n += 1;
+        }
+    }
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function indexOf(id) {
+        return slots.findIndex((slot) => slot.id === id);
+    }
+    return {
+        write(id, write) {
+            let i = indexOf(id);
+            if (i === -1) {
+                if (capacity !== undefined && slots.length >= capacity) {
+                    throw new Error(`save-slots: cannot create slot "${id}" — capacity ${capacity} reached`);
+                }
+                slots.push(emptySlot(id));
+                i = slots.length - 1;
+            }
+            const slot = slots[i];
+            slot.empty = false;
+            slot.savedAt = now();
+            if (write?.name !== undefined)
+                slot.name = write.name;
+            if (write?.meta !== undefined)
+                slot.meta = { ...write.meta };
+            notify();
+            return cloneSlot(slot);
+        },
+        clear(id) {
+            const i = indexOf(id);
+            if (i === -1)
+                return null;
+            const slot = slots[i];
+            slot.empty = true;
+            slot.name = undefined;
+            slot.savedAt = undefined;
+            slot.meta = {};
+            notify();
+            return cloneSlot(slot);
+        },
+        rename(id, name) {
+            const i = indexOf(id);
+            if (i === -1)
+                return null;
+            const slot = slots[i];
+            slot.name = name;
+            notify();
+            return cloneSlot(slot);
+        },
+        get(id) {
+            const i = indexOf(id);
+            return i === -1 ? null : cloneSlot(slots[i]);
+        },
+        list() {
+            return slots.map(cloneSlot);
+        },
+        mostRecent() {
+            let best = null;
+            for (const slot of slots) {
+                if (slot.empty)
+                    continue;
+                if (best === null || (slot.savedAt ?? 0) > (best.savedAt ?? 0))
+                    best = slot;
+            }
+            return best === null ? null : cloneSlot(best);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { slots: slots.map(cloneSlot), capacity };
+        },
+        restore(snapshot) {
+            capacity = snapshot.capacity;
+            slots.length = 0;
+            for (const slot of snapshot.slots)
+                slots.push(normalizeSlot(slot));
+            notify();
+        },
+    };
+}