@jgengine/core 0.25.0 → 0.27.0

package/skills/jgengine-combat/capabilities.md

@@ -12,6 +12,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createAntiOneShotPolicy` (function) · `import { createAntiOneShotPolicy } from "@jgengine/core/combat"`
 
+## armor-bypass — ask whether a damage type ignores armor points
+
+- `typeBypassesArmor` (function) · `import { typeBypassesArmor } from "@jgengine/core/combat"`
+
+## armor-mitigation — read the fraction of a hit armor removes at a given armor value
+
+- `armorMitigation` (function) · `import { armorMitigation } from "@jgengine/core/combat"`
+
 ## capture-bonus-levels — convert wild level and capture effectiveness into bonus levels
 
 - `captureBonusLevels` (function) · `import { captureBonusLevels } from "@jgengine/core/stats/spawnLevelStats"`
@@ -40,6 +48,26 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createComboPoints` (function) · `import { createComboPoints } from "@jgengine/core/combat"`
 
+## cover-field — authored-geometry cover with a bounded nearest query and rebuild on edit
+
+- `createCoverField` (function) · `import { createCoverField } from "@jgengine/core/combat"`
+
+## cover-points-from-solids — derive stand-able cover positions from authored solid boxes
+
+- `coverPointsFromSolids` (function) · `import { coverPointsFromSolids } from "@jgengine/core/combat"`
+
+## cover-points-near — bounded nearest-cover query
+
+- `coverPointsNear` (function) · `import { coverPointsNear } from "@jgengine/core/combat"`
+
+## cover-score — threat-driven cover point scoring
+
+- `scoreCoverPoint` (function) · `import { scoreCoverPoint } from "@jgengine/core/combat"`
+
+## cover-select — select cover by threat, role range and flank angle
+
+- `selectCover` (function) · `import { selectCover } from "@jgengine/core/combat"`
+
 ## damage-clamp — cap incoming damage per hit at a configured maximum
 
 - `createDamageClamp` (function) · `import { createDamageClamp } from "@jgengine/core/combat"`
@@ -60,6 +88,42 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createDamagePipeline` (function) · `import { createDamagePipeline } from "@jgengine/core/combat"`
 
+## damage-runtime — resolve hits through a damage table, hit zones, and armor, and tick data-defined statuses with declared stacking
+
+- `createDamageRuntime` (function) · `import { createDamageRuntime } from "@jgengine/core/combat"`
+
+## damage-table — score a data-defined damage type against a resistance class, with the outcome readable as a table
+
+- `typeMultiplier` (function) · `import { typeMultiplier } from "@jgengine/core/combat"`
+
+## damage-table-format — render damage-table rows as fixed-width lines for a probe, a CLI dump, or a test
+
+- `formatDamageTable` (function) · `import { formatDamageTable } from "@jgengine/core/combat"`
+
+## damage-table-read — read a damage table as rows of type × resistance × armor mitigation, with final damage per base
+
+- `readDamageTable` (function) · `import { readDamageTable } from "@jgengine/core/combat"`
+
+## damage-table-resolve — resolve a damage type against a resistance class and armor into a multiplier, mitigation, and final damage
+
+- `resolveTableDamage` (function) · `import { resolveTableDamage } from "@jgengine/core/combat"`
+
+## damage-table-validate — reject a damage table with duplicate types or non-finite multipliers before combat runs
+
+- `assertDamageTable` (function) · `import { assertDamageTable } from "@jgengine/core/combat"`
+
+## damage-target-unknown — reject a hit on a target with no registered resistance or armor profile
+
+- `UnknownTargetProfileError` (class) · `import { UnknownTargetProfileError } from "@jgengine/core/combat"`
+
+## damage-type-duplicate — reject a damage table that defines one type twice
+
+- `DuplicateDamageTypeError` (class) · `import { DuplicateDamageTypeError } from "@jgengine/core/combat"`
+
+## damage-type-unknown — reject a hit whose damage type the table does not define instead of dealing 1×
+
+- `UnknownDamageTypeError` (class) · `import { UnknownDamageTypeError } from "@jgengine/core/combat"`
+
 ## death-system — resolve entity death and its on-death consequences
 
 - `createDeathSystem` (function) · `import { createDeathSystem } from "@jgengine/core/combat"`
@@ -132,6 +196,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createAbilityKit` (function) · `import { createAbilityKit } from "@jgengine/core/combat"`
 
