@jgengine/core 0.14.0 → 0.15.0

package/dist/game/dialogueGraph.d.ts

@@ -0,0 +1,116 @@
+/**
+ * One selectable response on a conversation node — the text a player clicks and the
+ * node it advances to. `kind` is a free style tag the presenter interprets; the model
+ * never reads it (no genre baked in).
+ */
+export interface DialogueGraphChoice {
+    /** Player-facing choice text. */
+    text: string;
+    /** Id of the node this choice advances to. Omitted / `null` ends the conversation. */
+    to?: string | null;
+    /** Free-string style/category tag the game styles on (never interpreted by the model). */
+    kind?: string;
+}
+/**
+ * One conversation node: who is speaking, the line they say, and the branches out of it.
+ * `speaker`/`speakerKind`/`portrait` are opaque display data — the model never interprets them.
+ */
+export interface DialogueGraphNode {
+    /** Stable node id — choices point at it via {@link DialogueGraphChoice.to}. */
+    id: string;
+    /** Free-string speaker name shown in the view. Omitted → an unattributed line. */
+    speaker?: string;
+    /** Free-string speaker style tag (the game maps it to a portrait frame / name color). */
+    speakerKind?: string;
+    /** Opaque portrait key or URL the view renders in its portrait slot. */
+    portrait?: string;
+    /** The line this node speaks. */
+    text: string;
+    /** Branching responses. Empty / omitted → a terminal node the player can close. */
+    choices?: readonly DialogueGraphChoice[];
+}
+/** A serializable branching conversation: a start node id and the nodes it can reach. */
+export interface DialogueGraph {
+    /** Id of the node the conversation opens on. */
+    start: string;
+    /** Every node in the conversation. */
+    nodes: readonly DialogueGraphNode[];
+}
+/**
+ * The render-ready snapshot of a conversation at one node — everything a view needs to
+ * draw speaker, line, and choice buttons, with no traversal logic in the component.
+ */
+export interface DialogueGraphView {
+    /** Current node id. */
+    nodeId: string;
+    /** Speaker name to display, or `undefined` for an unattributed line. */
+    speaker?: string;
+    /** Speaker style tag the game skins on. */
+    speakerKind?: string;
+    /** Portrait key/URL for the portrait slot, or `undefined` when none. */
+    portrait?: string;
+    /** The current line text. */
+    text: string;
+    /** Branching responses at this node (empty at a terminal node). */
+    choices: readonly DialogueGraphChoice[];
+    /** True when this node has no onward choices — the conversation can be closed. */
+    done: boolean;
+}
+/** Serializable run state — the current node id and the ids already visited. */
+export interface DialogueGraphSnapshot {
+    /** Node the run is currently sitting on. */
+    nodeId: string;
+    /** Node ids visited so far, in order (a start node is the first). */
+    visited: readonly string[];
+}
+/** Options for {@link createDialogueRun}. */
+export interface DialogueRunOptions {
+    /** Node id to open on. Default: the graph's `start`. */
+    startAt?: string;
+    /** Visited node ids to seed (e.g. restored from a save). */
+    visited?: Iterable<string>;
+}
+/** An observable walk through a {@link DialogueGraph}: current view, choose to advance, serialize. */
+export interface DialogueRun {
+    /** The graph being walked. */
+    readonly graph: DialogueGraph;
+    /** Render-ready view at the current node, or `null` if the current id is unknown. */
+    current(): DialogueGraphView | null;
+    /** The current node's id. */
+    currentId(): string;
+    /** Advance via the choice at `index` on the current node; returns the new view (or `null`). */
+    choose(index: number): DialogueGraphView | null;
+    /** Jump straight to a node id (bypassing choices); returns its view (or `null`). */
+    goTo(nodeId: string): DialogueGraphView | null;
+    /** Re-open on the start node, clearing visited history. */
+    reset(): DialogueGraphView | null;
+    /** Whether the current node is terminal (no onward choices). */
+    isDone(): boolean;
+    /** Whether a node id has been visited this run. */
+    hasVisited(nodeId: string): boolean;
+    /** Observe advance / jump / reset. Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable run state for a save. */
+    snapshot(): DialogueGraphSnapshot;
+    /** Restore from a {@link DialogueGraphSnapshot}. */
+    restore(snapshot: DialogueGraphSnapshot): void;
+}
+/**
+ * Project a {@link DialogueGraph} node id to its render-ready {@link DialogueGraphView} —
+ * the pure "current view" selector a stateless renderer reads (speaker, line, choices,
+ * done). Returns `null` when the id is not in the graph. No traversal or mutation.
+ *
+ * @capability dialogue-graph-view select a conversation node's render-ready view (speaker, line, branching choices) from a serializable dialogue graph
+ */
+export declare function selectDialogueView(graph: DialogueGraph, nodeId: string): DialogueGraphView | null;
+/**
+ * Walk a branching {@link DialogueGraph}: hold the current node, expose its render-ready
+ * view, and advance by choosing one of the current node's responses (each choice names the
+ * node it leads to; a choice with no `to` ends the conversation). Purely a serializable
+ * model — a React host renders `current()` and calls `choose(index)` — so no game
+ * re-implements node lookup, choice-to-node traversal, or "am I at the end" bookkeeping.
+ * `snapshot`/`restore` round-trip the run through a save.
+ *
+ * @capability dialogue-run walk a serializable branching dialogue graph — current node view, choose-to-advance traversal, visited history, snapshot/restore
+ */
+export declare function createDialogueRun(graph: DialogueGraph, options?: DialogueRunOptions): DialogueRun;

