@jgengine/core 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -26,6 +26,38 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.36.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.36.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.33.0`; `@jgengine/github` is `0.23.0`.
+
+### Added
+
+- `createAgentSystem` (`@jgengine/core/agents/system`) takes a game's needs, options, mood weights, members and
+  schedules once and returns a running cast: one `tick(dt)` for everyone, one target selector for the whole system,
+  a fallback declared once, and a plain-JSON `save()`/`load()` that rides the game's own save.
+- `--quick` on `bun run shoot` and `bun run drive` is the 960x540 iteration preset: one settled frame (a 2s settle window in drive), no video, no perf pass, written as `<name>-quick.png` and timed on its own line. It refuses a 1600x900 pixel claim, a frame-time claim, a non-desktop device and a recording flag by name instead of producing weaker evidence; full stays the default for PR shots. On a warm daemon a two-shot `drive` of ember-command went 9.3s to 8.2s and 4316KB to 1383KB of PNG.
+- `createPlayScript` / `runPlayScript` (`@jgengine/shell/play`) play a real `PlayableGame` headlessly from a tick-based script: `move`, `aim`, `fire`, `use`, `wait` and `command` steps plus `setup`/`onTick` hooks, `expect` assertions read after setup and on their own tick, a tick timeline, and an FNV digest for replay comparison. It replays the shell's own frame pipeline — held movement through the walk controller, a bound action resolving to its command on press and repeat, interact prompts, hotbar — so a script proves the same code path a player's hands do. No browser, no wall clock, fixed `dt`.
+- `bun run simulate <game> <script>` runs a committed `<game>/scripts/*.play.ts` against a game under `./Games`, prints the timeline, names a failed assertion and exits 1. It merges the game's own tsconfig `paths` with this checkout's source packages, so the game imports and the engine under test are one module graph.
+- `HeadlessRunner.aim()` steers the walk controller mid-run; `HeadlessRunnerOptions` gains `seed` (deterministic `ctx.rng`) and `collision` (the shell's voxel config, previously dropped on the headless path).
+
+Play scripts prove play in seconds instead of minutes of browser play, and the three proofs land beside their games: Scrap Signal (an enemy takes damage and closes in), Beacon Bastion (a composed wave is reached, its bounty scales, a boss phase flips) and Harbor Heat (heat is witness-gated, the search area is set, a courier is swept).
+
+### Changed
+
+- The graphics quality tier now costs what it claims on the render path. A tier's post chain renders at its own resolution scale (`low` 0.7, `medium` 0.85, `high`/`ultra` native) instead of always at the canvas size, and a game's authored `shadowMapSize` and `cascades` are a ceiling the tier caps rather than a value it ignored — every reference game authored 3 cascades and 1024/2048, so no tier changed a shadow before this. `low` and `medium` also stretch the far cascades' refresh interval, and the smallest caster worth a depth draw grows as the map shrinks. `high` and `ultra` keep native resolution, the authored shadow sizes and the measured cadence, so their frames are unchanged.
+- Measured uncapped at 1600x900: whole-frame draws at `low` fell 53% in harbor-heat (515 → 242) and 63% in drift-foundry (1,098 → 408), with the shadow pass there down from 911 ms to 344 ms over a 6 s window; `high` and `ultra` held their draw counts.
+
+### Fixed
+
+- Terrain build no longer scans every road and path segment for every vertex. A baked path corridor, a draped road and a painted polyline region each answer "how far is this point?" from a precomputed segment grid, so Scrap Signal's world build drops from 16.6 s to 0.51 s on the same machine and its longest boot stall from 11.6–18.4 s to 1.2 s. Sampled heights and palettes are bit-identical to the previous full scan, and `withPathProfiles` still composes profiles in order.
+- Load-time shader warmup compiles against the render state the first frame actually draws with. A scene whose post chain renders into its own buffer was linking two programs per material, one linear untone-mapped set the frame draws and one canvas set nothing ever drew; the cover no longer waits for the second set. Harbor Heat links 84 programs to 58 and Scrap Signal 124 to 83 before the cover lifts, with no visual change.
+
+### Performance
+
+- `createTerrainPaletteSampler` (`@jgengine/core/world/terrain`) tests only the material regions whose painted core or blend ring covers a sample, so a world with hundreds of authored regions no longer pays for all of them at every vertex.
+
 ## 0.35.0
 
 ### Migrate

package/dist/agents/system.d.ts

@@ -0,0 +1,135 @@
+import type { UtilityInterrupt, UtilityOption, UtilityTunables } from "../ai/utilityBrain.js";
+import type { NeedDefinition } from "../sim/needs.js";
+import type { Vec3 } from "../world/geometry.js";
+import { type Agent, type AgentFallback, type AgentFrame, type AgentSnapshot, type AgentTarget } from "./agent.js";
+import type { Mood, MoodTier, MoodWeight } from "./mood.js";
+import type { AgentScheduleConfig } from "./schedule.js";
+export type { Agent, AgentAction, AgentFallback, AgentFrame, AgentSnapshot, AgentTarget } from "./agent.js";
+export type { AgentScheduleConfig, AgentScheduleStop, AgentSchedulePhase } from "./schedule.js";
+export type { Mood, MoodTier, MoodWeight } from "./mood.js";
+export type { NeedDefinition } from "../sim/needs.js";
+export type { UtilityInterrupt, UtilityOption, UtilityTunables } from "../ai/utilityBrain.js";
+/** The mood policy a member runs on: which needs matter, and the game's own words for the bands. */
+export interface AgentMoodConfig {
+    readonly weights?: readonly MoodWeight[];
+    readonly tiers?: readonly MoodTier[];
+}
+/** What a selector is told about the member asking: who it is, its live agent, and where it stands. */
+export interface AgentSelectView {
+    readonly id: string;
+    /** The live agent, for a selector that reads needs, mood or the held action. */
+    readonly agent: Agent;
+    /** Body position from the system's `position` reader, or `null` when the game has no body for it. */
+    readonly at: Vec3 | null;
+    readonly now: number;
+    /** True while the member is off camera and takes no utility pass this tick. */
+    readonly far: boolean;
+}
+/** Everything the member could do right now, as the game's world offers it. Declared once per system. */
+export type AgentSelector = (view: AgentSelectView) => readonly AgentTarget[];
+/** Where a system keeps its save data: a key-value store, a save slot, or a test's map. */
+export interface AgentSystemStorage {
+    read(): AgentSystemState | undefined;
+    write(next: AgentSystemState): void;
+}
+/** One member's saved state: its agent snapshot plus the off-camera flag the snapshot does not carry. */
+export interface AgentMemberState {
+    readonly agent: AgentSnapshot;
+    readonly far: boolean;
+}
+/** The whole system as plain JSON - drop it in a save, read it back with {@link AgentSystem.load}. */
+export interface AgentSystemState {
+    readonly version: 1;
+    readonly members: Readonly<Record<string, AgentMemberState>>;
+}
+/** One member: an id, and only what differs from the system's defaults. */
+export interface AgentMemberSpec extends UtilityTunables {
+    readonly id: string;
+    /** Needs for this member; defaults to the system's. */
+    readonly needs?: readonly NeedDefinition[];
+    /** Scored actions for this member; defaults to the system's. */
+    readonly options?: readonly UtilityOption[];
+    readonly interrupts?: readonly UtilityInterrupt[];
+    /** The member's authored day; omit for one that only reacts to targets. */
+    readonly schedule?: AgentScheduleConfig;
+    readonly mood?: AgentMoodConfig;
+    /** Targets for this member instead of the system's selector. */
+    readonly select?: AgentSelector;
+    /** `[0,1)` source; defaults to the system's `rng`. */
+    readonly rng?: () => number;
+    readonly devtoolsName?: string;
+    /** Start off camera: schedule and needs only, no utility pass, until `setFar(id, false)`. */
+    readonly far?: boolean;
+}
+/** The game's data, in one place: what its people need, what they can do, and how they feel. */
+export interface AgentSystemConfig {
+    /** Needs every member carries unless it declares its own. */
+    readonly needs: readonly NeedDefinition[];
+    /** Scored actions every member chooses between unless it declares its own. */
+    readonly options: readonly UtilityOption[];
+    readonly interrupts?: readonly UtilityInterrupt[];
+    readonly mood?: AgentMoodConfig;
+    /** Members present at creation; more join later with {@link AgentSystem.add}. */
+    readonly members?: readonly AgentMemberSpec[];
+    /** Resolve every member's targets. Called once per on-camera member per tick, never per option. */
+    readonly select?: AgentSelector;
+    /** Fallback given to every target that declares none - one fallback per system, not per target. */
+    readonly fallback?: AgentFallback;
+    /** The world clock, so `tick(dt)` needs no `now` argument. */
+    readonly clock?: {
+        now(): number;
+    };
+    /** Where a member's body is, handed to the selector as `at`. */
+    readonly position?: (id: string) => Vec3 | null;
+    /** Save storage, hydrated on the first tick and written by {@link AgentSystem.save}. */
+    readonly storage?: AgentSystemStorage;
+    /** Deterministic source shared by members that do not declare their own. */
+    readonly rng?: () => number;
+    /** Dials every member starts with; a member may override any of them. */
+    readonly defaults?: UtilityTunables;
+    /** Devtools prefix: member `x` registers as `<devtoolsName>.x`. */
+    readonly devtoolsName?: string;
+}
+/**
+ * A whole cast of agents behind one factory and one tick.
+ *
+ * Feed it a game's data once - needs, options, mood weights, the members and their schedules - and it
+ * owns the parts a game should not write: the roster, lazy creation, one tick for everyone, where a
+ * target came from, and a save blob that is plain JSON. Everything an individual {@link Agent} can do
+ * stays reachable through {@link get}.
+ */
+export interface AgentSystem {
+    /** Create and register one member; a member saved under this id resumes instead of starting fresh. */
+    add(spec: AgentMemberSpec): Agent;
+    get(id: string): Agent | null;
+    has(id: string): boolean;
+    remove(id: string): void;
+    /** Member ids in creation order. */
+    ids(): readonly string[];
+    size(): number;
+    /** One call per game tick: decay, day plan and decision for every member, near or far. */
+    tick(dt: number, now?: number): void;
+    /** What the last tick produced for a member, or `null` before it has ticked. */
+    frame(id: string): AgentFrame | null;
+    /** A member's mood, readable before its first tick. */
+    mood(id: string): Mood | null;
+    /** Mean mood across members, or `null` for an empty system. */
+    moodMean(): number | null;
+    /** Action of a member, `null` before its first tick. */
+    action(id: string): AgentFrame["action"] | null;
+    setFar(id: string, far: boolean): void;
+    isFar(id: string): boolean;
+    /** Plain-JSON state, also written to `storage` when one was given. */
+    save(): AgentSystemState;
+    /** Restore members saved under ids this system knows, and hold the rest until they join. */
+    load(next: AgentSystemState | undefined): void;
+    dispose(): void;
+}
+/**
+ * One call for a whole cast: a game hands over its needs, options, mood weights, schedules and one
+ * target selector, and gets back a running system with a single `tick(dt)` and a save blob that goes
+ * into the game's own save.
+ *
+ * @capability agents a needs, thought, action and mood loop an agent runs on the world clock
+ */
+export declare function createAgentSystem(config: AgentSystemConfig): AgentSystem;