+## hit-zone — resolve a hit zone into one damage multiplier, crit by zone with an injected RNG
+
+- `resolveHitZone` (function) · `import { resolveHitZone } from "@jgengine/core/combat"`
+
+## hit-zone-multiplier — quote a zone's multiplier for a known crit outcome without rolling
+
+- `hitZoneMultiplier` (function) · `import { hitZoneMultiplier } from "@jgengine/core/combat"`
+
+## hit-zone-unknown — reject a hit zone table whose named default does not exist
+
+- `UnknownHitZoneError` (class) · `import { UnknownHitZoneError } from "@jgengine/core/combat"`
+
+## hit-zone-validate — reject a hit-zone table with duplicate zones or a missing default
+
+- `assertHitZoneTable` (function) · `import { assertHitZoneTable } from "@jgengine/core/combat"`
+
 ## hitscan-shot — aim a hitscan shot (shoot a gun): resolve origin and direction from the eye or muzzle for a raycast
 
 - `resolveShot` (function) · `import { resolveShot } from "@jgengine/core/combat"`
@@ -199,6 +279,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `resolveSpawnStats` (function) · `import { resolveSpawnStats } from "@jgengine/core/stats/spawnLevelStats"`
 
+## squad-combat — threat-driven cover, flanking, suppression, retreat and role-driven fire discipline
+
+- `createSquadCombat` (function) · `import { createSquadCombat } from "@jgengine/core/combat"`
+
+## squad-roles — deterministic role assignment over a caller-authored composition
+
+- `assignSquadRoles` (function) · `import { assignSquadRoles } from "@jgengine/core/combat"`
+
 ## stagger-meter — accumulate an ailment buildup (bleed, freeze) until it procs
 
 - `createBuildupMeter` (function) · `import { createBuildupMeter } from "@jgengine/core/combat"`