package/dist/game/dialogueGraph.js

@@ -0,0 +1,103 @@
+/**
+ * Project a {@link DialogueGraph} node id to its render-ready {@link DialogueGraphView} —
+ * the pure "current view" selector a stateless renderer reads (speaker, line, choices,
+ * done). Returns `null` when the id is not in the graph. No traversal or mutation.
+ *
+ * @capability dialogue-graph-view select a conversation node's render-ready view (speaker, line, branching choices) from a serializable dialogue graph
+ */
+export function selectDialogueView(graph, nodeId) {
+    const node = graph.nodes.find((candidate) => candidate.id === nodeId);
+    if (node === undefined)
+        return null;
+    const choices = node.choices ?? [];
+    return {
+        nodeId: node.id,
+        speaker: node.speaker,
+        speakerKind: node.speakerKind,
+        portrait: node.portrait,
+        text: node.text,
+        choices,
+        done: choices.length === 0,
+    };
+}
+/**
+ * Walk a branching {@link DialogueGraph}: hold the current node, expose its render-ready
+ * view, and advance by choosing one of the current node's responses (each choice names the
+ * node it leads to; a choice with no `to` ends the conversation). Purely a serializable
+ * model — a React host renders `current()` and calls `choose(index)` — so no game
+ * re-implements node lookup, choice-to-node traversal, or "am I at the end" bookkeeping.
+ * `snapshot`/`restore` round-trip the run through a save.
+ *
+ * @capability dialogue-run walk a serializable branching dialogue graph — current node view, choose-to-advance traversal, visited history, snapshot/restore
+ */
+export function createDialogueRun(graph, options = {}) {
+    const start = options.startAt ?? graph.start;
+    const listeners = new Set();
+    let currentId = start;
+    const visited = [];
+    function markVisited(id) {
+        if (visited[visited.length - 1] !== id)
+            visited.push(id);
+    }
+    for (const id of options.visited ?? [])
+        markVisited(id);
+    markVisited(currentId);
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function moveTo(nodeId) {
+        currentId = nodeId;
+        markVisited(nodeId);
+        notify();
+        return selectDialogueView(graph, currentId);
+    }
+    return {
+        graph,
+        current() {
+            return selectDialogueView(graph, currentId);
+        },
+        currentId() {
+            return currentId;
+        },
+        choose(index) {
+            const view = selectDialogueView(graph, currentId);
+            const choice = view?.choices[index];
+            if (choice === undefined)
+                return view;
+            const to = choice.to;
+            if (to === undefined || to === null)
+                return view; // terminal choice — caller closes
+            return moveTo(to);
+        },
+        goTo(nodeId) {
+            return moveTo(nodeId);
+        },
+        reset() {
+            visited.length = 0;
+            return moveTo(start);
+        },
+        isDone() {
+            return (selectDialogueView(graph, currentId)?.done ?? true) === true;
+        },
+        hasVisited(nodeId) {
+            return visited.includes(nodeId);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { nodeId: currentId, visited: [...visited] };
+        },
+        restore(snapshot) {
+            currentId = snapshot.nodeId;
+            visited.length = 0;
+            for (const id of snapshot.visited)
+                markVisited(id);
+            if (!visited.includes(currentId))
+                markVisited(currentId);
+            notify();
+        },
+    };
+}

