@jgengine/core 0.28.0 → 0.30.0

package/dist/progression/standing.js

@@ -0,0 +1,151 @@
+import { createReputationLedger, DEFAULT_REPUTATION_TIERS, } from "../faction/reputation.js";
+function check(condition, message) {
+    if (!condition)
+        throw new RangeError(message);
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+/** Check authored standing content before use; throws `RangeError` naming the offending field. */
+export function assertStandingConfig(config) {
+    const trackIds = new Set();
+    for (const track of config.tracks) {
+        const id = track.id.trim();
+        check(id !== "", "Standing track id must not be empty");
+        check(!trackIds.has(id), `Standing track "${id}" is declared twice`);
+        trackIds.add(id);
+        if (track.min !== undefined)
+            check(isFiniteNumber(track.min), `Standing track "${id}" min must be finite`);
+        if (track.max !== undefined)
+            check(isFiniteNumber(track.max), `Standing track "${id}" max must be finite`);
+        check(track.min === undefined || track.max === undefined || track.min <= track.max, `Standing track "${id}" needs min <= max`);
+        if (track.initial !== undefined) {
+            check(isFiniteNumber(track.initial), `Standing track "${id}" initial must be finite`);
+            check((track.min === undefined || track.initial >= track.min) && (track.max === undefined || track.initial <= track.max), `Standing track "${id}" initial ${track.initial} is outside its bounds`);
+        }
+        const tiers = track.tiers ?? DEFAULT_REPUTATION_TIERS;
+        check(tiers.length > 0, `Standing track "${id}" needs at least one tier`);
+        const tierIds = new Set();
+        for (const tier of tiers) {
+            check(tier.id.trim() !== "", `Standing track "${id}" has a tier with an empty id`);
+            check(!tierIds.has(tier.id), `Standing track "${id}" declares tier "${tier.id}" twice`);
+            check(isFiniteNumber(tier.min), `Standing track "${id}" tier "${tier.id}" min must be finite`);
+            tierIds.add(tier.id);
+        }
+    }
+    const outcomeIds = new Set();
+    for (const outcome of config.outcomes ?? []) {
+        const id = outcome.id.trim();
+        check(id !== "", "Standing outcome id must not be empty");
+        check(!outcomeIds.has(id), `Standing outcome "${id}" is declared twice`);
+        outcomeIds.add(id);
+        const impacts = Object.entries(outcome.impacts);
+        check(impacts.length > 0, `Standing outcome "${id}" moves no track`);
+        for (const [trackId, delta] of impacts) {
+            check(trackIds.has(trackId), `Standing outcome "${id}" names unknown track "${trackId}"`);
+            check(isFiniteNumber(delta), `Standing outcome "${id}" impact on "${trackId}" must be finite`);
+        }
+    }
+}
+/**
+ * Per-faction or per-district standing that rises and falls from named outcomes, over authored
+ * tracks. Numbers live in the shared reputation ledger (`faction/reputation`); this adds the
+ * authored outcome table, tier-per-track and the one snapshot a save stores. An outcome id or
+ * track id that resolves to nothing throws at the call, so authored content fails loudly.
+ *
+ * @capability standing per-track standing moved by authored outcomes, with tiers and one snapshot
+ */
+export function createStanding(config) {
+    assertStandingConfig(config);
+    const tracks = new Map();
+    for (const track of config.tracks)
+        tracks.set(track.id, track);
+    const outcomes = new Map();
+    for (const outcome of config.outcomes ?? [])
+        outcomes.set(outcome.id, outcome);
+    const ledgers = new Map();
+    for (const track of config.tracks) {
+        ledgers.set(track.id, createReputationLedger({
+            tiers: track.tiers ?? DEFAULT_REPUTATION_TIERS,
+            initial: { [track.id]: track.initial ?? 0 },
+            ...(track.min === undefined ? {} : { min: track.min }),
+            ...(track.max === undefined ? {} : { max: track.max }),
+        }));
+    }
+    function ledgerFor(trackId) {
+        const ledger = ledgers.get(trackId);
+        if (ledger === undefined)
+            throw new RangeError(`Standing track "${trackId}" is not authored`);
+        return ledger;
+    }
+    return {
+        tracks: () => config.tracks.slice(),
+        hasTrack: (trackId) => tracks.has(trackId),
+        hasOutcome: (outcomeId) => outcomes.has(outcomeId),
+        standing(actorId, trackId) {
+            return ledgerFor(trackId).standing(actorId, trackId);
+        },
+        tier: (actorId, trackId) => ledgerFor(trackId).tier(actorId, trackId),
+        standings(actorId) {
+            const out = {};
+            for (const trackId of ledgers.keys())
+                out[trackId] = ledgerFor(trackId).standing(actorId, trackId);
+            return out;
+        },
+        apply(actorId, outcomeId) {
+            const outcome = outcomes.get(outcomeId);
+            if (outcome === undefined)
+                throw new RangeError(`Standing outcome "${outcomeId}" is not authored`);
+            const changes = [];
+            for (const [trackId, delta] of Object.entries(outcome.impacts)) {
+                const ledger = ledgerFor(trackId);
+                const before = ledger.standing(actorId, trackId);
+                const previousTier = ledger.tier(actorId, trackId).id;
+                ledger.gain(actorId, trackId, delta);
+                const after = ledger.standing(actorId, trackId);
+                changes.push({ trackId, before, after, delta: after - before, previousTier, tier: ledger.tier(actorId, trackId).id });
+            }
+            return changes;
+        },
+        adjust(actorId, trackId, delta) {
+            const ledger = ledgerFor(trackId);
+            const before = ledger.standing(actorId, trackId);
+            const previousTier = ledger.tier(actorId, trackId).id;
+            ledger.gain(actorId, trackId, delta);
+            const after = ledger.standing(actorId, trackId);
+            return { trackId, before, after, delta: after - before, previousTier, tier: ledger.tier(actorId, trackId).id };
+        },
+        meets(actorId, requirement) {
+            const value = ledgerFor(requirement.trackId).standing(actorId, requirement.trackId);
+            return (requirement.min === undefined || value >= requirement.min) && (requirement.max === undefined || value <= requirement.max);
+        },
+        snapshot() {
+            const records = {};
+            for (const [trackId, ledger] of ledgers) {
+                for (const [actorId, row] of Object.entries(ledger.snapshot().records)) {
+                    const target = records[actorId] ?? (records[actorId] = {});
+                    const value = row[trackId];
+                    if (value !== undefined)
+                        target[trackId] = value;
+                }
+            }
+            return { records };
+        },
+        restore(next) {
+            const byTrack = new Map();
+            for (const [actorId, row] of Object.entries(next.records ?? {})) {
+                for (const [trackId, value] of Object.entries(row)) {
+                    if (!ledgers.has(trackId) || !isFiniteNumber(value))
+                        continue;
+                    const target = byTrack.get(trackId);
+                    if (target === undefined)
+                        byTrack.set(trackId, { [actorId]: { [trackId]: value } });
+                    else
+                        target[actorId] = { [trackId]: value };
+                }
+            }
+            for (const [trackId, ledger] of ledgers)
+                ledger.restore({ records: byTrack.get(trackId) ?? {} });
+        },
+    };
+}

package/dist/progression/upgrades.d.ts

@@ -0,0 +1,70 @@
+import { type Curve } from "../game/progression.js";
+import type { Standing, StandingRequirement } from "./standing.js";
+/**
+ * One upgrade node. Its price is the shared progression {@link Curve} evaluated at the rank being
+ * bought, so a game authors one curve and every rank of every node follows it.
+ */
+export interface UpgradeNodeDef {
+    id: string;
+    label?: string;
+    /** Cost of rank `n`, priced by this curve at `n` (1-based). */
+    cost: Curve;
+    /** Ranks purchasable (default `1`). */
+    maxRank?: number;
+    /** Node ids that must be owned before this one can be bought. */
+    requires?: readonly string[];
+    standing?: StandingRequirement;
+}
+/** Plain JSON state: node id → ranks owned. Nodes at rank `0` are absent. */
+export interface UpgradeState {
+    ranks: Readonly<Record<string, number>>;
+}
+/** Why a purchase was refused; the tree is left untouched on any rejection. */
+export type UpgradeRejection = "unknown-node" | "max-rank" | "missing-prerequisites" | "standing" | "insufficient-funds";
+/** Result of {@link UpgradeTree.buy}: the rank reached and what it cost, or why it was refused. */
+export type UpgradeBuy = {
+    ok: true;
+    nodeId: string;
+    rank: number;
+    cost: number;
+} | {
+    ok: false;
+    reason: UpgradeRejection;
+};
+/** Authored upgrade nodes with a per-node cost curve, prerequisites, a standing gate and one snapshot. */
+export interface UpgradeTree {
+    nodes(): readonly UpgradeNodeDef[];
+    node(nodeId: string): UpgradeNodeDef | null;
+    /** Ranks owned for `nodeId`; `0` when unknown or unowned. */
+    rank(nodeId: string): number;
+    maxRank(nodeId: string): number;
+    /** Price of `rank` (default: the next rank), or `null` when unknown or past the cap. */
+    costOf(nodeId: string, rank?: number): number | null;
+    /** What buying the next rank needs, without changing anything. */
+    canBuy(nodeId: string, actorId: string): UpgradeBuy;
+    /** Buy the next rank, charging `pay` only after every gate passes. */
+    buy(nodeId: string, actorId: string, pay: (cost: number) => boolean): UpgradeBuy;
+    owned(): readonly string[];
+    spendTotal(): number;
+    snapshot(): UpgradeState;
+    restore(next: UpgradeState): void;
+}
+/** Authored nodes plus the standing a node's requirement reads. */
+export interface UpgradeTreeConfig {
+    nodes: readonly UpgradeNodeDef[];
+    /** The standing a node's requirement reads, for both validation and purchase. */
+    standing?: Pick<Standing, "hasTrack" | "standing">;
+    /** Rehydrate from a prior {@link UpgradeTree.snapshot}. */
+    state?: UpgradeState;
+}
+/** Check authored upgrade nodes; throws `RangeError` naming the offending node or field. */
+export declare function assertUpgrades(config: UpgradeTreeConfig): void;
+/**
+ * An upgrade tree whose prices come from the shared curve primitive: each node authors one cost
+ * curve, each rank is that curve at the rank, and a purchase passes prerequisites, a standing gate
+ * and the caller's own payment step. State is one rank map that JSON round-trips, so a career save
+ * stores what a player paid for rather than the arithmetic behind it.
+ *
+ * @capability upgrade-tree ranked upgrades priced by a cost curve, gated by prerequisites and standing
+ */
+export declare function createUpgradeTree(config: UpgradeTreeConfig): UpgradeTree;

package/dist/progression/upgrades.js

@@ -0,0 +1,128 @@
+import { evalCurve } from "../game/progression.js";
+function check(condition, message) {
+    if (!condition)
+        throw new RangeError(message);
+}
+/** Check authored upgrade nodes; throws `RangeError` naming the offending node or field. */
+export function assertUpgrades(config) {
+    const nodes = new Set();
+    for (const node of config.nodes) {
+        const id = node.id.trim();
+        check(id !== "", "Upgrade node id must not be empty");
+        check(!nodes.has(id), `Upgrade node "${id}" is declared twice`);
+        nodes.add(id);
+        const maxRank = node.maxRank ?? 1;
+        check(Number.isInteger(maxRank) && maxRank >= 1, `Upgrade node "${id}" maxRank must be an integer >= 1`);
+        for (let rank = 1; rank <= maxRank; rank += 1) {
+            const cost = evalCurve(node.cost, rank);
+            check(Number.isFinite(cost) && cost >= 0, `Upgrade node "${id}" cost at rank ${rank} must be finite and >= 0`);
+        }
+        const standing = node.standing;
+        if (standing !== undefined) {
+            check(standing.trackId.trim() !== "", `Upgrade node "${id}" names an empty standing track`);
+            check(config.standing === undefined || config.standing.hasTrack(standing.trackId), `Upgrade node "${id}" reads unknown standing track "${standing.trackId}"`);
+            check(standing.min === undefined || standing.max === undefined || standing.min <= standing.max, `Upgrade node "${id}" needs standing min <= max`);
+        }
+    }
+    for (const node of config.nodes) {
+        check(!(node.requires ?? []).includes(node.id), `Upgrade node "${node.id}" requires itself`);
+        for (const required of node.requires ?? []) {
+            check(nodes.has(required), `Upgrade node "${node.id}" requires unknown node "${required}"`);
+        }
+    }
+}
+/**
+ * An upgrade tree whose prices come from the shared curve primitive: each node authors one cost
+ * curve, each rank is that curve at the rank, and a purchase passes prerequisites, a standing gate
+ * and the caller's own payment step. State is one rank map that JSON round-trips, so a career save
+ * stores what a player paid for rather than the arithmetic behind it.
+ *
+ * @capability upgrade-tree ranked upgrades priced by a cost curve, gated by prerequisites and standing
+ */
+export function createUpgradeTree(config) {
+    assertUpgrades(config);
+    const definitions = config.nodes.slice();
+    const byId = new Map();
+    for (const node of definitions)
+        byId.set(node.id, node);
+    const ranks = new Map();
+    let spent = 0;
+    function load(state) {
+        ranks.clear();
+        spent = 0;
+        for (const [nodeId, rank] of Object.entries(state.ranks ?? {})) {
+            const node = byId.get(nodeId);
+            if (node === undefined || !Number.isInteger(rank) || rank <= 0)
+                continue;
+            const capped = Math.min(rank, node.maxRank ?? 1);
+            ranks.set(nodeId, capped);
+            for (let index = 1; index <= capped; index += 1)
+                spent += evalCurve(node.cost, index);
+        }
+    }
+    if (config.state !== undefined)
+        load(config.state);
+    const rankOf = (nodeId) => ranks.get(nodeId) ?? 0;
+    function costAt(node, rank) {
+        if (!Number.isInteger(rank) || rank < 1 || rank > (node.maxRank ?? 1))
+            return null;
+        return evalCurve(node.cost, rank);
+    }
+    function checkBuy(node, actorId) {
+        const current = rankOf(node.id);
+        if (current >= (node.maxRank ?? 1))
+            return { ok: false, reason: "max-rank" };
+        const missing = (node.requires ?? []).filter((required) => rankOf(required) < 1);
+        if (missing.length > 0)
+            return { ok: false, reason: "missing-prerequisites" };
+        const standing = node.standing;
+        if (standing !== undefined) {
+            const reader = config.standing;
+            if (reader === undefined)
+                return { ok: false, reason: "standing" };
+            const value = reader.standing(actorId, standing.trackId);
+            if ((standing.min !== undefined && value < standing.min) || (standing.max !== undefined && value > standing.max)) {
+                return { ok: false, reason: "standing" };
+            }
+        }
+        const cost = costAt(node, current + 1);
+        if (cost === null)
+            return { ok: false, reason: "max-rank" };
+        return { ok: true, nodeId: node.id, rank: current + 1, cost };
+    }
+    return {
+        nodes: () => definitions.slice(),
+        node: (nodeId) => byId.get(nodeId) ?? null,
+        rank: rankOf,
+        maxRank: (nodeId) => byId.get(nodeId)?.maxRank ?? 0,
+        costOf(nodeId, rank) {
+            const node = byId.get(nodeId);
+            if (node === undefined)
+                return null;
+            return costAt(node, rank ?? rankOf(nodeId) + 1);
+        },
+        canBuy: (nodeId, actorId) => {
+            const node = byId.get(nodeId);
+            if (node === undefined)
+                return { ok: false, reason: "unknown-node" };
+            return checkBuy(node, actorId);
+        },
+        buy(nodeId, actorId, pay) {
+            const node = byId.get(nodeId);
+            if (node === undefined)
+                return { ok: false, reason: "unknown-node" };
+            const checkResult = checkBuy(node, actorId);
+            if (!checkResult.ok)
+                return checkResult;
+            if (!pay(checkResult.cost))
+                return { ok: false, reason: "insufficient-funds" };
+            ranks.set(nodeId, checkResult.rank);
+            spent += checkResult.cost;
+            return checkResult;
+        },
+        owned: () => Array.from(ranks.keys()),
+        spendTotal: () => spent,
+        snapshot: () => ({ ranks: Object.fromEntries(ranks) }),
+        restore: load,
+    };
+}

package/dist/ui/accessibility.d.ts

@@ -29,6 +29,14 @@ export declare function reducedMotionDuration(state: AccessibilityState, ms: num
  * maps to `null` (no filter). Consumed by the React `ColorblindFilters` defs.
  */
 export declare const COLORBLIND_MATRICES: Record<ColorblindMode, string | null>;
+/**
+ * The CSS filter that applies `mode` to one rendered frame — a `url(#jg-cb-<mode>)` reference to the
+ * `feColorMatrix` defs {@link COLORBLIND_MATRICES} drives. `"none"` maps to `null` (no filter), so a
+ * caller can spread it onto the canvas alone and leave HUD and menu text at its own contrast.
+ *
+ * @capability colorblind-frame-filter resolve a colorblind mode to the CSS filter for the 3D frame alone
+ */
+export declare function colorblindFrameFilter(mode: ColorblindMode): string | null;
 /** Observable, serializable accessibility-preferences store. */
 export interface AccessibilityStore {
     get(): AccessibilityState;

package/dist/ui/accessibility.js

@@ -32,6 +32,20 @@ export const COLORBLIND_MATRICES = {
     tritanopia: "0.95 0.05 0 0 0  0 0.433 0.567 0 0  0 0.475 0.525 0 0  0 0 0 1 0",
     grayscale: "0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0 0 0 1 0",
 };
+/**
+ * The CSS filter that applies `mode` to one rendered frame — a `url(#jg-cb-<mode>)` reference to the
+ * `feColorMatrix` defs {@link COLORBLIND_MATRICES} drives. `"none"` maps to `null` (no filter), so a
+ * caller can spread it onto the canvas alone and leave HUD and menu text at its own contrast.
+ *
+ * @capability colorblind-frame-filter resolve a colorblind mode to the CSS filter for the 3D frame alone
+ */
+export function colorblindFrameFilter(mode) {
+    const matrix = COLORBLIND_MATRICES[mode];
+    // An unknown id at runtime would reference a filter that does not exist, and a broken `url()` filter hides the element.
+    if (matrix === null || matrix === undefined)
+        return null;
+    return `url(#jg-cb-${mode})`;
+}
 /**
  * Serializable, observable store of accessibility preferences (reduced motion,
  * high contrast, text scale, colorblind mode, captions). Genre-agnostic plumbing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.28.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.30.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.28.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.30.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-gameplay/SKILL.md

@@ -121,6 +121,8 @@ Prefer `defineSystem` and `defineGame({ systems })` for scheduled capabilities.
 
 `createNearAgents` (`sim/nearAgents`) is the default near half: a nav crowd with a need set and a utility brain per agent, counting its decisions for tests and probes. Give it the same need definitions the off-screen world decays, or the two halves disagree at the boundary.
 
+`createAgent` (`agents/agent`) is one resident's whole life without the nav: needs decay through `sim/needs`, the utility brain picks among the targets the world offers, `agents/mood` reads a feeling from those needs plus named sources a queue or a litter patch raises, and an authored day plan (`agents/schedule`, which resolves `sim/routine`) puts the agent at work, at a meal or at home - including a work beat, where a stop names the places it patrols. A target that disappears falls to the agent's declared fallback. `createRelationshipBook` (`agents/relationships`) keeps familiarity and opinion per pair: a social action moves both, friends prefer each other's company, and a bonded pair refuses to split. Every part snapshots and restores. [Agent lives](recipes/agent-lives.md) wires both a park guest and a household being from the same factory.
+
 `createVisitorPopulation` (`sim/population`) is the crowd a scene reports, and it is the bodies: a visitor joins only when your `VisitorWorld.admit` has made its body, and only while `VisitorWorld.has` holds it, so `onSite()` is the member count a HUD reads in O(1) and `arrivalsToday()` is the sum of the admissions the world accepted rather than a tally kept beside them. Arrival rate, capacity (a number or a function of the clock), the leaving rule and the `inside` bounds check are game policy; a refused body or one placed outside the bounds is released and never counted. `rollDay()` closes the day without emptying the park, `adopt` takes over a body a save or a seed made, and a restore only brings back members the world still holds.
 
 Rides and their lines are `createRideSystem` and `createWaitQueue` (`sim/rides`, `sim/queue`): a ride cycles load → ride → unload at its own capacity, wears against its own breakdown curve, and reports boards, alights, breakdowns and repair costs through a sink; the wait a guest faces comes from the queue's own measured boarding throughput, not a configured constant. Guest choice stays on the utility brain — `rideChoiceOptions` compiles a guest's `RideTaste` (intensity comfort, nausea comfort, queue tolerance) and the park's ratings into options, `rideChoiceCandidates` costs each one by its own line's wait, and `createRideChooser` wires both to one guest. Ratings, cycle times, breakdown curves and costs are caller data, and `retune` changes them in play.

package/skills/jgengine-gameplay/api.md

@@ -2,6 +2,52 @@
 
 # jgengine-gameplay — exported API surface
 
+## @jgengine/core/agents/agent
+
+- `Agent` (interface): interface Agent — Needs, mood, schedule and a chosen action, in one object a game ticks.
+- `AgentAction` (interface): interface AgentAction — What the agent is doing.
+- `AgentActionReason` (type): type AgentActionReason = UtilitySwitchReason | "fallback" | "schedule" | "cleared" — Why the action last changed.
+- `AgentConfig` (interface): interface AgentConfig — Everything an agent is made of. Policy is data; nothing about a game is compiled in.
+- `AgentFallback` (interface): interface AgentFallback — Where an agent goes when the thing it wanted is gone: a named option and a named place.
+- `AgentFrame` (interface): interface AgentFrame — What one update produced: the action, the feeling, and where the day plan puts the agent.
+- `AgentSnapshot` (interface): interface AgentSnapshot — Serializable whole agent: needs, feeling, held action, day-plan cursor and the far flag.
+- `AgentTarget` (interface): interface AgentTarget — One reachable thing the agent could do this tick, as the game sees its own world.
+- `AgentUpdate` (interface): interface AgentUpdate — One call per tick: the clock, and the targets the game's world currently offers.
+- `createAgent` (function): function createAgent(config: AgentConfig): Agent — Create one agent. The same factory serves a park guest, a household being, a patrolling janitor and a soldier: `options` is what it can choose between, `schedule` is where its day puts it.
+
+## @jgengine/core/agents/mood
+
+- `DEFAULT_MOOD_TIERS` (const): const DEFAULT_MOOD_TIERS: readonly MoodTier[] — Five bands a park guest, a household being or a soldier can share. A game overrides them when its own tone needs different words; the numeric bands are what HUD counters and tests read.
+- `Mood` (interface): interface Mood — What the agent feels right now, on the caller's own tier labels.
+- `MoodReader` (interface): interface MoodReader — A mood reader that keeps the game-raised biases, so a queue or a litter patch moves mood too.
+- `MoodSnapshot` (interface): interface MoodSnapshot — Serializable mood state: the game-raised biases that sit on top of need satisfaction.
+- `MoodTier` (interface): interface MoodTier — One labelled band of the 0-100 mood score.
+- `MoodWeight` (interface): interface MoodWeight — One need's say in the mood score; weights are relative, so they need no fixed total.
+- `createMoodReader` (function): function createMoodReader(config: { readonly needs: Pick<NeedSet, "ids" | "fraction">; readonly weights?: readonly MoodWeight[]; readonly tiers?: readonly MoodTier[]; }): MoodReader — Create the mood an agent carries. Needs are the agent's own (shared with its utility brain), and every bias is named data the game can remove again - there is no decaying hidden penalty.
+- `moodTierOf` (function): function moodTierOf(score: number, tiers: readonly MoodTier[] = DEFAULT_MOOD_TIERS): MoodTier — The band a score reads as, from tiers sorted by `at` descending. Unknown or unsorted tiers fall back to the lowest declared band rather than throwing, because a HUD reads this every frame.
+- `readMood` (function): function readMood(needs: Pick<NeedSet, "ids" | "fraction">, weights: readonly MoodWeight[], tiers: readonly MoodTier[] = DEFAULT_MOOD_TIERS, sources?: Readonly<Record<string, number>>): Mood — A mood read from a need set: each declared need contributes its `0..1` satisfaction times its weight, normalized by the total weight, so an agent with four needs and one with six read on the same 0-100 scale. Pure and allocation-light - the per-frame read a HUD and a thought bubble share.
+
+## @jgengine/core/agents/relationships
+
+- `DEFAULT_RELATIONSHIP_MILESTONES` (const): const DEFAULT_RELATIONSHIP_MILESTONES: readonly RelationshipMilestone[] — The pair levels every game starts from; a game overrides the words and the cut points.
+- `DEFAULT_SOCIAL_CONTACT` (const): const DEFAULT_SOCIAL_CONTACT: Required<SocialContact> — What a plain social action adds: a shared moment nudges both dials, never maxes either.
+- `Relationship` (interface): interface Relationship — How one pair stands: how much time they have shared, and what they think of each other.
+- `RelationshipBook` (interface): interface RelationshipBook — Everyone's view of everyone else: familiarity and opinion per pair, changed by social actions, with the pair levels that make a friendship a preference and a bond a refusal to split.
+- `RelationshipBookSnapshot` (interface): interface RelationshipBookSnapshot — Serializable relationship state: every known pair plus the dials in play.
+- `RelationshipMilestone` (interface): interface RelationshipMilestone — One labelled bond level on the opinion scale.
+- `RelationshipPolicy` (interface): interface RelationshipPolicy — Tunables a game owns, every one reachable through {@link RelationshipBook.retune}.
+- `SocialContact` (interface): interface SocialContact — Opinion and familiarity one interaction adds; a game passes its own for a hug, a row or a shift.
+- `SocialOutcome` (interface): interface SocialOutcome — What one social action did to a pair.
+- `createRelationshipBook` (function): function createRelationshipBook(policy: RelationshipPolicy = {}): RelationshipBook — Create the shared book of pair state. Keys are undirected and delimiter-safe through `createPairKeyCodec`, and milestone crossings come from `crossThresholds`, so a notice feed and a journal both read the same event.
+
+## @jgengine/core/agents/schedule
+
+- `AgentSchedule` (interface): interface AgentSchedule — A day plan resolved against the world clock. No state to tick: a far agent reads the same day.
+- `AgentScheduleConfig` (interface): interface AgentScheduleConfig — An agent's whole day as data: what it does, where, and when.
+- `AgentSchedulePhase` (interface): interface AgentSchedulePhase — Where a schedule puts an agent at one instant.
+- `AgentScheduleStop` (interface): interface AgentScheduleStop extends RoutineStopSpec — One authored stop in an agent's day. The shape is the routine owner's (`sim/routine`) plus a beat: the places a working stop walks in order, so a janitor on patrol is an agent with a route rather than a special case.
+- `createAgentSchedule` (function): function createAgentSchedule(config: AgentScheduleConfig): AgentSchedule — Resolve an authored day plan into a clock-driven schedule. Timing, travel and arrival slips come from `sim/routine`; this adds the work beat and the refills a stop carries, so an off-hours stop is just another authored stop and a patrol is not a second scheduler.
+
 ## @jgengine/core/behaviour/behaviour
 
 - `Behaviour` (class): class Behaviour — Subclass and override the lifecycle hooks. A behaviour only joins the per-frame update dispatch if it actually overrides `onUpdate` (prototype-identity check at each activation), so hook-only behaviours cost nothing per frame.
@@ -2349,6 +2395,26 @@
 - `missionMarkers` (function): function missionMarkers(document: SceneDocumentLike): Record<string, ScenePoint3> — Marker positions from an authored scene, keyed by marker id — what a positional objective reads.
 - `registerMissionTriggerActions` (function): function registerMissionTriggerActions(): void — Register {@link MISSION_TRIGGER_ACTIONS} so the editor lists them. Idempotent; call at module load next to the game's catalogs.
 
+## @jgengine/core/progression/careerBank
+
+- `CareerBank` (interface): interface CareerBank — Persistent career money plus the run in progress, which a failed run loses.
+- `CareerBankConfig` (interface): interface CareerBankConfig — Configuration for {@link createCareerBank}.
+- `CareerBankState` (interface): interface CareerBankState — Everything a career bank stores, as plain JSON. `banked` is the persistent balance; `haul` is the run in progress and is the part a failed run loses. `deposited`, `lost`, `bestHaul` and `runs` are lifetime counters a results screen reads.
+- `createCareerBank` (function): function createCareerBank(config: CareerBankConfig): CareerBank — Money that means something between runs: a persistent balance plus a run's haul that is banked on a cash-out and lost on a failure. Amounts are snapped to the currency's minor units, so a save round-trip and a display never drift. Pair it with `economy/upgrades` for a career upgrade tree.
+
+## @jgengine/core/progression/gates
+
+- `GateDef` (interface): interface GateDef — A milestone: content that opens exactly when its requirements hold and names the unlock it grants. `unlock` must resolve in the catalog the set is built with, or the set refuses to load.
+- `GateFacts` (interface): interface GateFacts — What a gate is evaluated against: standing by track and money by currency.
+- `GateMiss` (type): type GateMiss = "standing" | "balance" — Which named condition a closed gate still needs.
+- `GateRequirement` (interface): interface GateRequirement — Every condition a gate can require; all named conditions must hold.
+- `GateSet` (interface): interface GateSet — Evaluated gate content: the table, its status against facts, and the grants a caller applies.
+- `GateSetConfig` (interface): interface GateSetConfig — Content and the resolvers a {@link GateSet} is built from.
+- `GateStatus` (interface): interface GateStatus — One gate against live facts.
+- `assertGates` (function): function assertGates(config: GateSetConfig): void — Check an authored gate table against the content it grants; throws `RangeError` naming the gate.
+- `createGateSet` (function): function createGateSet(config: GateSetConfig): GateSet — Authored unlock gates: each one names the unlock it grants and the standing or balance it reads. Evaluated against caller-supplied facts, so one table serves a single-player save, a server actor or a probe. Load refuses a gate whose unlock id resolves to nothing (the D3.8 class), so a dead milestone fails at startup instead of in play. A gate with no requirements is open from the start.
+- `gateFacts` (function): function gateFacts(standing: Pick<Standing, "standing">, actorId: string, balances: Readonly<Record<string, number>> = {}): GateFacts — Read a {@link Standing} and a balance record as {@link GateFacts}.
+
 ## @jgengine/core/progression/gearScore
 
 - `GearScore` (interface): interface GearScore — A scored loadout: the total, each slot's share, each stat's signed contribution, and how complete it is.
@@ -2372,6 +2438,18 @@
 - `assertSkillTreeConfig` (function): function assertSkillTreeConfig<TStat extends string>(config: SkillTreeConfig<TStat>): void — Check tree data before play; throws `RangeError` naming the offending node, requirement or synergy.
 - `createSkillTree` (function): function createSkillTree<TStat extends string = string>(config: SkillTreeConfig<TStat>, options: { devtoolsName?: string } = {}): SkillTree<TStat> — A data-authored skill tree: nodes carry a point cost, prerequisites, passives and unlocked actions, synergies pay off two or more nodes together, and `respec` refunds exactly the points spent. Spend against `canSpend` for a reason a UI can show; read `resolved()` for the stat modifiers and action list to feed `createStats` / `createAbilityKit`.
 
+## @jgengine/core/progression/standing
+
+- `Standing` (interface): interface Standing — Live standing over authored tracks, moved by named outcomes or direct adjustments, with the tier on each track and a serializable snapshot.
+- `StandingChange` (interface): interface StandingChange — One track's movement, with the tier on both sides so a caller can announce a crossing.
+- `StandingConfig` (interface): interface StandingConfig — Authored standing content: the tracks an actor stands with, and the outcomes that move them.
+- `StandingOutcomeDef` (interface): interface StandingOutcomeDef — One outcome a game can report, and the standing it moves on each track.
+- `StandingRequirement` (interface): interface StandingRequirement — A threshold on one track, as an unlock or an upgrade reads it.
+- `StandingState` (interface): interface StandingState — Plain JSON state of a {@link Standing}; tracks left at their authored `initial` are absent.
+- `StandingTrackDef` (interface): interface StandingTrackDef — One standing track: a faction, a district, a licence board — whatever an authored outcome moves.
+- `assertStandingConfig` (function): function assertStandingConfig(config: StandingConfig): void — Check authored standing content before use; throws `RangeError` naming the offending field.
+- `createStanding` (function): function createStanding(config: StandingConfig): Standing — Per-faction or per-district standing that rises and falls from named outcomes, over authored tracks. Numbers live in the shared reputation ledger (`faction/reputation`); this adds the authored outcome table, tier-per-track and the one snapshot a save stores. An outcome id or track id that resolves to nothing throws at the call, so authored content fails loudly.
+
 ## @jgengine/core/progression/statGraph
 
 - `StatContribution` (interface): interface StatContribution — One folded contribution to a value, retained so a sheet can explain "why is this value 42?" — every step carries the source that produced it.
@@ -2389,6 +2467,17 @@
 - `createStatGraph` (function): function createStatGraph(def: StatGraphDef): StatGraph — A data-driven stat graph: game-owned named inputs feed caller-authored derived formulas, with contribution provenance, uncommitted previews, cycle detection, and selective recomputation. Formula semantics and numeric tables stay entirely game-defined.
 - `statModifierContributions` (function): function statModifierContributions<TStat extends string>(source: string, set: StatModifierSet<TStat>): Record<string, StatContribution[]> — Bridge the shared {@link StatModifierSet} shape (add/multiply, used by talents, items, and buffs) into stat-graph contributions, so a ranked talent tree or gear roll feeds the graph as one named source instead of a parallel store.
 
+## @jgengine/core/progression/upgrades
+
+- `UpgradeBuy` (type): type UpgradeBuy = { ok: true; nodeId: string; rank: number; cost: number } | { ok: false; reason: UpgradeRejection } — Result of {@link UpgradeTree.buy}: the rank reached and what it cost, or why it was refused.
+- `UpgradeNodeDef` (interface): interface UpgradeNodeDef — One upgrade node. Its price is the shared progression {@link Curve} evaluated at the rank being bought, so a game authors one curve and every rank of every node follows it.
+- `UpgradeRejection` (type): type UpgradeRejection = "unknown-node" | "max-rank" | "missing-prerequisites" | "standing" | "insufficient-funds" — Why a purchase was refused; the tree is left untouched on any rejection.
+- `UpgradeState` (interface): interface UpgradeState — Plain JSON state: node id → ranks owned. Nodes at rank `0` are absent.
+- `UpgradeTree` (interface): interface UpgradeTree — Authored upgrade nodes with a per-node cost curve, prerequisites, a standing gate and one snapshot.
+- `UpgradeTreeConfig` (interface): interface UpgradeTreeConfig — Authored nodes plus the standing a node's requirement reads.
+- `assertUpgrades` (function): function assertUpgrades(config: UpgradeTreeConfig): void — Check authored upgrade nodes; throws `RangeError` naming the offending node or field.
+- `createUpgradeTree` (function): function createUpgradeTree(config: UpgradeTreeConfig): UpgradeTree — An upgrade tree whose prices come from the shared curve primitive: each node authors one cost curve, each rank is that curve at the rank, and a purchase passes prerequisites, a standing gate and the caller's own payment step. State is one rank map that JSON round-trips, so a career save stores what a player paid for rather than the arithmetic behind it.
+
 ## @jgengine/core/progression/xpCurve
 
 - `XpCurve` (interface): interface XpCurve — A resolved, validated {@link XpCurveDef}: thresholds, lifetime totals, a stated rule, and a leveling track bound to the same numbers.

package/skills/jgengine-gameplay/capabilities.md

@@ -16,6 +16,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createAffixRoller` (function) · `import { createAffixRoller } from "@jgengine/core/gameplay"`
 
+## agent-schedule — an authored per-agent day plan with a work beat and off-hours behaviour
+
+- `createAgentSchedule` (function) · `import { createAgentSchedule } from "@jgengine/core/agents/schedule"`
+
+## agents — a needs, thought, action and mood loop an agent runs on the world clock
+
+- `createAgent` (function) · `import { createAgent } from "@jgengine/core/agents/agent"`
+
 ## auction-book — timed bid auctions with escrowed bids, buyout, anti-snipe close extension, and collection-box settlement
 
 - `createAuctionBook` (function) · `import { createAuctionBook } from "@jgengine/core/gameplay"`
@@ -36,6 +44,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `cancelJob` (function) · `import { cancelJob } from "@jgengine/core/gameplay"`
 
+## career-bank — persistent career money with a run haul that can be banked or lost
+
+- `createCareerBank` (function) · `import { createCareerBank } from "@jgengine/core/progression/careerBank"`
+
 ## carry-encumbrance — gate a pickup against the carrier's remaining capacity
 
 - `canCarry` (function) · `import { canCarry } from "@jgengine/core/inventory/carryLoad"`
@@ -392,6 +404,12 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `slotAccepts` (function) · `import { slotAccepts } from "@jgengine/core/gameplay"`
 
+## mood — a mood derived from how satisfied an agent's needs are
+
+- `createMoodReader` (function) · `import { createMoodReader } from "@jgengine/core/agents/mood"`
+- `moodTierOf` (function) · `import { moodTierOf } from "@jgengine/core/agents/mood"`
+- `readMood` (function) · `import { readMood } from "@jgengine/core/agents/mood"`
+
 ## move — a keyed value toward a target by a bounded step
 
 - `towardValue` (function) · `import { towardValue } from "@jgengine/core/gameplay"`
@@ -537,6 +555,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `attachRefusalNotices` (function) · `import { attachRefusalNotices } from "@jgengine/core/game/notices"`
 
+## relationships — familiarity and opinion between agents, with a bond that changes behaviour
+
+- `createRelationshipBook` (function) · `import { createRelationshipBook } from "@jgengine/core/agents/relationships"`
+
 ## resolve — the current tier/band label for a keyed or scalar value
 
 - `tierAt` (function) · `import { tierAt } from "@jgengine/core/gameplay"`
@@ -651,6 +673,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `stationOutputRate` (function) · `import { stationOutputRate } from "@jgengine/core/gameplay"`
 
+## standing — per-track standing moved by authored outcomes, with tiers and one snapshot
+
+- `createStanding` (function) · `import { createStanding } from "@jgengine/core/progression/standing"`
+
 ## stat-graph — derive game-defined stats from named inputs with provenance and preview
 
 - `createStatGraph` (function) · `import { createStatGraph } from "@jgengine/core/gameplay"`
@@ -724,6 +750,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `unitTrainingConfig` (function) · `import { unitTrainingConfig } from "@jgengine/core/gameplay"`
 
+## unlock-gates — milestones gated by standing or money, validated against the content they grant
+
+- `createGateSet` (function) · `import { createGateSet } from "@jgengine/core/progression/gates"`
+
 ## unlock-points — spendable point pool earned per level and spent to unlock nodes, with refund and respec
 
 - `createUnlockPoints` (function) · `import { createUnlockPoints } from "@jgengine/core/economy/unlockPoints"`
@@ -732,6 +762,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createUnlockCatalog` (function) · `import { createUnlockCatalog } from "@jgengine/core/gameplay"`
 
+## upgrade-tree — ranked upgrades priced by a cost curve, gated by prerequisites and standing
+
+- `createUpgradeTree` (function) · `import { createUpgradeTree } from "@jgengine/core/progression/upgrades"`
+
 ## visitor-population — a crowd whose on-site and daily counts are the bodies the game made
 
 - `createVisitorPopulation` (function) · `import { createVisitorPopulation } from "@jgengine/core/gameplay"`