@@ -236,6 +324,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createEffectSystem` (function) · `import { createEffectSystem } from "@jgengine/core/combat"`
 
+## status-runtime — tick data-defined statuses (burn, shock, slow, corrode) with declared stacking rules and per-tick effects
+
+- `createStatusRuntime` (function) · `import { createStatusRuntime } from "@jgengine/core/combat"`
+
+## status-unknown — reject a status id the runtime has no definition for
+
+- `UnknownStatusError` (class) · `import { UnknownStatusError } from "@jgengine/core/combat"`
+
+## threats-from-memory — turn perception memory into a bounded, ranked threat list
+
+- `threatsFromMemory` (function) · `import { threatsFromMemory } from "@jgengine/core/combat"`
+
 ## threshold-crossings — emit ordered crossing events as a numeric source passes named thresholds with hysteresis and once/repeat policy
 
 - `createThresholdTracker` (function) · `import { createThresholdTracker } from "@jgengine/core/combat"`
@@ -248,6 +348,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `vfxPresets` (const) · `import { vfxPresets } from "@jgengine/core/combat"`
 
+## weapon-cadence — convert a rounds-per-minute weapon rate into the interval a fire gate takes
+
+- `weaponIntervalMs` (function) · `import { weaponIntervalMs } from "@jgengine/core/combat"`
+
+## weapon-definition-validate — reject a malformed weapon definition at construction with the field named
+
+- `assertWeaponDefinition` (function) · `import { assertWeaponDefinition } from "@jgengine/core/combat"`
+
 ## weapon-feedback — turn weapon shots, recoil kick and impacts into per-tick feedback-mixer signals for camera shake, audio and rumble
 
 - `createWeaponFeedbackSignals` (function) · `import { createWeaponFeedbackSignals } from "@jgengine/core/combat/weaponFeedback"`
@@ -267,3 +375,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## weapon-runtime — compose cadence, magazine, a caller-owned raycast, and portable damage resolution into a fire controller
 
 - `createWeaponRuntime` (function) · `import { createWeaponRuntime } from "@jgengine/core/combat"`
+
+## weapon-system — run a data-defined weapon: fire modes, recoil and bloom, hitscan or ballistic projectiles, interrupted reloads and readable ammo, all resolving through the damage runtime
+
+- `createWeaponSystem` (function) · `import { createWeaponSystem } from "@jgengine/core/combat"`

package/skills/jgengine-combat/reference.md

@@ -141,6 +141,27 @@ Genre systems layered over the same effects/projectiles/targeting/loot primitive
 - **Resistance matrix** (`combat/resistance`) — a damage-category × target-property table distinct from `combat/attackTags` (those are defense tags). `resolveResistance(matrix, category, targetProperties)` → `{ verdict: "immune" | "resist" | "normal" | "vulnerable", multiplier, immune }`; `resistanceScale` returns just the multiplier (default `immune:0, resist:0.5, normal:1, vulnerable:2`, overridable). Immune on any property wins; resists stack multiplicatively. Sits over the `receive` gate — the handler multiplies its effect `amount` by the scale (Bloons lead/camo immunities, elemental RPG weaknesses).
 - **Run draft** (`game/runDraft`, built on `world/scatterItems` `pickWeighted` + `stats/statModifiers`) — `createRunModifierStack(offers)` accumulates stacking picks (`add`, `count`, `atMax`, `total(stat)` aggregating adds × exponentiated multiplies, `apply(stats)` onto a `createStats` source). `createRunDraft({ offers, rng? })` adds the pause-flow: `present(n)` draws N distinct weighted offers (excluding maxed-out ones), `choose(id)` applies to the stack. Pause/resume is game-side (`ctx.time.pause()` before `present`, `play()` after `choose`). Vampire Survivors level-up picks, Hades boons, Risk of Rain stacking items.
 
+## Damage model, armor, crits, and statuses
+
+`createDamageRuntime` (`combat/damageRuntime`) is the stateful in-process composition of the table, the zones, the armor curve, and carried statuses. A number reads as `base × zone multiplier × type multiplier × (1 − armor mitigation)`; `hit()` returns every stage, `tick()` ticks statuses through the same table and armor, `timeToKill()` quotes a fight, and `table()` reads the whole chart. `snapshot()`/`restore()` carry registered targets and carried statuses; `retune()` swaps table, zones, or definitions without dropping either. For multiplayer authority, keep the pure stages (`resolveMatchup`, `resolveReceivedDamage`, `resolveStatusApplication`) and replicate their results instead.
+
+- **Type × resistance table** (`combat/damageTable`) — `{ types: [{ id, vs: { armor: 2, flesh: 0.5 }, bypassArmor? }], armor: { halfValue, maxMitigation }, defaultMultiplier? }`. `typeMultiplier` reads one pair; `resolveTableDamage` folds type, armor, and base into a row; `readDamageTable` returns every row at given armor values and `formatDamageTable` prints them. Armor uses `armor / (armor + halfValue)` — armor equal to `halfValue` halves the hit — so a designer reads the number rather than guessing a percentage per point. Unknown types throw; unknown resistance classes use the default.
+- **Hit zones and crits** (`combat/hitZones`) — `{ zones: [{ id, multiplier?, critChance?, critMultiplier? }], defaultZone, critChance?, critMultiplier? }`. `resolveHitZone(table, zone, rng)` rolls once and returns **one** multiplier: a crit replaces the zone's normal multiplier (head 1.5× normal, 2.5× crit → 2.5×, never 3.75×). `hitZoneMultiplier(table, zone, crit)` quotes the same number without a roll, which is what `timeToKill({ crit: true })` uses.
+- **Statuses** (`combat/statusRuntime`) — `createStatusRuntime({ statuses, rng?, applyDamage? })`; each `StatusDef` declares `{ id, stack, durationMs, intervalMs?, magnitude?, effect?, chance? }`. `stack` is the existing `StatusStackPolicy` (`refresh` / `stack` to `max` / `replace` / `ignore`), and it is the only thing that changes stacks: a tick deals `magnitude × stacks`, so two burns at 4 per tick deal 8, never 16. `effect` is `{ kind: "damage", channel }` (routed through `applyDamage`, so resistances and armor apply) or `{ kind: "stat", stat }` (read with `statDelta`, e.g. negative `moveSpeed` for slow or negative `armor` for corrode). Reapplication restarts the tick clock instead of banking a burst; ticks per call are bounded and the remainder carries. `dotField` stays the cheap no-stacking scheduler.
+
+## Weapons as data
+
+`createWeaponSystem` (`combat/weaponSystem`) runs one `WeaponDefinition` (`combat/weaponDefinition`): plain JSON with `roundsPerMinute`, `fireMode` (`single` / `auto` / `burst` + `burst.count`), `delivery` (`hitscan` + `maxRange`, or `projectile` + `speed` / `gravity` / `drag` / `lifetime`), optional `magazine`, `handling` (the same recoil bloom and ADS tuning `createWeaponHandling` takes), `damage` (`type`, `base`, optional `statuses`), optional `falloff`, `pellets`, `maxInFlight` and `autoReload`. Nothing in it is a function, so a generator rolls it and a save stores it; `assertWeaponDefinition` rejects a bad roll at construction with the field named.
+
+- **Loop.** `setAim(yaw, pitch)` from look input, `setTrigger(down)`, `tick(dt, stance)` → `{ shots, impacts }`. A press survives to the next tick that can use it; a tap does not repeat. Recoil is applied to the aim before the shot leaves, so `record.directions` and the world query see the kicked vector, and `aim()` reports it with recovery folded in.
+- **Spread and bounds.** Each pellet samples the cone uniformly over solid angle from the injected `rng`; zero spread draws nothing. One tick fires at most `maxShotsPerTick` (default 4, clamp 16) catch-up shots and keeps the remaining budget, so a stalled frame cannot turn into a long burst.
+- **Delivery.** A hitscan calls your `raycast(from, direction, maxRange)` on the firing tick. A projectile is stepped with semi-implicit Euler (drag, then gravity), swept as one segment per tick so it cannot tunnel, and resolved when `sweep(from, to)` reports a contact. Both build the same `DamageRuntimeHitInput` for `createDamageRuntime().hit()`, so zone, type, armor, status rolls and provenance are identical; only the distance differs. Falloff scales `base` by the distance the pellet actually travelled.
+- **Live pellets are capped** by `maxInFlight` (default 32, max 256); excess pellets of a shot are counted in `stats().pelletsDropped` rather than queued.
+- **Reload states.** `reload()` starts or continues; `interruptReload()` suspends through `Magazine.pauseReload` keeping progress; `resumeReload()` continues from it; `cancelReload()` discards. `ammo()` returns loaded / capacity / reserve / state / reload fraction / burst remaining / cadence fraction, and `stats()` carries shots, rounds spent, pulls, reloads, drops and damage dealt — the whole ammo economy is readable without touching internals.
+- **State.** `snapshot()` / `restore()` carry aim, handling, magazine, trigger, burst, pellets and counters as plain data; `retune(definition)` swaps rate, feel, damage and capacity without losing ammo or aim (a shrinking magazine discards rounds above the new capacity); a `devtoolsName` registers a one-line probe.
+- **When to use which.** `createWeaponRuntime` (`combat/weaponFire`) is the minimal plumbing for a game that already owns its fire loop and raycaster; `createWeaponSystem` is the definition-driven version with fire modes, ballistics, reload states and ammo accounting. Both leave models, audio, muzzle flash, camera and input to the game; feel numbers come from `measureWeapon` and presentation from `weaponPresentation`.
+- **Evidence** (`combat/weaponSystem.test.ts`): the test fixture at 600 rpm with a 30-round magazine empties in 2.9 s, climbs 17.0° pitch and 3.1° yaw over the magazine, is back to half climb in 0.37 s and within 5% in 0.6 s; bloom runs 2.0 → 8.0 → 12.0 mrad (cap) by the tenth shot and settles to base 0.63 s after the last shot. A hitscan and a projectile contact at the same distance produce the same 20 damage (30 on a 1.5x head zone), and one second of held fire cannot exceed four shots.
+
 ## Encounter sequencing
 
 `combat/encounterSequence` is the genre-agnostic hierarchical sequencer behind arenas, raids, tutorials, races, defense phases, and scripted objectives — a serializable state machine over caller-defined phase `data` with **no built-in wave/boss concept**. State is plain JSON (the working tree, per-node runtime, active path, elapsed) so a mid-encounter save round-trips; the predicate/spawn registries live in the config you re-supply alongside it, the way `advanceSpawnDirector` pairs config with state.
@@ -149,3 +170,14 @@ Genre systems layered over the same effects/projectiles/targeting/loot primitive
 - **Completion predicates** — `completion: { kind, params }` names a registered evaluator; `BUILTIN_COMPLETION_PREDICATES` ships `immediate`, `manual`/`flag`, `timer` (phase seconds), `cleared` (tagged count drained), `metric` (live threshold), `event` (cumulative count), and `quorum` (N of nested predicates). Signals (`counts`/`metrics`/`events`/`flags`) come in through `ctx.signals`; evaluation is deterministic. Register your own via `config.predicates`.
 - **Spawn providers** — spawning is one optional node adapter: `spawn: { kind, params }` invoked on enter. `BUILTIN_SPAWN_PROVIDERS.points` reads a named authored scene point list from `ctx.spawnPoints` (coordinates stay in the scene, referenced by key — never embedded in the sequence); `list` echoes inline requests. Register catalog/director-backed providers via `config.spawnProviders`.
 - **Injection & scripted control** — `injectPhase(state, phase, { after | before | childOf })` inserts a phase or branch at runtime (e.g. a boss after the final wave) into the serializable tree without disturbing active/completed nodes; `forceCompletePhase` completes the active phase regardless of its predicate for scripted skips and failure/retry, restoring the authored predicate afterward.
+
+## Enemy squad AI
+
+`createSquadCombat` (`combat/squadCombat`) is the combat half of an NPC squad: it reads the perception memory the game already keeps (`createPerception`, B1.4) and moves through the nav crowd it already owns (`createNavCrowd`, B1.2). It never sees a global player position — a member reacts to what its own memory or a squadmate's shared sighting says, so losing contact means losing the fight.
+
+- **Cover comes from geometry.** `createCoverField({ solids })` turns authored solid boxes (a `WorldSolid` list drops in) into stand points on every vertical face, clear of the corners and filtered by `walkable: (p) => nav.findPolygon(p) !== null`; `rebuild(solids)` re-derives after an editor edit. A game with its own spatial index supplies the narrower `CoverSource` instead: `near(position, radius, limit)`, bounded per call. Never author a coordinate list for cover.
+- **Selection is by threat.** `selectCover(points, query)` scores each point on `hidden` (confidence-weighted share of remembered threats whose line of sight it blocks, including a body-sized footprint), the role's `preferredRange`, its `flankAngle` around the threat, distance, a squadmate's claim, and whether the walk to it is a detour. A point that hides from one of two shooters is not cover; a memory below `minConfidence` stops steering.
+- **Roles are content.** `assignSquadRoles(members, { roles })` maps names and counts to members deterministically; a role carries `preferredRange`, `flankAngle`, `retreatBelow`, `holdCover`, `discipline` (hold/peek/peek distance/fire interval) and `cover` weights. The engine has no role list, and `"assault"`, `"support"`, `"flanker"` exist only in the game's composition.
+- **Behavior over a tick.** A member picks cover, walks to it, leans out for `peekSeconds` to shoot (`peekSpot` steps around the corner it hides behind), then drops back. `underFire(memberId, amount)` raises suppression, which pins the member to its cover and cancels its peeks until the meter decays. Below a role's `retreatBelow`, the member falls back to the point furthest from the threat. After `relocateAfterSeconds` of continuous exposure it stops trusting its point and moves, which is what breaks a long spell in the open.
+- **Wiring.** `engage(memberId, targetId, distance)` is the paced shot: resolve damage in your own pipeline, call `underFire` on the victim, push a `damage` stimulus at the shooter's position so a member learns about a shooter it cannot see. `healthOf` reads authoritative health, `teamOf` decides who is hostile, `blocked` is your collision layer. `snapshot()`/`restore()` carry member decisions, the crowd and the tuning, so a save mid-fight resumes the same fight.
+- **Evidence.** `combat/squadCombat.soak.test.ts` is the reference run: 2v4 in an authored arena, 90 s, exposure measured every tick against the walls from live positions. Worst exposure 2.33 s against a 3 s bar, 0 of 38 exposure spells over 3 s, p50 0.05 ms per tick. Copy its shape (authored boxes, nav grid with the same holes, perception observing live positions) rather than trusting a flag.

package/skills/jgengine-gameplay/SKILL.md

@@ -38,6 +38,37 @@ Pins consume no choice RNG and must satisfy the same pool and constraints;
 incompatible pins backtrack earlier unpinned choices or return `unsatisfiable`
 within the configured attempt and pick budgets.
 
+Roll whole named gear from an authored catalog with `rollLoot`
+(`loot/lootGen`): bases with mount slots, parts, affix pools, weighted rarity
+tiers, manufacturer stat personalities and a level curve, all caller data.
+`validateLootItem` names each defect, `compareLootItems` returns per-stat deltas
+and a weighted score, and `lootWeaponDefinition` (`loot/lootWeapon`) projects a
+rolled item onto a `WeaponDefinition` for `createWeaponSystem`. `createLootRoller`
+counts drops per rarity for a debug probe and snapshots its counters. Sample
+catalog, distribution check and generated-weapon proof are in
+[reference-systems.md](reference-systems.md#procedural-gear).
+
+Resolve an authored XP curve with `defineXpCurve` (`progression/xpCurve`): one growth rule
+(`flat`, `linear`, `power`, `geometric`, `table`), a `maxLevel` cap and a stated `rule` string;
+`table()` and `totalXpFor()` read the same data, and `track()` hands those thresholds to
+`leveling`. Spend a character's points in `createSkillTree` (`progression/skillTree`): nodes carry
+a point `cost`, `requires`, `excludes`, `passives` and `actives`, `synergies` pay off two or more
+ranked nodes together, `respec()` refunds exactly the points spent, and `resolved()` returns the
+`StatModifierSet` plus ability-slot-shaped actives to feed `createStats` / `createAbilityKit`.
+Score a whole loadout with `gearScore` (`progression/gearScore`) on the same weight policy as
+`compareLootItems`. [reference-systems.md](reference-systems.md#progression-and-gear-score) shows
+the data shapes and a two-build comparison.
+
+Wear gear with `createEquipment` (`inventory/equipment`): slot defs own accepted kinds and the slots
+they block, item defs own the slots an item may occupy, a filled slot swaps and hands back the
+replaced item, and `state()` / `restore()` round-trip the worn set. Weigh a character with
+`characterLoad` (`inventory/carryLoad`), which turns carried inventories plus worn gear into the
+shared encumbrance bands (`moveMultiplier`, sprint/jump gates, `remaining`), so `canCarry` gates a
+pickup. Declare a stash as its own inventory (`tier: "banked"`) and move items with
+`InventorySet.move`; `snapshot()` / `restore()` save both as detached data. The bag and stash render
+through `<InventoryGrid>` with `<EquipmentSlots>` above it. See
+[inventory, equipment and weight](reference-systems.md#inventory-equipment-and-weight).
+
 Validate generated quest catalogs with `validateQuestCatalog` (`game/questCatalog`).
 Follow the [quest authoring recipe](recipes/quest-authoring.md) for bounded batches,
 canonical facts, external unlock declarations, and precise repair diagnostics.
@@ -63,6 +94,14 @@ bounded batches, repair located issues and require explicit semantic approval.
 
 Prefer `defineSystem` and `defineGame({ systems })` for scheduled capabilities. Keep boot/join in the game loop only when it is truly lifecycle glue. System ordering, frequency, and serialization are explicit; avoid a giant per-frame callback.
 
+## Days and off-screen agents
+
+`resolveRoutine` (`sim/routine`) resolves an authored day (home, work, meal) against the world clock: injected travel time makes each stop depart early enough to arrive on time, and an arrival that runs late slips instead of teleporting. The timeline is pure, so a save, a forecast and a live agent read the same day.
+
+`createOffScreenWorld` (`sim/offScreen`) keeps every resident either near or cheap. Near residents spawn into your own simulation through `NearAgents`; far ones are a position, a routine phase and a needs record that only move when the clock crosses a routine boundary — no navigation, no needs tick, no utility decision. The distance radius, optional cost model and per-tick switch budget are game config. Crossing back in spawns the resident where the cheap state says it is, with its schedule progress and needs intact, so it cannot pop in at the origin.
+
+`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.
+
 For staffed production, use `stationOutputRate` (`work/staffedStation`) to resolve
 caller-owned worker stats and efficiency, then feed the rate to `tickProduction`.
 Keep staffing and production progress in the same serializable store; the