package/dist/game/eventTicker.d.ts

@@ -0,0 +1,95 @@
+import { type TimedFeedEntry } from "./feed.js";
+/**
+ * One event pushed onto the ticker. `kind` and `icon` are free strings the game owns
+ * and the model never interprets — they only ride through to the renderer so a game can
+ * color, icon, and group each entry however it likes ("kill", "assist", "info", …).
+ */
+export interface EventTickerInput {
+    /** Free-string category the game styles; the model never branches on it. */
+    kind: string;
+    /** The line to show (e.g. `"Ranger eliminated Marauder"`). */
+    text: string;
+    /** Optional free-string icon name the renderer resolves. */
+    icon?: string;
+}
+/** A stored ticker entry — an {@link EventTickerInput} stamped with an id and clock time. */
+export interface EventTickerEntry extends TimedFeedEntry {
+    /** Stable id assigned at push time. */
+    id: number;
+    /** Clock time (ms) the entry was pushed, for age-based fade/prune. */
+    at: number;
+    /** The game-owned free-string category. */
+    kind: string;
+    /** The line to show. */
+    text: string;
+    /** Optional free-string icon name. */
+    icon: string | undefined;
+}
+/**
+ * A live ticker entry as handed to the renderer: the stored entry plus a `fade` value
+ * `0..1` (age / `ttlMs`) — `0` for a fresh entry, approaching `1` as it nears expiry —
+ * so the UI can drop opacity as an entry ages out. `fade` is always `0` when no `ttlMs`
+ * is configured.
+ */
+export interface EventTickerView extends EventTickerEntry {
+    /** How faded this entry should be, `0` (fresh) → `1` (about to expire). */
+    fade: number;
+}
+/** Serializable state of the ticker, for save/restore. */
+export interface EventTickerSnapshot {
+    /** Wall-clock (ms) the snapshot was taken, so restore re-anchors entry ages. */
+    now: number;
+    /** Next id to hand out. */
+    nextId: number;
+    /** The kept entries, oldest first. */
+    entries: readonly EventTickerEntry[];
+}
+/** Options for {@link createEventTicker}. */
+export interface EventTickerOptions {
+    /** Injected clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Max entries kept — older ones drop off the tail. Omit for no count cap. */
+    limit?: number;
+    /**
+     * How long (ms) an entry lives before it should be fully faded and pruned. Omit to keep
+     * entries indefinitely with `fade` pinned at `0`.
+     */
+    ttlMs?: number;
+}
+/** A live, observable event/kill-feed ticker. */
+export interface EventTicker {
+    /**
+     * Append an event. Stamps `at` from the injected clock, assigns an id, applies the count
+     * cap, and notifies subscribers. Returns the new entry's id.
+     */
+    push(input: EventTickerInput): number;
+    /**
+     * Prune entries older than `ttlMs` (relative to `nowOverride ?? now()`), then return the
+     * live entries newest-first, each carrying its `fade` `0..1`. Safe to call every frame:
+     * it drops expired entries but does not notify (the caller re-renders on its own tick).
+     */
+    recent(nowOverride?: number): EventTickerView[];
+    /** The kept entries oldest-first, without `fade` — a plain snapshot of the buffer. */
+    entries(): EventTickerEntry[];
+    /** Drop every entry. Notifies subscribers. */
+    clear(): void;
+    /** Observe changes (push, clear, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): EventTickerSnapshot;
+    /** Restore from an {@link EventTickerSnapshot}, re-anchoring entry ages to the current clock. */
+    restore(snapshot: EventTickerSnapshot): void;
+}
+/**
+ * A thin, serializable, observable event/kill-feed ticker over the flat {@link appendFeed} /
+ * {@link pruneFeed} feed helpers: a single rolling, count-capped, time-fading list of
+ * free-string entries. A game calls `push({ kind, text, icon? })` and the ticker stamps and
+ * caps it; `recent()` prunes expired entries and returns the live list newest-first, each with
+ * a `fade` `0..1` (age / `ttlMs`) for the renderer to drop opacity as entries age out. Nothing
+ * here is genre-specific: `kind`, `text`, and `icon` are free strings the game owns and styles,
+ * and the model never interprets them. `snapshot`/`restore` round-trips the buffer through a
+ * save, re-anchoring ages so fades resume correctly.
+ *
+ * @capability event-ticker rolling capped, timed-fade event/kill-feed ticker of free-string entries over the feed helpers — push/recent-with-fade, snapshot/restore
+ */
+export declare function createEventTicker(config?: EventTickerOptions): EventTicker;

