@jgengine/core 0.28.0 → 0.30.0

package/skills/jgengine-gameplay/recipes/agent-lives.md

@@ -0,0 +1,76 @@
+# Agent lives: needs, mood, relationships, schedules
+
+One system for every resident that wants something. `createAgent` (`@jgengine/core/agents/agent`)
+composes four owners that already exist: `createNeedSet` (`sim/needs`) decays the needs,
+`createUtilityBrain` (`ai/utilityBrain`) scores what to do, `resolveRoutine` (`sim/routine`) says
+where the day plan puts the agent, and `createMoodReader` (`agents/mood`) reads how satisfied it is.
+A game supplies the targets its world offers and owns the body, the nav and the art.
+
+```ts
+import { createAgent } from "@jgengine/core/agents/agent";
+import { createRelationshipBook } from "@jgengine/core/agents/relationships";
+
+const needs = [
+  { id: "hunger", max: 100, rate: 0.9 },
+  { id: "fun", max: 100, rate: 0.6 },
+  { id: "energy", max: 100, rate: 0.5 },
+];
+
+const agent = createAgent({
+  id: "guest:1",
+  needs,
+  options: [
+    { id: "eat", terms: [{ need: "hunger", curve: { kind: "linear", from: 0.2, to: 0.95 } }] },
+    { id: "ride", terms: [{ need: "fun", curve: { kind: "linear", from: 0.15, to: 0.9 } }] },
+    { id: "seat", base: 0.05, terms: [{ need: "energy", curve: { kind: "linear", from: 0.1, to: 1 } }] },
+    { id: "work", base: 0.2 },
+  ],
+  schedule: {
+    cycleSeconds: 86_400,
+    stops: [
+      { place: "home", arriveAt: 0, activity: "sleep", refill: { energy: 70 } },
+      { place: "lobby", arriveAt: 30_000, activity: "work", beat: ["hall-a", "hall-b", "hall-c"] },
+      { place: "cafe", arriveAt: 50_000, activity: "meal", refill: { hunger: 60 } },
+    ],
+    travelSeconds: (from, to) => distances.get(`${from}>${to}`) ?? 60,
+  },
+  mood: { weights: [{ need: "hunger", weight: 2 }, { need: "fun", weight: 1 }] },
+  rng: ctx.rng,
+});
+
+agent.update({
+  dt,
+  now: ctx.time.now(),
+  targets: [
+    { option: "ride", target: "coaster", cost: queueSeconds, fallback: { option: "seat", target: "bench" } },
+    { option: "eat", target: "burger-stall", cost: walkSeconds },
+    { option: "seat", target: "bench" },
+  ],
+});
+```
+
+Read the frame, not the internals: `frame.action` (`option`, `target`, `usedFallback`), `frame.mood`
+(`score`, `tier`, `label`), `frame.phase` and `frame.post` (where the schedule and the work beat put
+the agent), and `frame.changed` with `frame.reason`. `targets` is the world as it is this tick, so a
+sold-out stall simply is not in the list, and a pick whose target disappears moves to its declared
+`fallback` instead of freezing.
+
+- **Saved state.** `agent.snapshot()` carries needs (values, rates, modifiers), mood sources, the held
+  pick and its dials, the action, the far flag and the schedule stop the agent last ate at. The day
+  plan itself is authored data resolved from the clock, so it is never saved. Put every agent's
+  snapshot and one `book.snapshot()` in the save document.
+- **Far agents.** `agent.setFar(true)` stops the utility pass: the agent keeps decaying and follows
+  its schedule, and its action reads off the phase. A far agent costs no decision and no nav.
+- **Mood from the world.** `agent.moodSources.setSource("queue", -20)` and `clearSource` let a queue,
+  litter, a broken ride or a cold snap move the feeling without giving mood its own state machine.
+- **One relationship book per world.** `book.socialise(a, b, { opinion: 6, familiarity: 0.1 })` returns
+  the pair before and after plus the milestones crossed. `book.prefersCompanyOf(a, b)` is a friendship
+  a game can act on by seating them together; `book.refusesToSplit(a, b)` is a bond that must not be
+  posted to separate shifts. A bond needs opinion *and* time shared, so one good afternoon is not
+  enough.
+- **A work beat is not a special case.** A stop with `beat` walks those places in order for
+  `beatDwellSeconds` each; a janitor, a security guard and a tour guide are the same agent with
+  different authored beats. Off-hours behaviour is a stop without a beat.
+- **Determinism.** Pass `ctx.rng` and set `jitter`; two agents built from the same seeded stream make
+  the same choices. The game owns the RNG cursor in its save (`createGameSave` `rng`), since one
+  stream is usually shared by the whole world.

package/skills/jgengine-world/api.md

