@jgengine/core 0.10.0 → 0.11.0

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/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/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) {

package/dist/game/lootPipeline.d.ts

@@ -0,0 +1,164 @@
+import type { Drop, LootEntry, LootTableDef } from "./lootTable.js";
+/**
+ * One eligible entry inside a {@link LootRollPlan}: the original table entry plus its live
+ * eligibility and effective weight/chance. Modifiers rewrite these fields; the source `entry`
+ * object is never mutated, so table definitions stay shared and reusable.
+ */
+export interface LootPlanEntry {
+    /** The untouched source entry from the table this stage rolls. */
+    entry: LootEntry;
+    /** Position of `entry` in the source table, carried through to provenance. */
+    index: number;
+    /** Effective relative pick weight (weighted mode). Starts at the entry's declared weight. */
+    weight: number;
+    /** Effective per-entry drop probability (independent mode). Starts at the entry's declared chance. */
+    chance?: number;
+    /** When `false`, the entry is gated out of this roll — excluded from the weighted total or the independent pass. */
+    eligible: boolean;
+}
+/**
+ * The mutable roll plan a stage derives from its table before rolling. Modifiers transform this —
+ * gating entries, reweighting them, or changing the roll count — instead of touching table defs.
+ */
+export interface LootRollPlan {
+    /** Source table id (for provenance) or `null` when the stage rolled an inline, unnamed table. */
+    tableId: string | null;
+    /** Weighted vs independent roll mode, inherited from the source table. */
+    mode: "weighted" | "independent";
+    /** Number of rolls to perform; a quantity modifier can raise or lower this. */
+    rolls: number;
+    /** The candidate entries with their live eligibility and effective weights/chances. */
+    entries: LootPlanEntry[];
+}
+/**
+ * A registered, id-tagged loot policy applied to one stage. `plan` transforms eligibility, weights,
+ * and roll counts before rolling (luck, difficulty, gating); `drops` post-processes the rolled drops
+ * (quantity multipliers, dedupe, caps). Neither hook mutates table definitions, and the id is recorded
+ * in provenance so a resolved drop can be traced back to the policies that shaped it.
+ */
+export interface LootModifier<TCtx = unknown> {
+    /** Stable identifier recorded in {@link LootDropProvenance.modifiers} and stage traces. */
+    id: string;
+    /** Rewrite the roll plan (eligibility, effective weights, roll count). Return the plan to apply. */
+    plan?: (plan: LootRollPlan, ctx: TCtx) => LootRollPlan;
+    /** Post-process this stage's rolled drops (scale counts, dedupe, cap). Return the drops to keep. */
+    drops?: (drops: Drop[], ctx: TCtx) => Drop[];
+}
+/**
+ * How a stage folds its rolled drops into the accumulating result: `"contribute"` appends,
+ * `"fallback"` rolls only when nothing has dropped yet, `"replace"` discards prior drops and
+ * overrides with its own (quest/boss overrides).
+ */
+export type LootStageKind = "contribute" | "fallback" | "replace";
+/**
+ * One ordered step in a {@link LootPipelineDef}: a source pool (a table id or inline table), an
+ * optional context gate, a fold mode, and the modifiers that reshape its roll. Stages compose the
+ * genre concepts — world pool, dedicated pool, luck, pity — without any of them living in core.
+ */
+export interface LootStage<TCtx = unknown> {
+    /** Stable stage identifier recorded in provenance and traces. */
+    id: string;
+    /** Source pool: a table id resolved against the pipeline's resolver, or an inline table definition. */
+    table: string | LootTableDef;
+    /** Fold mode; defaults to `"contribute"`. */
+    kind?: LootStageKind;
+    /** Context gate — when it returns `false` the stage is skipped and traced with reason `"gate-false"`. */
+    when?: (ctx: TCtx) => boolean;
+    /** Modifiers applied in order to this stage's roll. */
+    modifiers?: LootModifier<TCtx>[];
+}
+/**
+ * A named, ordered loot-resolution pipeline: the stages to run plus result-shaping policy
+ * (duplicate stacking, a total drop cap). Serializable except for its stage gate/modifier functions,
+ * mirroring how {@link LootTableDef} entries may carry a `generate` function.
+ */
+export interface LootPipelineDef<TCtx = unknown> {
+    id: string;
+    /** Stages run in array order — the deterministic resolution order. */
+    stages: LootStage<TCtx>[];
+    /** When `true`, drops of the same item/currency are merged into one entry with summed counts. */
+    stack?: boolean;
+    /** Optional hard cap on the number of resolved drops; extras are trimmed and the cap is traced. */
+    maxDrops?: number;
+}
+/** The caller-owned context, injected RNG, and optional seed threaded through a single resolution. */
+export interface LootResolveContext<TCtx = unknown> {
+    /** Caller-owned, typed resolution context read by stage gates and modifiers. */
+    ctx: TCtx;
+    /** Injected randomness — seed it for deterministic, server-authoritative replay. */
+    rng: () => number;
+    /** Optional seed value recorded verbatim in {@link LootResolution.seed} for replay bookkeeping. */
+    seed?: number | string;
+}
+/** Why one drop is in the result: the stage/table/entry that produced it, its weights, and the modifiers that shaped it. */
+export interface LootDropProvenance {
+    /** Stage that produced the drop. */
+    stageId: string;
+    /** Source table id, or `null` for an inline table. */
+    tableId: string | null;
+    /** Index of the winning entry in its source table. */
+    entryIndex: number;
+    /** The granted item id, when the drop is an item. */
+    item?: string;
+    /** The granted currency id, when the drop is currency. */
+    currency?: string;
+    /** The entry's declared weight before modifiers (weighted mode). */
+    originalWeight?: number;
+    /** The entry's effective weight after modifiers (weighted mode). */
+    effectiveWeight?: number;
+    /** The entry's declared chance before modifiers (independent mode). */
+    originalChance?: number;
+    /** The entry's effective chance after modifiers (independent mode). */
+    effectiveChance?: number;
+    /** Ids of the modifiers that ran on the producing stage, in application order. */
+    modifiers: string[];
+}
+/** The disposition of a stage after resolution — did it roll, get gated, fall through, override, or find nothing. */
+export type LootStageStatus = "rolled" | "skipped" | "empty" | "replaced" | "fell-through";
+/** Per-stage record of what happened during resolution, for debugging and replay auditing. */
+export interface LootStageTrace {
+    stageId: string;
+    tableId: string | null;
+    kind: LootStageKind;
+    status: LootStageStatus;
+    /** Human-readable reason for a non-`"rolled"` status (e.g. `"gate-false"`, `"empty-pool"`, `"prior-drops-present"`). */
+    reason?: string;
+    /** Ids of modifiers applied on this stage. */
+    modifiers: string[];
+    /** Drops this stage contributed to the final result. */
+    dropCount: number;
+}
+/** The fully serializable outcome of a resolution: the drops, their provenance, per-stage traces, and the replay seed. */
+export interface LootResolution {
+    drops: Drop[];
+    provenance: LootDropProvenance[];
+    stages: LootStageTrace[];
+    seed?: number | string;
+}
+/** A resolved, reusable loot pipeline. Call {@link LootPipeline.resolve} with a per-drop context and RNG. */
+export interface LootPipeline<TCtx = unknown> {
+    readonly id: string;
+    resolve(context: LootResolveContext<TCtx>): LootResolution;
+}
+/** Dependencies a pipeline needs at build time — chiefly how to turn a table id into its definition. */
+export interface LootPipelineDeps {
+    /** Resolve a table id to its definition. Required only when stages reference tables by id. */
+    resolveTable?: (id: string) => LootTableDef | undefined;
+}
+/**
+ * Validate a loot pipeline definition and return it unchanged, for use with {@link createLootPipeline}.
+ *
+ * @capability loot-pipeline validate a composable loot-resolution pipeline definition
+ */
+export declare function defineLootPipeline<TCtx = unknown>(def: LootPipelineDef<TCtx>): LootPipelineDef<TCtx>;
+/**
+ * Build a composable loot-resolution pipeline: ordered source pools, context gates, fallbacks when a
+ * pool yields nothing, roll modifiers (luck, quantity, difficulty) applied as registered policies, and
+ * full provenance for every drop (stage, table, entry, original vs effective weights, modifier ids, seed).
+ * Rolling consumes the injected RNG in the same order as the base loot table, so a seeded resolution is
+ * deterministic and server-authoritatively replayable. Genre concepts (world, dedicated, boss, luck,
+ * rarity, pity) stay out of core and ship as stage/modifier compositions.
+ *
+ * @capability loot-pipeline compose ordered loot pools with fallbacks, roll modifiers, and provenance
+ */
+export declare function createLootPipeline<TCtx = unknown>(def: LootPipelineDef<TCtx>, deps?: LootPipelineDeps): LootPipeline<TCtx>;

package/dist/game/lootPipeline.js

@@ -0,0 +1,216 @@
+function tableModeOf(def) {
+    return def.mode ?? "weighted";
+}
+function buildPlan(def) {
+    return {
+        tableId: def.id,
+        mode: tableModeOf(def),
+        rolls: def.rolls ?? 1,
+        entries: def.entries.map((entry, index) => {
+            const planEntry = { entry, index, weight: entry.weight ?? 0, eligible: true };
+            if (entry.chance !== undefined)
+                planEntry.chance = entry.chance;
+            return planEntry;
+        }),
+    };
+}
+function resolveCount(count, rng) {
+    if (typeof count === "number")
+        return count;
+    const [min, max] = count;
+    return min + Math.floor(rng() * (max - min + 1));
+}
+function dropFromEntry(entry, count, rng) {
+    if (entry.generate !== undefined)
+        return { item: entry.generate(rng), count };
+    return entry.item !== undefined ? { item: entry.item, count } : { currency: entry.currency, count };
+}
+/** Pick one eligible plan entry by effective weight, mirroring `createLootRegistry`'s weighted algorithm and RNG order. */
+function pickWeighted(entries, rng) {
+    const eligible = entries.filter((candidate) => candidate.eligible && candidate.weight > 0);
+    if (eligible.length === 0)
+        return null;
+    const total = eligible.reduce((sum, candidate) => sum + candidate.weight, 0);
+    let roll = rng() * total;
+    for (const candidate of eligible) {
+        roll -= candidate.weight;
+        if (roll < 0)
+            return candidate;
+    }
+    return eligible[eligible.length - 1] ?? null;
+}
+/** Roll a prepared plan into drops, consuming `rng` in the same order as the base loot table primitive. */
+function rollPlan(plan, rng) {
+    const rolled = [];
+    for (let roll = 0; roll < plan.rolls; roll += 1) {
+        if (plan.mode === "independent") {
+            for (const planEntry of plan.entries) {
+                if (!planEntry.eligible)
+                    continue;
+                if (rng() < (planEntry.chance ?? 0)) {
+                    const count = resolveCount(planEntry.entry.count, rng);
+                    rolled.push({ drop: dropFromEntry(planEntry.entry, count, rng), planEntry });
+                }
+            }
+        }
+        else {
+            const picked = pickWeighted(plan.entries, rng);
+            if (picked === null)
+                continue;
+            const count = resolveCount(picked.entry.count, rng);
+            rolled.push({ drop: dropFromEntry(picked.entry, count, rng), planEntry: picked });
+        }
+    }
+    return rolled;
+}
+function stackDrops(drops) {
+    const order = [];
+    const byKey = new Map();
+    for (const drop of drops) {
+        const key = drop.item !== undefined ? `item:${drop.item}` : `currency:${drop.currency}`;
+        const existing = byKey.get(key);
+        if (existing === undefined) {
+            byKey.set(key, { ...drop });
+            order.push(key);
+        }
+        else {
+            existing.count += drop.count;
+        }
+    }
+    return order.map((key) => byKey.get(key));
+}
+function assertValidPipeline(def) {
+    if (def.stages.length === 0) {
+        throw new Error(`loot pipeline "${def.id}" must have at least one stage`);
+    }
+    const seen = new Set();
+    for (const stage of def.stages) {
+        if (seen.has(stage.id)) {
+            throw new Error(`loot pipeline "${def.id}" has duplicate stage id "${stage.id}"`);
+        }
+        seen.add(stage.id);
+    }
+    if (def.maxDrops !== undefined && (!Number.isInteger(def.maxDrops) || def.maxDrops < 0)) {
+        throw new Error(`loot pipeline "${def.id}" maxDrops must be a non-negative integer`);
+    }
+}
+/**
+ * Validate a loot pipeline definition and return it unchanged, for use with {@link createLootPipeline}.
+ *
+ * @capability loot-pipeline validate a composable loot-resolution pipeline definition
+ */
+export function defineLootPipeline(def) {
+    assertValidPipeline(def);
+    return def;
+}
+/**
+ * Build a composable loot-resolution pipeline: ordered source pools, context gates, fallbacks when a
+ * pool yields nothing, roll modifiers (luck, quantity, difficulty) applied as registered policies, and
+ * full provenance for every drop (stage, table, entry, original vs effective weights, modifier ids, seed).
+ * Rolling consumes the injected RNG in the same order as the base loot table, so a seeded resolution is
+ * deterministic and server-authoritatively replayable. Genre concepts (world, dedicated, boss, luck,
+ * rarity, pity) stay out of core and ship as stage/modifier compositions.
+ *
+ * @capability loot-pipeline compose ordered loot pools with fallbacks, roll modifiers, and provenance
+ */
+export function createLootPipeline(def, deps = {}) {
+    assertValidPipeline(def);
+    function resolveStageTable(stage) {
+        if (typeof stage.table !== "string")
+            return stage.table;
+        const resolved = deps.resolveTable?.(stage.table);
+        if (resolved === undefined) {
+            throw new Error(`loot pipeline "${def.id}" stage "${stage.id}" references unknown table "${stage.table}"`);
+        }
+        return resolved;
+    }
+    return {
+        id: def.id,
+        resolve({ ctx, rng, seed }) {
+            let drops = [];
+            let provenance = [];
+            const traces = [];
+            for (const stage of def.stages) {
+                const kind = stage.kind ?? "contribute";
+                const modifierIds = (stage.modifiers ?? []).map((modifier) => modifier.id);
+                if (stage.when !== undefined && !stage.when(ctx)) {
+                    traces.push({ stageId: stage.id, tableId: null, kind, status: "skipped", reason: "gate-false", modifiers: modifierIds, dropCount: 0 });
+                    continue;
+                }
+                if (kind === "fallback" && drops.length > 0) {
+                    traces.push({ stageId: stage.id, tableId: null, kind, status: "fell-through", reason: "prior-drops-present", modifiers: modifierIds, dropCount: 0 });
+                    continue;
+                }
+                const tableDef = resolveStageTable(stage);
+                let plan = buildPlan(tableDef);
+                for (const modifier of stage.modifiers ?? []) {
+                    if (modifier.plan !== undefined)
+                        plan = modifier.plan(plan, ctx);
+                }
+                const rolled = rollPlan(plan, rng);
+                let stageDrops = rolled.map((entry) => entry.drop);
+                for (const modifier of stage.modifiers ?? []) {
+                    if (modifier.drops !== undefined)
+                        stageDrops = modifier.drops(stageDrops, ctx);
+                }
+                // Provenance tracks the rolled entries and their lineage; drop-only modifiers (dedupe/cap) may
+                // reshape counts, so provenance is emitted from the rolls that still carry entry indices.
+                const stageProvenance = rolled.map((entry) => {
+                    const record = {
+                        stageId: stage.id,
+                        tableId: plan.tableId,
+                        entryIndex: entry.planEntry.index,
+                        modifiers: modifierIds,
+                    };
+                    if (entry.drop.item !== undefined)
+                        record.item = entry.drop.item;
+                    if (entry.drop.currency !== undefined)
+                        record.currency = entry.drop.currency;
+                    const source = entry.planEntry.entry;
+                    if (plan.mode === "weighted") {
+                        record.originalWeight = source.weight ?? 0;
+                        record.effectiveWeight = entry.planEntry.weight;
+                    }
+                    else {
+                        record.originalChance = source.chance ?? 0;
+                        record.effectiveChance = entry.planEntry.chance ?? 0;
+                    }
+                    return record;
+                });
+                const status = stageDrops.length === 0 ? "empty" : kind === "replace" ? "replaced" : "rolled";
+                const trace = {
+                    stageId: stage.id,
+                    tableId: plan.tableId,
+                    kind,
+                    status,
+                    modifiers: modifierIds,
+                    dropCount: stageDrops.length,
+                };
+                if (status === "empty")
+                    trace.reason = "empty-pool";
+                traces.push(trace);
+                if (stageDrops.length === 0)
+                    continue;
+                if (kind === "replace") {
+                    drops = stageDrops;
+                    provenance = stageProvenance;
+                }
+                else {
+                    drops = [...drops, ...stageDrops];
+                    provenance = [...provenance, ...stageProvenance];
+                }
+            }
+            if (def.stack === true)
+                drops = stackDrops(drops);
+            if (def.maxDrops !== undefined && drops.length > def.maxDrops) {
+                drops = drops.slice(0, def.maxDrops);
+                provenance = provenance.slice(0, def.maxDrops);
+                traces.push({ stageId: "@cap", tableId: null, kind: "contribute", status: "skipped", reason: `capped-at-${def.maxDrops}`, modifiers: [], dropCount: 0 });
+            }
+            const resolution = { drops, provenance, stages: traces };
+            if (seed !== undefined)
+                resolution.seed = seed;
+            return resolution;
+        },
+    };
+}

package/dist/game/lootTable.d.ts

@@ -1,7 +1,15 @@
-/** One possible drop in a {@link LootTableDef} — an item or currency, its count range, and its odds. */
+/** One possible drop in a {@link LootTableDef} — an item, currency, or generated item, its count range, and its odds. */
 export interface LootEntry {
     item?: string;
     currency?: string;
+    /**
+     * Roll a procedurally generated item instead of a static catalog id (a rolled unique gun, an
+     * affixed relic) — invoked with the roll's rng and returning the generated item's runtime id, the
+     * one `content.itemById` and inventories treat exactly like a static id (#536.1). Compose it with
+     * `item/itemInstanceRegistry`'s `proceduralLootEntry` over any procedural roller (e.g. `item/affix`'s
+     * `createAffixRoller`).
+     */
+    generate?: (rng: () => number) => string;
     count: number | [number, number];
     /** Relative pick weight — required in `"weighted"` mode, forbidden in `"independent"` mode. */
     weight?: number;
@@ -31,8 +39,17 @@ export interface LootRegistry {
     has(id: string): boolean;
     roll(id: string, rng?: () => number): Drop[];
 }
+/**
+ * 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;
-/** Validates a loot table definition and returns it unchanged, for use with {@link createLootRegistry}. */
+/**
+ * Validates a loot table definition and returns it unchanged, for use with {@link createLootRegistry}.
+ *
+ * @capability loot-table validate a loot table definition for use with the registry
+ */
 export declare function lootTable(def: LootTableDef): LootTableDef;
 export declare function grantDrops(drops: Drop[], appliers: {
     putItem: (itemId: string, count: number) => unknown;

package/dist/game/lootTable.js

@@ -1,8 +1,7 @@
 function assertValidEntry(entry, mode) {
-    const hasItem = entry.item !== undefined;
-    const hasCurrency = entry.currency !== undefined;
-    if (hasItem === hasCurrency) {
-        throw new Error("loot entry must have exactly one of item or currency");
+    const kinds = [entry.item !== undefined, entry.currency !== undefined, entry.generate !== undefined].filter(Boolean).length;
+    if (kinds !== 1) {
+        throw new Error("loot entry must have exactly one of item, currency, or generate");
     }
     if (mode === "weighted") {
         if (entry.chance !== undefined) {
@@ -45,8 +44,15 @@ function pickEntry(entries, rng) {
 }
 function rollEntry(entry, rng) {
     const count = resolveCount(entry.count, rng);
+    if (entry.generate !== undefined)
+        return { item: entry.generate(rng), count };
     return entry.item !== undefined ? { item: entry.item, count } : { currency: entry.currency, count };
 }
+/**
+ * Register named loot tables and roll weighted randomized drops from them.
+ *
+ * @capability loot-table register loot tables and roll weighted randomized drops
+ */
 export function createLootRegistry() {
     const tables = new Map();
     return {
@@ -82,7 +88,11 @@ export function createLootRegistry() {
         },
     };
 }
-/** Validates a loot table definition and returns it unchanged, for use with {@link createLootRegistry}. */
+/**
+ * Validates a loot table definition and returns it unchanged, for use with {@link createLootRegistry}.
+ *
+ * @capability loot-table validate a loot table definition for use with the registry
+ */
 export function lootTable(def) {
     assertValidDef(def);
     return def;

package/dist/game/objectives.d.ts

@@ -0,0 +1,43 @@
+/** Whether a metric must reach up to a target or stay down under it. */
+export type ThresholdDirection = "atLeast" | "atMost";
+/** A live-metric goal: hit `target` from the required `direction` (defaults to `atLeast`). */
+export interface ThresholdObjective {
+    id: string;
+    target: number;
+    direction?: ThresholdDirection;
+}
+/** Evaluated state of one {@link ThresholdObjective} against a current metric value. */
+export interface ObjectiveStatus {
+    id: string;
+    value: number;
+    target: number;
+    direction: ThresholdDirection;
+    /** True when the value satisfies the target from the required direction. */
+    met: boolean;
+    /** Fraction toward the target, 0..1 (1 once met). */
+    progress: number;
+}
+/**
+ * Evaluate a single live-metric objective: is `value` at least (or at most) the target, and how far along.
+ * Unlike an event counter, this reads a continuously-changing metric — population, approval, pollution —
+ * the objective shape city-builders and management sims track every tick.
+ *
+ * @capability objectives check progress of a threshold objective against a live metric
+ */
+export declare function evaluateObjective(objective: ThresholdObjective, value: number): ObjectiveStatus;
+/** Rolled-up state across a set of objectives. */
+export interface ObjectiveSummary {
+    statuses: ObjectiveStatus[];
+    /** How many objectives are met. */
+    met: number;
+    total: number;
+    /** True when every objective is met. */
+    complete: boolean;
+    /** Mean progress across all objectives, 0..1. */
+    progress: number;
+}
+/**
+ * Evaluate every objective against current metric values (a lookup map or function) and roll them up into
+ * a met-count, completion flag, and mean progress — the brief/charter panel every sim renders.
+ */
+export declare function evaluateObjectives(objectives: readonly ThresholdObjective[], values: Readonly<Record<string, number>> | ((id: string) => number)): ObjectiveSummary;