@jgengine/core 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -26,6 +26,122 @@ 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.37.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.37.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.34.0`; `@jgengine/github` is `0.24.0`.
+
+### Added
+
+- `bun run check:script-help` walks every `package.json` script that points into `scripts/`, runs each with `--help`, and fails when one errors, hangs over its own timeout, prints nothing, or when a script names a file the repo does not have. Script files that predate `--help` are listed in `scripts/script-help-baseline.json` and reported, so a new one cannot arrive undocumented.
+- `land`, `lane:close`, `lane:audit`, `ci-status` and `verify:fast` answer `--help` with their purpose, the flags they actually accept, one example and their exit codes, through one shared `scripts/script-help.ts`. No install, network or browser needed.
+- `RunLoop.present(count)` and `RunLoop.choose(id)` (`@jgengine/core/run/runLoop`) draw several next-run changes for a choice screen and adopt the pick, so a game that offers three relics does not compose `game/runDraft` beside the loop. `present` honours the same `after` gates and weights as the single draw and never repeats the change just played while alternatives remain; `choose` opens the next run around the pick and refuses an id the loop's table does not carry.
+- `installRunProbe` (`@jgengine/core/run/runLoop`) publishes `window.__jgengineRun` with the run in progress, what it carries, what it banked or lost, its best bank and the change it offers, so a capture or devtools read proves the loop is live instead of only imported.
+- `bun run find <pattern> [--in <dir>] [--kind ts,tsx] [--files]` answers a repository-wide search in about a second: ripgrep reads the tree once, honours `.gitignore` and never enters `node_modules`, `.git`, `.claude/worktrees` or build output. `--files` lists names by `--glob`, which is what a tree listing was for. Eight of the ten hard timeouts in three hours of lane transcripts were a recursive directory listing over this checkout (160 s, 3.0M files) against a 120 s limit, while every other call's p90 was 10.5 s.
+- `bun run check-recursive-walk` fails a `scripts/**` file or a lane document (`AGENTS.md`, `README.md`, every skill under `.claude/skills`) that ships a recursive directory listing, a `find` walk from a root, or `git ls-files` piped into per-file work; a required one carries `// walk-ok: <reason>`. It runs in CI through the scripts test shard.
+- `ModelConfig.variants` (`levels: [{ url, maxDistance? }]`, `hysteresis?`) declares ordered mesh detail levels for a model. The instanced prop path switches level per instance by distance to the camera, so near and far placements of one species keep their own mesh inside one batch cell. A model without `variants` draws exactly as before.
+- `createModelVariantSelector` (`@jgengine/core/world/modelLod`) returns the level index for an id at a distance, carrying hysteresis across each boundary (`DEFAULT_VARIANT_HYSTERESIS`, 6 m). `lodBandIndex` is now exported from `@jgengine/core/world/lod` and both the LOD scheduler and the selector read distances through it, so simulation throttling and mesh detail cannot disagree.
+- `syncStaticObjectSource` takes an optional `accept` predicate so one batch can split its instances between two instanced draws.
+- `InstancedScatter` now honours `ModelConfig.variants`: each species-chunk batch asks the same `createModelVariantSelector` the static prop path uses for every placement's level, and each level draws its own instanced meshes claiming only its placements. A chunk that holds near and far palms of one species draws both levels from the one batch; a model without `variants` draws exactly as before.
+- `writeScatterVariantLevel` (`@jgengine/shell` internal, `scatter/scatterVariants`) is the per-frame pass: it writes one level's composed matrices into a reserved slot array and returns `count`, allocating nothing per frame, and takes an optional `keep` predicate so a tier-distance or occlusion cull composes with level selection in one loop.
+- `terrain({ cellSize })` states ground density as world units per quad instead of a segment count, and derives the per-axis grid from `bounds` — the same `cellSize` on a bigger world spends more cells rather than stretching one count across it. `segments` still works and also takes `[x, z]` for a non-square grid. Setting both fails naming `cellSize`; a cell size over the 1,000,000-vertex ceiling fails with the cell/vertex numbers and the smallest `cellSize` that fits.
+- `shoot`, `drive` and `perf` take `--quality <low|medium|high|ultra>` and pin that graphics tier on the game page (`?quality=<tier>`). Each run reads the tier back from the shell (`data-jg-quality`) and fails when it is missing or different, so a capture or perf record always names the tier it measured. Every capture summary prints `tier <tier>`; `perf` echoes `perf: tier <tier>` and records it in `quality`.
+- The old `--quality draft|full` iteration mode is now the `--draft` switch (low tier, half viewport, `-draft` file names), on `shoot`, `drive` and `perf`; `perf:gate` takes `--draft` too. An unknown `--quality` value fails naming all four tiers.
+- `attributeTriangles` (`@jgengine/shell/render/triangleAttribution`) sums a scene's triangles by model and geometry with instance counts, and the devtools render probe publishes it as `probes["render/triangles"]` and the `render/triangles` system probe, so `debug_snapshot` names the object behind a heavy frame instead of only counting it. Harbor Heat read 1,021,671 triangles from 840 objects: the 640 m terrain at 300 segments (180,000), the `TwistedTree_2` foliage species (137,010 over 15 trees) and 93 instances of a 1,280-triangle NPC model.
+- `ShotSpec` and `resolveShotSpec` (`@jgengine/core/combat/shotSpec`) describe how a shot travels and what it does on contact as plain data: an instant trace or a travelling body with speed, gravity, drag, fuse, lifetime, radius and homing, plus contact damage, falloff, penetration, splash, ricochet and statuses. Every field but `delivery.kind` is optional with a documented default, so a plain gun is three lines and a grenade, mortar, arrow or hitscan explosive is the same shape with different numbers. `shotArc`, `shotFalloffAt` and `shotHitOutcome` are the one place trajectory, falloff and penetration are solved; `shotSpecFromStats` and `shotSpecFromWeapon` adapt existing item stats and weapon definitions once, and a splash radius or damage number never decides that a shot travels.
+- `ProjectileShotInput.spec` lets a caller state the spec directly; the projectile and weapon systems read the resolved spec at spawn, fuse, hitscan settle and damage application instead of classifying a shot.
+- A trace that carries splash now resolves its area damage at the contact point on the same tick, which is the #2272 hitscan-explosive configuration.
+- `bun run check:path-portability` fails a test that asserts one platform's path separator: a `\\` literal under `toContain`/`toEqual`/`toBe`/`includes`/`endsWith`, a bare `toContain("/")`, a POSIX root handed to `join`/`resolve`, or a literal compared with an OS path result. It reports the file, the line and the `join(...)` that replaces it. A genuinely single-platform assertion is named in `scripts/path-portability-allow.json` with a reason, printed on every run. This is the class behind #2301 (`toContain("proofs\\flows")`) and the `agent-worktree.test.ts` assertions that only pass on one OS.
+
+Verification:
+- `bun test scripts/check-path-portability.test.ts` - pass, including the pre-fix `proofs\\flows` line failing through the gate and the fixed one passing
+- `bun run check:path-portability` - ok, 3 allowlisted with reasons
+- `bun test scripts/agent-worktree.test.ts scripts/shot-metrics.test.ts scripts/lane-audit.test.ts` - pass
+
+### Changed
+
+- Merge pull request #2309 from Noisemaker111/agent/lane-path-portability
+- `bun run land` hands the PR over instead of waiting for it: it pushes, opens or updates the PR, runs `--verify`, arms auto-merge and exits in seconds, printing the PR URL and `bun run ci:status --pr <n>`. A trivial change spent 5m09s inside `land`'s own poll loop, and one night's lanes spent 449 minutes watching CI. `--watch` still lands the old way and says it is deprecated.
+- `bun run land:queue` is the only process that waits for CI. It lands ready PRs into `beta` in readiness order (auto-merge armed, else the `land:queue` label), rebases a branch whose base moved in a throwaway worktree so a moved base costs one CI run instead of two, waits once per PR and prints one line per PR with its wait time and run id. A lane hands off by running `bun run land`; it never rebases, labels or waits.
+- `bun run lane:close` ends a lane in one command. It stages the worktree's tracked and new files (ignored ones such as `.scratch/` stay out), takes the commit message from the branch's own `changes/` fragment, writes that fragment from the commit summary when the diff has none, pushes, opens or updates the PR with the fragment as the body, arms auto-merge, and prints the PR URL and `bun run ci:status --pr <n>`. One lane's last 20 calls were 13 of commit, push, rebase and PR choreography; this replaces them with one. `bun run land --commit` does the same for a lane that skips `lane:close`, and a clean tree lands as it did before.
+- `bun run bg:run -- <cmd>` starts a long command and returns its id at once; `bun run bg:await <id>` blocks on that task's exit file as an event, then prints its whole output and its exit code. It replaces waiting out a `.out` file with guessed intervals — one lane spent 10 minutes of `Start-Sleep` calls watching a capture it had already started. A runner that dies is answered rather than waited on forever.
+- `--commit` prints every path it will commit before committing, and refuses the ones a lane did not author: a scratch artifact, a path git ignores, a lockfile staged without its `package.json` manifest, and a new `changes/` fragment whose name is not part of the branch's name. `--allow <path>` keeps one refused file on purpose. The first replay committed a test-written `changes/agent-lane-x.md` and this checkout's shared-install `bun.lock` drift; both are refused now, with the file list printed either way.
+- A capture at a non-default tier writes its tier into the file name (`-low`, `-medium`, `-ultra`), so an ultra shot cannot overwrite the high one it was compared against.
+
+Root cause: `--quality` carried the iteration preset, not the graphics tier, so a culling lane that asked for ultra got the game's default `high` on both sides of its comparison and could not prove a tier claim.
+
+### Fixed
+
+- `verify:fast`, `land` and `lane:close` refuse a checkout with no `node_modules` up front: they print the missing marker, the exact fix (`bun install` in this checkout, or `bun run agent:bootstrap`) and exit 78, instead of a `command not found` or a module error from a test file. A genuine failure still exits on its own code.
+- `lane:audit --cwd` finds the lane whose own tool calls name that worktree, and prints `attributed ses_… (N references to …)`. Ambiguous ties name their candidates and pick the worst-waiting one; no candidate at all exits non-zero naming the path it searched, so `--fail-on-waiting` has a lane to judge instead of an empty table.
+- `land` builds the PR body only from `changes/` fragments its own `git diff origin/beta...HEAD` adds, prints a line for every fragment it ignores, and falls back to the branch's commit subjects.
+
+Root cause: a subagent session stores the directory of the agent that spawned it, so a lane was invisible to its own audit; `changes/` is shared by every lane on the branch, so "newest fragment" was free to be a stranger's note.
+
+Before: `lane:audit --cwd …\lane-wait-audit` exited 1 with "no child sessions", and a body built from a stray `changes/` fragment claimed work the diff did not contain.
+After: `lane:audit: attributed ses_e94f3aeedffe2CCMsTlrzgvez5 (136 references to …\lane-wait-audit)`, and `land: ignoring changes/scratch-leftover.md: this branch's diff against origin/beta does not add it`.
+
+Verification:
+- `bun test scripts/lane-audit.test.ts scripts/lane-close.test.ts scripts/land.test.ts` — pass
+- `bun run verify:fast` — pass
+- `bun run lane:audit --cwd <the real lane worktree> --hours 6` — attributed that lane by 136 references
+- `lane:audit` classifies a call by what it runs, not by the text inside its arguments: `rg`, `grep`, `Select-String`, `findstr`, `Get-Content`, `cat`, `echo`, `Write-Output` and `git` (any subcommand) never count as a sleep or a CI watch, and quoted arguments are stripped before matching. A lane that greps for `Start-Sleep` or writes a PR body about `gh run watch` no longer records waiting it never did.
+- Catches the waits it used to miss: `Start-Sleep` under `powershell -Command`/`pwsh -c`/`bash -lc`, `cmd /c "timeout /t"`, `Thread.sleep`, `Atomics.wait`, `Bun.sleep`, and `gh pr checks` inside a `for`/`while` loop.
+
+Over the last 40 hours (209 lanes): sleep 1066.6 -> 1068.7 minutes, CI watch 421.8 -> 421.3 minutes. 15 calls stopped counting as waits, one real `Start-Sleep -Seconds 150` started counting.
+
+Verification:
+- `bun test scripts/lane-audit.test.ts scripts/lane-close.test.ts scripts/land.test.ts` — pass
+- `bun run lane:audit --json --hours 40` before and after, compared per command
+- `lane:close` reads `calls` as the count it is, takes waits from a new `waits` list in `lane:audit --json`, and refuses an unfamiliar audit shape with `the audit output shape changed: <field> is <type>, expected <type> (keys seen: …)` instead of a TypeError. Exit codes unchanged: a sleep or CI watch is 2, `--waive` records the reason, no percentage thresholds.
+
+Root cause: `lane:audit --json` had always reported `calls` as a number, while `lane:close` held it as a list of call objects; nothing read the real document until lane attribution started returning a lane, so the gate that judges a finishing lane crashed on the first lane that had one.
+
+Before: `lane:close` landed the PR, then died with `source.filter is not a function` at `waitingGate`.
+After: the same captured output is judged, the waits are listed, and the lane gets exit 2 with a report skeleton.
+
+Verification:
+- `bun test scripts/lane-audit.test.ts scripts/lane-close.test.ts` — pass, including the captured-output fixture
+- `bun run verify:fast` — pass
+- `shoot --url ... --look` now sends the aim to the page it captures, so a lane can measure a branch on a dev runner it started itself. The read-back stays: a page that reports no applied aim still fails the capture instead of returning a plausible wrong view, and a page that applies `--param look=` itself can report it on `data-jg-look` or `window.__jgLook`. `--site --look` is refused at the command line, naming the `--url` form that works.
+- `check:no-blocking-wait` judges code that waits, not prose that describes waiting. In `packages/<pkg>/src/meta` (the changelog mirror and its neighbours) single- and double-quoted text and comments are masked before matching, so a release note reading "one lane spent 10 minutes of `Start-Sleep`" no longer fails the gate; a command in a template literal still fails, and every other `scripts/**` path keeps the strict rule where a quoted command is a real finding. The 0.37.0 release cut failed `types` on `packages/core/src/meta/changelog.ts:46,55,56` with exactly that false positive.
+- `@jgengine/rapier` now accumulates `step(dt)` into its fixed substeps instead of stepping once per call with `fixedDt` as the timestep. A 1 s move covered 0.5 s of simulated time at 30 fps and 2.4 s at 144 fps; it now covers 1 s at either rate, matching `PhysicsWorld` and the `PhysicsBackend` contract.
+- `PhysicsWorld` bounds-floor friction is Coulomb (`friction × g × dt`) like contact friction, not a 60 Hz multiplicative brake: a crate sliding at 4 m/s travelled 0.165 m on the world floor and 0.970 m on a floor collider, and now travels 0.967 m on both.
+- Player and character-controller gravity integrate trapezoidally, so a jump reaches `v²/2g` at any frame rate: the default jump peaked at 0.933 m at 30 fps and 1.026 m at 144 fps, and now at 1.050 m for both.
+
+## 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/combat/projectiles.d.ts

@@ -4,10 +4,13 @@ import type { EntityColliderSet } from "../scene/colliders.js";
 import { type SceneRaycastApi } from "../scene/sceneRaycast.js";
 import type { Aim } from "../scene/spatial.js";
 import type { CombatSpatialDeps, EffectResult, EffectSystem, EffectVia } from "./effects.js";
+import { type ShotSpec } from "./shotSpec.js";
 import { type ShotOriginPolicy } from "./shotOrigin.js";
 export interface ProjectileShotInput {
     from: string;
     via: EffectVia;
+    /** How this shot travels and what it does on contact. Omitted means the shot's numeric stats are adapted once. */
+    spec?: ShotSpec;
     aim: Aim;
     effect: string;
     /** Defaults to `{ kind: "converge" }` — explicit rays pass through; angular aim converges from the muzzle to the sightline. */
@@ -121,8 +124,9 @@ export interface ProjectileSettleReport {
     effect: string;
     hit: boolean;
     /**
-     * True for lobbed/exploding shots (grenades, launchers, rockets) whose real path is an arc,
-     * false for direct-fire shots (bullets, bolts) that travel muzzle→impact in a straight line.
+     * True for lobbed fused rounds (grenades, launchers, rockets) whose real path is an arc,
+     * false for direct-fire shots (bullets, bolts) that travel muzzle→impact in a straight line,
+     * including direct-fire shots that carry an explosion.
      * Presentation uses it to keep straight-line tracers off arced projectiles.
      */
     ballistic: boolean;