@@ -46,6 +46,58 @@
 - `planLookahead` (function): function planLookahead<S, M>(root: S, domain: LookaheadDomain<S, M>, profile: DifficultyProfile, rng: () => number): M | null — Pick the agent's next move by bounded lookahead: a depth-limited negamax (or single-perspective sequence search when `adversarial: false`) over the caller's {@link LookaheadDomain}, exploring at most `profile.planWidth` moves per ply to `profile.planDepth` plies, with the final root choice run through {@link pickScored} so `decisionNoise` still injects tier-appropriate blunders. Depth `1` is greedy — an easy profile literally cannot see the fork coming; an expert profile finds multi-ply tactics. Work is bounded by `planWidth ** planDepth` domain calls; run it at decision cadence (turns, ability windows, order re-evaluation), not per frame.
 - `shouldUseAbility` (function): function shouldUseAbility(opportunity: number, profile: DifficultyProfile, rng: () => number): boolean — Should the agent spend an ability now? `opportunity` is the caller-scored quality of this moment in `0..1` (targets clumped for the AoE, player mid-animation, burn phase). The perceived opportunity is fuzzed by `decisionNoise` and compared against `abilityDiscipline`: an easy profile (low discipline, high noise) wastes cooldowns on weak moments and sometimes sits on a perfect window; an expert profile fires exactly on strong windows. One rng draw when noisy.
 
+## @jgengine/core/ai/director/boss
+
+- `BossBehaviour` (type): type BossBehaviour = Omit<SquadRole, "id" | "count"> — The role shape a boss fights with in one phase: the same dials a squad role uses.
+- `BossPhase` (interface): interface BossPhase — One authored phase: the health it starts at, how the boss fights, and its tell.
+- `BossState` (interface): interface BossState — Serializable boss state: which phase holds, how long it has held, and the tell still on screen.
+- `BossStep` (interface): interface BossStep — One step of the boss clock.
+- `BossTell` (interface): interface BossTell — The warning a boss gives while it changes phase, and how long the player has to read it.
+- `advanceBoss` (function): function advanceBoss(phases: readonly BossPhase[], state: BossState, health: number, dt: number): BossStep — Advance the boss by `dt` at a health fraction and return the phase in effect.
+- `bossPhase` (function): function bossPhase(phases: readonly BossPhase[], health: number): BossPhase — The phase a boss fights with at a health fraction. Pure read for a HUD; never mutates.
+- `createBossState` (function): function createBossState(phases: readonly BossPhase[]): BossState — Fresh boss state for a phase list, opening in phase 0 with no tell showing.
+
+## @jgengine/core/ai/director/encounter
+
+- `Encounter` (interface): interface Encounter — Live encounter: opens waves, emits timed spawn orders, and round-trips through a save.
+- `EncounterConfig` (interface): interface EncounterConfig — Construction options for {@link createEncounter}.
+- `EncounterDefinition` (interface): interface EncounterDefinition — A whole encounter, authored as data instead of spawned in game code.
+- `EncounterGroup` (interface): interface EncounterGroup — One authored group inside a wave: what arrives, how many, where from, and when. `unit` and `entry` are game-owned ids — the engine never resolves them.
+- `EncounterOrder` (interface): interface EncounterOrder — One unit the director says should enter now.
+- `EncounterPressure` (interface): interface EncounterPressure — The subset of a pressure plan the encounter layer applies.
+- `EncounterState` (interface): interface EncounterState — Serializable encounter state.
+- `EncounterView` (interface): interface EncounterView — Pooled per-frame readout of where the encounter stands.
+- `EncounterWave` (interface): interface EncounterWave — One authored wave.
+- `createEncounter` (function): function createEncounter(config: EncounterConfig): Encounter — Create a live encounter over an authored definition: open a wave, step its clock, take the orders whose time has come, and close the wave when the game says it is cleared.
+- `expandWave` (function): function expandWave(config: EncounterConfig, waveIndex: number, pressure: EncounterPressure = {}): EncounterOrder[] — Expand one authored wave into the units it sends, at the times it sends them.
+
+## @jgengine/core/ai/director/pressure
+
+- `PressurePlan` (interface): interface PressurePlan — One bounded answer to "how hard now", plus the effects the encounter layer applies.
+- `PressureReading` (interface): interface PressureReading — Encounter pressure: how hard a director leans on a player who is struggling, read from the player's own state, quantized to a tier, and bounded by the rule's cap. The plan is a value, not a callback, so a test can sweep it and a probe can print it.
+- `PressureRule` (interface): interface PressureRule — The weights and window that turn a reading into an index, plus the hard cap.
+- `evaluatePressure` (function): function evaluatePressure(reading: PressureReading, rule: PressureRule = {}): PressurePlan — Turn one reading into a bounded pressure plan.
+
+## @jgengine/core/ai/director/roles
+
+- `FightIntent` (type): type FightIntent = "retreat" | "hold" | "flank" | "cover" | "assault" — The five duties a fighter can be given in a fight. A duty is *who does what*; the squad role a game dials (range, angles, fire discipline) is *how that duty fights* and stays content.
+- `FightOrders` (interface): interface FightOrders — What the director decided, per fighter, and why.
+- `FightSituation` (interface): interface FightSituation — The squad as it stands and the enemy it is facing, or no enemy at all.
+- `FighterState` (interface): interface FighterState — One fighter the director can order, with the state the decision reads.
+- `assignFightIntents` (function): function assignFightIntents(situation: FightSituation): FightOrders — Assign each fighter a duty from the squad's own state — who is hurt, who is under fire, and who already stands on the outside of the formation — never from an authored order or a spawn index.
+- `compositionForIntents` (function): function compositionForIntents(order: readonly string[], intents: ReadonlyMap<string, FightIntent>, roleFor: (intent: FightIntent) => SquadRole): SquadComposition — Turn duties into a squad composition `createSquadCombat` accepts: one slot per fighter, in the order the game gives its members, each mapped to the role that game dials for the duty. Build it through `composition` so squad combat executes the director's assignment instead of its own static list.
+
+## @jgengine/core/ai/director/sound
+
+- `Investigation` (interface): interface Investigation — A hunter still working a noise, as the squad layer reads it this tick.
+- `NoiseEvent` (interface): interface NoiseEvent — One noise in the world, as the game produces it.
+- `SoundHunt` (interface): interface SoundHunt — Sound hunting: raise a noise, get the bounded set of enemies that go and look.
+- `SoundHuntConfig` (interface): interface SoundHuntConfig — Everything the hunt reads and its bounds.
+- `SoundHuntEntry` (interface): interface SoundHuntEntry — One noise and the hunters sent to it. Serializable, so a hunt survives a save.
+- `SoundHuntSnapshot` (interface): interface SoundHuntSnapshot — Serializable book-keeping: which noises are still being worked, and by whom.
+- `SoundHunter` (interface): interface SoundHunter — A unit that could hear a noise: its id and where it stands when the noise lands.
+- `createSoundHunt` (function): function createSoundHunt(config: SoundHuntConfig): SoundHunt — Make enemies investigate a noise, reusing the hearing owner.
+
 ## @jgengine/core/ai/driver
 
 - `DrivePathPoint` (type): type DrivePathPoint = readonly [number, number] — A 2D polyline point (`[x, z]`), structurally compatible with authored road path centerlines.