package/dist/agents/system.js

@@ -0,0 +1,195 @@
+import { createAgent, } from "./agent.js";
+/**
+ * One call for a whole cast: a game hands over its needs, options, mood weights, schedules and one
+ * target selector, and gets back a running system with a single `tick(dt)` and a save blob that goes
+ * into the game's own save.
+ *
+ * @capability agents a needs, thought, action and mood loop an agent runs on the world clock
+ */
+export function createAgentSystem(config) {
+    const agents = new Map();
+    const frames = new Map();
+    const selectors = new Map();
+    const saved = new Map();
+    const order = [];
+    let hydrated = false;
+    let lastNow = 0;
+    function selectFor(id) {
+        return selectors.get(id) ?? config.select;
+    }
+    function restoreInto(agent, state) {
+        agent.restore(state.agent);
+        if (state.far)
+            agent.setFar(true);
+    }
+    function hydrate() {
+        if (hydrated)
+            return;
+        const state = config.storage?.read();
+        if (state === undefined)
+            return;
+        hydrated = true;
+        loadState(state);
+    }
+    function loadState(next) {
+        if (next === undefined)
+            return;
+        for (const [id, state] of Object.entries(next.members)) {
+            const agent = agents.get(id);
+            if (agent === undefined) {
+                saved.set(id, state);
+                continue;
+            }
+            restoreInto(agent, state);
+            saved.delete(id);
+        }
+    }
+    function create(spec) {
+        const defaults = config.defaults;
+        const tuned = (key) => spec[key] ?? defaults?.[key];
+        const devtoolsName = spec.devtoolsName ?? (config.devtoolsName === undefined ? undefined : `${config.devtoolsName}.${spec.id}`);
+        const agent = createAgent({
+            id: spec.id,
+            needs: spec.needs ?? config.needs,
+            options: spec.options ?? config.options,
+            ...optional("interrupts", spec.interrupts ?? config.interrupts),
+            ...optional("schedule", spec.schedule),
+            mood: {
+                ...optional("weights", spec.mood?.weights ?? config.mood?.weights),
+                ...optional("tiers", spec.mood?.tiers ?? config.mood?.tiers),
+            },
+            ...optional("switchMargin", tuned("switchMargin")),
+            ...optional("minHoldSeconds", tuned("minHoldSeconds")),
+            ...optional("costWeight", tuned("costWeight")),
+            ...optional("jitter", tuned("jitter")),
+            ...optional("rng", spec.rng ?? config.rng),
+            ...optional("devtoolsName", devtoolsName),
+        });
+        agents.set(agent.id, agent);
+        order.push(agent.id);
+        if (spec.select !== undefined)
+            selectors.set(agent.id, spec.select);
+        if (spec.far === true)
+            agent.setFar(true);
+        const pending = saved.get(spec.id);
+        if (pending !== undefined) {
+            restoreInto(agent, pending);
+            saved.delete(spec.id);
+        }
+        return agent;
+    }
+    const system = {
+        add(spec) {
+            const existing = agents.get(spec.id);
+            if (existing !== undefined)
+                return existing;
+            return create(spec);
+        },
+        get: (id) => agents.get(id) ?? null,
+        has: (id) => agents.has(id),
+        remove(id) {
+            const agent = agents.get(id);
+            if (agent === undefined)
+                return;
+            agent.dispose();
+            agents.delete(id);
+            frames.delete(id);
+            selectors.delete(id);
+            saved.delete(id);
+            const at = order.indexOf(id);
+            if (at >= 0)
+                order.splice(at, 1);
+        },
+        ids: () => order,
+        size: () => order.length,
+        tick(dt, now) {
+            hydrate();
+            const time = now ?? config.clock?.now() ?? lastNow;
+            lastNow = time;
+            for (const id of order) {
+                const agent = agents.get(id);
+                if (agent === undefined)
+                    continue;
+                let targets = [];
+                if (!agent.isFar()) {
+                    const selector = selectFor(id);
+                    if (selector !== undefined) {
+                        targets = selector({
+                            id,
+                            agent,
+                            at: config.position?.(id) ?? null,
+                            now: time,
+                            far: false,
+                        });
+                        if (config.fallback !== undefined)
+                            targets = withFallback(targets, config.fallback);
+                    }
+                }
+                frames.set(id, agent.update({ dt, now: time, targets }));
+            }
+        },
+        frame: (id) => frames.get(id) ?? null,
+        mood: (id) => agents.get(id)?.mood() ?? null,
+        moodMean() {
+            if (order.length === 0)
+                return null;
+            let total = 0;
+            for (const id of order) {
+                const agent = agents.get(id);
+                if (agent !== undefined)
+                    total += agent.mood().score;
+            }
+            return total / order.length;
+        },
+        action: (id) => frames.get(id)?.action ?? null,
+        setFar(id, far) {
+            const agent = agents.get(id);
+            if (agent === undefined)
+                return;
+            agent.setFar(far);
+            if (far)
+                frames.delete(id);
+        },
+        isFar: (id) => agents.get(id)?.isFar() ?? false,
+        save() {
+            hydrate();
+            const members = {};
+            for (const id of order) {
+                const agent = agents.get(id);
+                if (agent !== undefined)
+                    members[id] = { agent: agent.snapshot(), far: agent.isFar() };
+            }
+            const state = { version: 1, members };
+            config.storage?.write(state);
+            return state;
+        },
+        load: loadState,
+        dispose() {
+            for (const agent of agents.values())
+                agent.dispose();
+            agents.clear();
+            frames.clear();
+            saved.clear();
+            order.length = 0;
+        },
+    };
+    hydrate();
+    for (const spec of config.members ?? [])
+        create(spec);
+    return system;
+}
+/** Targets keep their own fallback; the rest inherit the system's one. */
+function withFallback(targets, fallback) {
+    let changed = false;
+    const next = targets.map((target) => {
+        if (target.fallback !== undefined)
+            return target;
+        changed = true;
+        return { ...target, fallback };
+    });
+    return changed ? next : targets;
+}
+/** Spread a config field only when the game set it, so `createAgent`'s own default stands otherwise. */
+function optional(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.35.0";
+export declare const VERSION = "0.36.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,26 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.35.0";
+export const VERSION = "0.36.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.36.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.36.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.33.0`; `@jgengine/github` is `0.23.0`.",
+        ],
+        added: [
+            "`createAgentSystem` (`@jgengine/core/agents/system`) takes a game's needs, options, mood weights, members and schedules once and returns a running cast: one `tick(dt)` for everyone, one target selector for the whole system, a fallback declared once, and a plain-JSON `save()`/`load()` that rides the game's own save.",
+            "`--quick` on `bun run shoot` and `bun run drive` is the 960x540 iteration preset: one settled frame (a 2s settle window in drive), no video, no perf pass, written as `<name>-quick.png` and timed on its own line. It refuses a 1600x900 pixel claim, a frame-time claim, a non-desktop device and a recording flag by name instead of producing weaker evidence; full stays the default for PR shots. On a warm daemon a two-shot `drive` of ember-command went 9.3s to 8.2s and 4316KB to 1383KB of PNG.",
+            "`createPlayScript` / `runPlayScript` (`@jgengine/shell/play`) play a real `PlayableGame` headlessly from a tick-based script: `move`, `aim`, `fire`, `use`, `wait` and `command` steps plus `setup`/`onTick` hooks, `expect` assertions read after setup and on their own tick, a tick timeline, and an FNV digest for replay comparison. It replays the shell's own frame pipeline — held movement through the walk controller, a bound action resolving to its command on press and repeat, interact prompts, hotbar — so a script proves the same code path a player's hands do. No browser, no wall clock, fixed `dt`.",
+            "`bun run simulate <game> <script>` runs a committed `<game>/scripts/*.play.ts` against a game under `./Games`, prints the timeline, names a failed assertion and exits 1. It merges the game's own tsconfig `paths` with this checkout's source packages, so the game imports and the engine under test are one module graph.",
+            "`HeadlessRunner.aim()` steers the walk controller mid-run; `HeadlessRunnerOptions` gains `seed` (deterministic `ctx.rng`) and `collision` (the shell's voxel config, previously dropped on the headless path).",
+        ],
+        changed: [
+            "The graphics quality tier now costs what it claims on the render path. A tier's post chain renders at its own resolution scale (`low` 0.7, `medium` 0.85, `high`/`ultra` native) instead of always at the canvas size, and a game's authored `shadowMapSize` and `cascades` are a ceiling the tier caps rather than a value it ignored — every reference game authored 3 cascades and 1024/2048, so no tier changed a shadow before this. `low` and `medium` also stretch the far cascades' refresh interval, and the smallest caster worth a depth draw grows as the map shrinks. `high` and `ultra` keep native resolution, the authored shadow sizes and the measured cadence, so their frames are unchanged.",
+            "Measured uncapped at 1600x900: whole-frame draws at `low` fell 53% in harbor-heat (515 → 242) and 63% in drift-foundry (1,098 → 408), with the shadow pass there down from 911 ms to 344 ms over a 6 s window; `high` and `ultra` held their draw counts.",
+            "Terrain build no longer scans every road and path segment for every vertex. A baked path corridor, a draped road and a painted polyline region each answer \"how far is this point?\" from a precomputed segment grid, so Scrap Signal's world build drops from 16.6 s to 0.51 s on the same machine and its longest boot stall from 11.6–18.4 s to 1.2 s. Sampled heights and palettes are bit-identical to the previous full scan, and `withPathProfiles` still composes profiles in order.",
+            "Load-time shader warmup compiles against the render state the first frame actually draws with. A scene whose post chain renders into its own buffer was linking two programs per material, one linear untone-mapped set the frame draws and one canvas set nothing ever drew; the cover no longer waits for the second set. Harbor Heat links 84 programs to 58 and Scrap Signal 124 to 83 before the cover lifts, with no visual change.",
+        ],
+        removed: [],
+    },
     "0.35.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.35.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.32.0`; `@jgengine/github` is `0.22.0`.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.35.0",