package/dist/game/eventTicker.js

@@ -0,0 +1,91 @@
+import { appendFeed, pruneFeed } from "./feed.js";
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/**
+ * A thin, serializable, observable event/kill-feed ticker over the flat {@link appendFeed} /
+ * {@link pruneFeed} feed helpers: a single rolling, count-capped, time-fading list of
+ * free-string entries. A game calls `push({ kind, text, icon? })` and the ticker stamps and
+ * caps it; `recent()` prunes expired entries and returns the live list newest-first, each with
+ * a `fade` `0..1` (age / `ttlMs`) for the renderer to drop opacity as entries age out. Nothing
+ * here is genre-specific: `kind`, `text`, and `icon` are free strings the game owns and styles,
+ * and the model never interprets them. `snapshot`/`restore` round-trips the buffer through a
+ * save, re-anchoring ages so fades resume correctly.
+ *
+ * @capability event-ticker rolling capped, timed-fade event/kill-feed ticker of free-string entries over the feed helpers — push/recent-with-fade, snapshot/restore
+ */
+export function createEventTicker(config = {}) {
+    const now = config.now ?? Date.now;
+    const limit = config.limit;
+    const ttlMs = config.ttlMs;
+    let entries = [];
+    let nextId = 1;
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    /** Drop expired entries in place; returns `true` when the list changed. */
+    function prune(t) {
+        if (ttlMs === undefined)
+            return false;
+        const kept = pruneFeed(entries, t, ttlMs);
+        if (kept === entries)
+            return false;
+        entries = kept;
+        return true;
+    }
+    return {
+        push(input) {
+            const id = nextId++;
+            const entry = {
+                id,
+                at: now(),
+                kind: input.kind,
+                text: input.text,
+                icon: input.icon,
+            };
+            entries = appendFeed(entries, entry, limit === undefined ? undefined : { limit });
+            notify();
+            return id;
+        },
+        recent(nowOverride) {
+            const t = nowOverride ?? now();
+            prune(t);
+            const out = [];
+            // Newest first: walk the tail-to-head of the oldest-first buffer.
+            for (let i = entries.length - 1; i >= 0; i -= 1) {
+                const entry = entries[i];
+                const fade = ttlMs === undefined || ttlMs <= 0 ? 0 : clamp01((t - entry.at) / ttlMs);
+                out.push({ ...entry, fade });
+            }
+            return out;
+        },
+        entries() {
+            return entries.slice();
+        },
+        clear() {
+            if (entries.length === 0)
+                return;
+            entries = [];
+            notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return {
+                now: now(),
+                nextId,
+                entries: entries.map((entry) => ({ ...entry })),
+            };
+        },
+        restore(snapshot) {
+            nextId = snapshot.nextId;
+            const drift = now() - snapshot.now;
+            entries = snapshot.entries.map((entry) => ({ ...entry, at: entry.at + drift }));
+            notify();
+        },
+    };
+}

package/dist/game/events.d.ts