package/skills/jgengine-world/capabilities.md

@@ -192,6 +192,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createBodyBind` (function) · `import { createBodyBind } from "@jgengine/core/world"`
 
+## boss-phase-state — fresh serializable boss phase state that opens in the first phase
+
+- `createBossState` (function) · `import { createBossState } from "@jgengine/core/ai/director/boss"`
+
+## boss-phases — data-authored boss phases that change behaviour and fire a tell at health thresholds
+
+- `advanceBoss` (function) · `import { advanceBoss } from "@jgengine/core/ai/director/boss"`
+
 ## bounded-grid-route — distinguish no path from exhausted grid search work
 
 - `findPathResult` (function) · `import { findPathResult } from "@jgengine/core/nav/navGrid"`
@@ -334,6 +342,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `summarizeElevation` (function) · `import { summarizeElevation } from "@jgengine/core/world"`
 
+## encounter-expand — turn an authored wave into a deterministic, pressure-adjusted list of timed spawn orders
+
+- `expandWave` (function) · `import { expandWave } from "@jgengine/core/ai/director/encounter"`
+
+## encounter-pressure — bounded difficulty tier read from player health, encounter progress and time
+
+- `evaluatePressure` (function) · `import { evaluatePressure } from "@jgengine/core/ai/director/pressure"`
+
+## encounter-runner — open authored waves, emit their timed orders, and track wave progress through a save
+
+- `createEncounter` (function) · `import { createEncounter } from "@jgengine/core/ai/director/encounter"`
+
 ## engine-layers — layered engine audio: rpm-keyed samples crossfaded, with on-load and off-load sets picked by engine load
 
 - `createEngineLayers` (function) · `import { createEngineLayers } from "@jgengine/core/audio/engineLayers"`
@@ -354,6 +374,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createFeedbackMixer` (function) · `import { createFeedbackMixer } from "@jgengine/core/vfx/feedbackMixer"`
 
+## fight-intent-composition — map assigned duties onto a squad combat composition in member order
+
+- `compositionForIntents` (function) · `import { compositionForIntents } from "@jgengine/core/ai/director/roles"`
+
+## fight-intents — assign hold, flank, cover, assault and retreat duties from live squad state
+
+- `assignFightIntents` (function) · `import { assignFightIntents } from "@jgengine/core/ai/director/roles"`
+
 ## find-effect — look up one named particle effect in the shared library, or undefined when unknown
 
 - `findEffect` (function) · `import { findEffect } from "@jgengine/core/vfx/effectLibrary"`
@@ -812,6 +840,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `planSolidRoute` (function) · `import { planSolidRoute } from "@jgengine/core/nav/solidRoute"`
 
+## sound-hunting — send a bounded set of nearby enemies to investigate a noise with decaying memory
+
+- `createSoundHunt` (function) · `import { createSoundHunt } from "@jgengine/core/ai/director/sound"`
+
 ## spatial-incremental — Update one entity's spatial cell after a committed write without scanning the population
 
 - `createSpatialApi` (function) · `import { createSpatialApi } from "@jgengine/core/scene/spatial"`