+  "version": "0.36.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.35.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.36.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.35.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.36.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-gameplay/api.md

@@ -48,6 +48,35 @@
 - `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/agents/system
+
+- `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.
+- `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.
+- `AgentMemberSpec` (interface): interface AgentMemberSpec extends UtilityTunables — One member: an id, and only what differs from the system's defaults.
+- `AgentMemberState` (interface): interface AgentMemberState — One member's saved state: its agent snapshot plus the off-camera flag the snapshot does not carry.
+- `AgentMoodConfig` (interface): interface AgentMoodConfig — The mood policy a member runs on: which needs matter, and the game's own words for the bands.
+- `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.
+- `AgentSelectView` (interface): interface AgentSelectView — What a selector is told about the member asking: who it is, its live agent, and where it stands.
+- `AgentSelector` (type): type AgentSelector = (view: AgentSelectView) => readonly AgentTarget[] — Everything the member could do right now, as the game's world offers it. Declared once per system.
+- `AgentSnapshot` (interface): interface AgentSnapshot — Serializable whole agent: needs, feeling, held action, day-plan cursor and the far flag.
+- `AgentSystem` (interface): interface AgentSystem — A whole cast of agents behind one factory and one tick.
+- `AgentSystemConfig` (interface): interface AgentSystemConfig — The game's data, in one place: what its people need, what they can do, and how they feel.
+- `AgentSystemState` (interface): interface AgentSystemState — The whole system as plain JSON - drop it in a save, read it back with {@link AgentSystem.load}.
+- `AgentSystemStorage` (interface): interface AgentSystemStorage — Where a system keeps its save data: a key-value store, a save slot, or a test's map.
+- `AgentTarget` (interface): interface AgentTarget — One reachable thing the agent could do this tick, as the game sees its own world.
+- `Mood` (interface): interface Mood — What the agent feels right now, on the caller's own tier labels.
+- `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.
+- `NeedDefinition` (type): type NeedDefinition = DecayMeterConfig — A decaying need is a survival decay meter (`max`/`min`/`start`/`rate`, optional moodle thresholds) whose satisfaction an agent brain reads to score actions. The meter owns the numbers; per-need appeal lives in the game's utility options.
+- `UtilityInterrupt` (interface): interface UtilityInterrupt — A need level that overrides the sticky pick the moment it is crossed.
+- `UtilityOption` (interface): interface UtilityOption — A thing an agent can decide to do, scored against its needs.
+- `UtilityTunables` (interface): interface UtilityTunables — In-play dials that stay reachable through {@link UtilityBrain.retune}.
+- `createAgentSystem` (function): function createAgentSystem(config: AgentSystemConfig): AgentSystem — One call for a whole cast: a game hands over its needs, options, mood weights, schedules and one target selector, and gets back a running system with a single `tick(dt)` and a save blob that goes into the game's own save.
+
 ## @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.

package/skills/jgengine-gameplay/capabilities.md

@@ -23,6 +23,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## agents — a needs, thought, action and mood loop an agent runs on the world clock
 
 - `createAgent` (function) · `import { createAgent } from "@jgengine/core/agents/agent"`
+- `createAgentSystem` (function) · `import { createAgentSystem } from "@jgengine/core/agents/system"`
 
 ## auction-book — timed bid auctions with escrowed bids, buyout, anti-snipe close extension, and collection-box settlement