@@ -17,15 +17,29 @@ export interface EntityAnimationEvent {
     instanceId: string;
     event: string;
 }
+/**
+ * One granted reward: an inventory `item` id or a `currency` id, plus how many. Named because every
+ * consumer of `loot.granted` needs it — a toast renderer, a loot log, a session summary — and each
+ * one that re-declares the shape inline is a cast the compiler cannot check.
+ */
+export interface LootDrop {
+    item?: string;
+    currency?: string;
+    count: number;
+}
 export interface LootGrantedEvent {
     userId: string;
-    drops: {
-        item?: string;
-        currency?: string;
-        count: number;
-    }[];
+    drops: LootDrop[];
     source?: string;
 }
+/**
+ * Read the drops out of a `loot.granted` payload that arrived as `unknown` — a `FeedEntry.data`, a
+ * replicated event, a persisted log row. Returns `[]` for anything that is not shaped like a loot
+ * grant, so a renderer never has to guard the payload itself: `entry.data as { drops?: ... }` is the
+ * cast four separate call sites were writing, and the one that omitted the `| undefined` would have
+ * thrown on a payload-less entry.
+ */
+export declare function lootDropsOf(data: unknown): readonly LootDrop[];
 export interface InventoryAddedEvent {
     userId: string;
     item: string;
@@ -145,6 +159,11 @@ export interface ProjectileSettledEvent {
     at: [number, number, number];
     effect: string;
     hit: boolean;
+    /**
+     * True for arced/exploding shots (grenades, launchers), false for direct-fire (bullets, bolts).
+     * Straight muzzle→impact tracers only make sense for direct-fire shots, so renderers skip the arced ones.
+     */
+    ballistic: boolean;
 }
 export interface WorldItemDroppedEvent {
     instanceId: string;

package/dist/game/events.js

@@ -1,3 +1,21 @@
+/**
+ * Read the drops out of a `loot.granted` payload that arrived as `unknown` — a `FeedEntry.data`, a
+ * replicated event, a persisted log row. Returns `[]` for anything that is not shaped like a loot
+ * grant, so a renderer never has to guard the payload itself: `entry.data as { drops?: ... }` is the
+ * cast four separate call sites were writing, and the one that omitted the `| undefined` would have
+ * thrown on a payload-less entry.
+ */
+export function lootDropsOf(data) {
+    if (typeof data !== "object" || data === null)
+        return [];
+    const drops = data.drops;
+    if (!Array.isArray(drops))
+        return [];
+    return drops.filter((drop) => typeof drop === "object" &&
+        drop !== null &&
+        typeof drop.count === "number" &&
+        Number.isFinite(drop.count));
+}
 /**
  * A typed publish/subscribe bus for gameplay events that systems and HUDs subscribe to.
  *

package/dist/game/gamePhase.d.ts

@@ -16,7 +16,7 @@ export declare const GAME_PHASE_STORE_KEY = "jg.phase";
  * transition and the dock follows.
  */
 export declare function setGamePhase(ctx: GameContext, phase: GamePhase): void;
-/** Current phase; defaults to `playing` when unset so always-live games need no wiring. */
+/** Current phase; defaults to `playing` when unset — a game that runs live from boot declares that intent explicitly with `defineGame({ lifecycle: "always-live" })` rather than relying on the silent default. */
 export declare function gamePhase(ctx: GameContext): GamePhase;
 export declare function isPlaying(ctx: GameContext): boolean;
 /**

package/dist/game/gamePhase.js

@@ -11,7 +11,7 @@ export function setGamePhase(ctx, phase) {
     ctx.game.store.set(GAME_PHASE_STORE_KEY, phase);
     setPlayControlsActive(ctx, phase === "playing");
 }
-/** Current phase; defaults to `playing` when unset so always-live games need no wiring. */
+/** Current phase; defaults to `playing` when unset — a game that runs live from boot declares that intent explicitly with `defineGame({ lifecycle: "always-live" })` rather than relying on the silent default. */
 export function gamePhase(ctx) {
     const value = ctx.game.store.get(GAME_PHASE_STORE_KEY);
     return value === "menu" || value === "paused" || value === "ended" ? value : "playing";

package/dist/game/leaderboardRank.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A single input score to rank. Accepts the raw shape produced by
+ * {@link LeaderboardRow} (a `LeaderboardRow` is assignable to this) as well as a
+ * minimal `{ userId, value }` pair with an optional display `label` the game owns.
+ */
+export interface RankableRow {
+    /** Stable identity of the scoring player/profile. */
+    userId: string;
+    /** The numeric score to rank on. */
+    value: number;
+    /** Optional display name the UI shows instead of `userId`. Free string the game owns. */
+    label?: string;
+}
+/**
+ * How equal scores share ranks:
+ * - `"standard"` (competition ranking): ties share a rank and the next distinct
+ *   score skips ahead — `1, 2, 2, 4`.
+ * - `"dense"`: ties share a rank and the next distinct score is the very next
+ *   integer — `1, 2, 2, 3`.
+ */
+export type TieMode = "standard" | "dense";
+/** Options for {@link rankLeaderboard}. All optional. */
+export interface RankLeaderboardOptions {
+    /**
+     * `userId` of the local player. The matching entry gets `isLocal: true` so the
+     * renderer can highlight "you" in the table. No effect on ordering.
+     */
+    highlightUserId?: string;
+    /** Tie handling for equal scores. Default `"standard"`. */
+    tieMode?: TieMode;
+    /** Keep only the first N ranked entries (applied after ranking). Default: keep all. */
+    limit?: number;
+    /** Sort direction on `value`. `"desc"` (default) ranks the highest score #1; `"asc"` ranks the lowest #1. */
+    order?: "desc" | "asc";
+}
+/** One render-ready row of the ranked table produced by {@link rankLeaderboard}. */
+export interface RankedEntry {
+    /** 1-based rank after tie handling. */
+    rank: number;
+    /** Carried through from the input row. */
+    userId: string;
+    /** Carried through from the input row. */
+    value: number;
+    /** The display label if the input row carried one, else `undefined`. */
+    label: string | undefined;
+    /** `true` when this row shares its `value` with at least one other ranked row. */
+    isTie: boolean;
+    /** `true` when `userId === options.highlightUserId` — the local "you" row. */
+    isLocal: boolean;
+}
+/**
+ * Turn raw leaderboard rows into a render-ready ranked table. Pure and
+ * allocation-bounded: it sorts a copy by `value` (descending by default), assigns
+ * 1-based ranks with correct tie handling (`"standard"` → `1, 2, 2, 4`; `"dense"`
+ * → `1, 2, 2, 3`), flags rows that share a score (`isTie`), marks the local player
+ * (`isLocal`, via `highlightUserId`), and finally applies `limit`. Sorting is
+ * stable, so rows with equal scores keep their input order. Nothing here styles or
+ * branches on game meaning — pair it with {@link medalFor} and a game-owned theme
+ * to render a reskinnable scoreboard. Accepts a {@link LeaderboardRow}`[]` straight
+ * from `leaderboard.snapshot()`/`getTop()` since those satisfy {@link RankableRow}.
+ *
+ * @capability scoreboard pure tie-aware ranking selector over the leaderboard model — standard/dense ranks, local-entry highlight, top-N, medal tokens for a reskinnable table
+ */
+export declare function rankLeaderboard(rows: readonly RankableRow[], options?: RankLeaderboardOptions): RankedEntry[];
+/**
+ * A free-string medal token for the top-three ranks — `"gold"` (1), `"silver"`
+ * (2), `"bronze"` (3) — or `null` for any other rank. It is a semantic token, not
+ * a color: the UI maps it to an icon/color/theme, and the model never styles. Feed
+ * it a {@link RankedEntry.rank}.
+ */
+export declare function medalFor(rank: number): "gold" | "silver" | "bronze" | null;

package/dist/game/leaderboardRank.js

@@ -0,0 +1,76 @@
+/**
+ * Turn raw leaderboard rows into a render-ready ranked table. Pure and
+ * allocation-bounded: it sorts a copy by `value` (descending by default), assigns
+ * 1-based ranks with correct tie handling (`"standard"` → `1, 2, 2, 4`; `"dense"`
+ * → `1, 2, 2, 3`), flags rows that share a score (`isTie`), marks the local player
+ * (`isLocal`, via `highlightUserId`), and finally applies `limit`. Sorting is
+ * stable, so rows with equal scores keep their input order. Nothing here styles or
+ * branches on game meaning — pair it with {@link medalFor} and a game-owned theme
+ * to render a reskinnable scoreboard. Accepts a {@link LeaderboardRow}`[]` straight
+ * from `leaderboard.snapshot()`/`getTop()` since those satisfy {@link RankableRow}.
+ *
+ * @capability scoreboard pure tie-aware ranking selector over the leaderboard model — standard/dense ranks, local-entry highlight, top-N, medal tokens for a reskinnable table
+ */
+export function rankLeaderboard(rows, options = {}) {
+    const { highlightUserId, tieMode = "standard", limit, order = "desc" } = options;
+    const dir = order === "asc" ? 1 : -1;
+    // Stable sort on value in the requested direction; equal values keep input order.
+    const sorted = rows
+        .map((row, index) => ({ row, index }))
+        .sort((a, b) => {
+        const byValue = (a.row.value - b.row.value) * dir;
+        return byValue !== 0 ? byValue : a.index - b.index;
+    })
+        .map((entry) => entry.row);
+    const ranked = [];
+    let lastValue;
+    let lastRank = 0;
+    for (let i = 0; i < sorted.length; i++) {
+        const row = sorted[i];
+        let rank;
+        if (lastValue !== undefined && row.value === lastValue) {
+            // Tie: share the previous rank regardless of mode.
+            rank = lastRank;
+        }
+        else if (tieMode === "dense") {
+            rank = lastRank + 1;
+        }
+        else {
+            // Standard/competition: skip ahead by the count of rows already placed.
+            rank = i + 1;
+        }
+        // isTie: shares value with a neighbor in the sorted list.
+        const prev = sorted[i - 1];
+        const next = sorted[i + 1];
+        const isTie = (prev !== undefined && prev.value === row.value) || (next !== undefined && next.value === row.value);
+        ranked.push({
+            rank,
+            userId: row.userId,
+            value: row.value,
+            label: row.label,
+            isTie,
+            isLocal: highlightUserId !== undefined && row.userId === highlightUserId,
+        });
+        lastValue = row.value;
+        lastRank = rank;
+    }
+    return limit !== undefined && limit >= 0 ? ranked.slice(0, limit) : ranked;
+}
+/**
+ * A free-string medal token for the top-three ranks — `"gold"` (1), `"silver"`
+ * (2), `"bronze"` (3) — or `null` for any other rank. It is a semantic token, not
+ * a color: the UI maps it to an icon/color/theme, and the model never styles. Feed
+ * it a {@link RankedEntry.rank}.
+ */
+export function medalFor(rank) {
+    switch (rank) {
+        case 1:
+            return "gold";
+        case 2:
+            return "silver";
+        case 3:
+            return "bronze";
+        default:
+            return null;
+    }
+}

package/dist/game/lootTable.d.ts

@@ -39,12 +39,21 @@ export interface LootRegistry {
     has(id: string): boolean;
     roll(id: string, rng?: () => number): Drop[];
 }
+/** Options for {@link createLootRegistry} — inject a default RNG so bare `roll(id)` uses the world stream. */
+export interface LootRegistryOptions {
+    /**
+     * Default `[0,1)` stream when `roll` is called without an explicit rng.
+     * Prefer the world stream from `createGameContext` (`ctx.rng`); bare registries
+     * still fall back to `Math.random` (warning once) for portable call sites outside a game context.
+     */
+    rng?: () => number;
+}
 /**
  * Register named loot tables and roll weighted randomized drops from them.
  *
  * @capability loot-table register loot tables and roll weighted randomized drops
  */
-export declare function createLootRegistry(): LootRegistry;
+export declare function createLootRegistry(options?: LootRegistryOptions): LootRegistry;
 /**
  * Validates a loot table definition and returns it unchanged, for use with {@link createLootRegistry}.
  *