@jgengine/core 0.28.0 → 0.30.0

package/dist/agents/relationships.js

@@ -0,0 +1,132 @@
+import { clamp } from "../math/scalar.js";
+import { createPairKeyCodec } from "../relation/keyedValues.js";
+import { crossThresholds } from "../relation/thresholds.js";
+/** The pair levels every game starts from; a game overrides the words and the cut points. */
+export const DEFAULT_RELATIONSHIP_MILESTONES = [
+    { id: "friends", label: "Friends", at: 35 },
+    { id: "close", label: "Close", at: 70 },
+    { id: "bonded", label: "Bonded", at: 95, requiresFamiliarity: 0.5 },
+];
+/** What a plain social action adds: a shared moment nudges both dials, never maxes either. */
+export const DEFAULT_SOCIAL_CONTACT = { familiarity: 0.08, opinion: 4 };
+const DEFAULTS = {
+    opinionMin: -100,
+    opinionMax: 100,
+    familiarityMax: 1,
+    milestones: DEFAULT_RELATIONSHIP_MILESTONES,
+};
+/**
+ * Create the shared book of pair state. Keys are undirected and delimiter-safe through
+ * `createPairKeyCodec`, and milestone crossings come from `crossThresholds`, so a notice feed and a
+ * journal both read the same event.
+ *
+ * @capability relationships familiarity and opinion between agents, with a bond that changes behaviour
+ */
+export function createRelationshipBook(policy = {}) {
+    let current = { ...DEFAULTS, ...policy };
+    const codec = createPairKeyCodec();
+    let pairs = new Map();
+    const pairKey = (a, b) => codec.key(a, b);
+    const read = (a, b) => pairs.get(pairKey(a, b)) ?? { familiarity: 0, opinion: 0 };
+    const boundaries = () => current.milestones.map((milestone) => ({ id: milestone, at: milestone.at }));
+    const gate = (milestone, pair) => pair.familiarity >= (milestone.requiresFamiliarity ?? 0);
+    const reached = (pair) => {
+        let best = null;
+        for (const milestone of current.milestones) {
+            if (pair.opinion < milestone.at || !gate(milestone, pair))
+                continue;
+            if (best === null || milestone.at > best.at)
+                best = milestone;
+        }
+        return best;
+    };
+    return {
+        get: read,
+        familiarity: (a, b) => read(a, b).familiarity,
+        opinion: (a, b) => read(a, b).opinion,
+        socialise(a, b, contact = DEFAULT_SOCIAL_CONTACT) {
+            const before = read(a, b);
+            if (a === b)
+                return { a, b, before, after: before, crossed: [] };
+            const familiarityDelta = contact.familiarity ?? 0;
+            const opinionDelta = contact.opinion ?? 0;
+            const after = {
+                familiarity: clamp(before.familiarity + familiarityDelta, 0, current.familiarityMax),
+                opinion: clamp(before.opinion + opinionDelta, current.opinionMin, current.opinionMax),
+            };
+            pairs.set(pairKey(a, b), after);
+            const crossed = crossThresholds(boundaries(), before.opinion, after.opinion)
+                .filter((crossing) => crossing.direction === "up")
+                .map((crossing) => crossing.id)
+                .filter((milestone) => gate(milestone, after));
+            return { a, b, before, after, crossed };
+        },
+        milestone: (a, b) => reached(read(a, b)),
+        label: (a, b) => (a === b ? null : reached(read(a, b))?.id ?? null),
+        friends(a, b) {
+            if (a === b)
+                return false;
+            return reached(read(a, b)) !== null;
+        },
+        bonded(a, b) {
+            if (a === b)
+                return false;
+            return reached(read(a, b))?.id === "bonded";
+        },
+        bondedWith(a) {
+            let bestId = null;
+            let bestOpinion = -Infinity;
+            for (const [key, pair] of pairs) {
+                const [first, second] = codec.parse(key);
+                const other = first === a ? second : second === a ? first : null;
+                if (other === null || !(pair.opinion > bestOpinion))
+                    continue;
+                if (reached(pair)?.id !== "bonded")
+                    continue;
+                bestOpinion = pair.opinion;
+                bestId = other;
+            }
+            return bestId;
+        },
+        prefersCompanyOf(a, b) {
+            return a !== b && reached(read(a, b)) !== null;
+        },
+        refusesToSplit(a, b) {
+            return a !== b && reached(read(a, b))?.id === "bonded";
+        },
+        partnersOf(a) {
+            const ids = [];
+            for (const key of pairs.keys()) {
+                const [first, second] = codec.parse(key);
+                if (first === a)
+                    ids.push(second);
+                else if (second === a)
+                    ids.push(first);
+            }
+            return ids.sort();
+        },
+        policy: () => ({ ...current, milestones: current.milestones }),
+        retune(patch) {
+            current = { ...current, ...patch };
+        },
+        snapshot: () => {
+            const out = {};
+            for (const [key, pair] of pairs)
+                out[key] = { ...pair };
+            return { pairs: out, policy: { ...current, milestones: current.milestones } };
+        },
+        restore(next) {
+            current = { ...DEFAULTS, ...next.policy };
+            const restored = new Map();
+            for (const [key, pair] of Object.entries(next.pairs)) {
+                if (!Number.isFinite(pair.familiarity) || !Number.isFinite(pair.opinion))
+                    continue;
+                restored.set(key, {
+                    familiarity: clamp(pair.familiarity, 0, current.familiarityMax),
+                    opinion: clamp(pair.opinion, current.opinionMin, current.opinionMax),
+                });
+            }
+            pairs = restored;
+        },
+    };
+}

package/dist/agents/schedule.d.ts

@@ -0,0 +1,58 @@
+import { type RoutineStopSpec } from "../sim/routine.js";
+/**
+ * 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.
+ */
+export interface AgentScheduleStop extends RoutineStopSpec {
+    /** Places walked in order while this stop holds. Omit to stay put at `place`. */
+    readonly beat?: readonly string[];
+    /** Seconds at each beat place. Default: the stop's own length split evenly across the beat. */
+    readonly beatDwellSeconds?: number;
+}
+/** An agent's whole day as data: what it does, where, and when. */
+export interface AgentScheduleConfig {
+    readonly stops: readonly AgentScheduleStop[];
+    /** Cycle length in game-seconds; default one game day. */
+    readonly cycleSeconds?: number;
+    /** Injected travel time between two places when a stop does not author `travelSeconds`. */
+    readonly travelSeconds?: (from: string, to: string) => number;
+}
+/** Where a schedule puts an agent at one instant. */
+export interface AgentSchedulePhase {
+    /** Opaque place the agent occupies, or the place it is walking from. */
+    readonly place: string;
+    /** Place it is walking to; `null` while holding. */
+    readonly nextPlace: string | null;
+    /** The stop's activity label ("work", "meal", "sleep"); `null` while travelling. */
+    readonly activity: string | null;
+    /** Where the beat posts the agent right now: a patrol place on a beating stop, `place` otherwise, `null` while travelling. */
+    readonly post: string | null;
+    readonly travelling: boolean;
+    /** 0 at departure to 1 on arrival. */
+    readonly progress: number;
+    /** Absolute game-second this phase began. */
+    readonly since: number;
+    /** Absolute game-second the next phase begins. */
+    readonly until: number;
+    /** Index of the stop held here, or the stop being walked away from. */
+    readonly stop: number;
+    /** Needs this stop refills on arrival, or `null`. */
+    readonly refill: Readonly<Record<string, number>> | null;
+}
+/** A day plan resolved against the world clock. No state to tick: a far agent reads the same day. */
+export interface AgentSchedule {
+    readonly cycleSeconds: number;
+    readonly stops: readonly AgentScheduleStop[];
+    phaseAt(time: number): AgentSchedulePhase;
+    /** Absolute game-second of the next arrival, departure or beat step strictly after `time`. */
+    nextChangeAfter(time: number): number;
+}
+/**
+ * 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.
+ *
+ * @capability agent-schedule an authored per-agent day plan with a work beat and off-hours behaviour
+ */
+export declare function createAgentSchedule(config: AgentScheduleConfig): AgentSchedule;

package/dist/agents/schedule.js

@@ -0,0 +1,72 @@
+import { resolveRoutine } from "../sim/routine.js";
+/**
+ * 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.
+ *
+ * @capability agent-schedule an authored per-agent day plan with a work beat and off-hours behaviour
+ */
+export function createAgentSchedule(config) {
+    const timeline = resolveRoutine({
+        stops: config.stops,
+        ...(config.cycleSeconds === undefined ? {} : { cycleSeconds: config.cycleSeconds }),
+        ...(config.travelSeconds === undefined ? {} : { travelSeconds: config.travelSeconds }),
+    });
+    const beats = config.stops.map((stop, index) => {
+        const resolved = timeline.stops[index];
+        const places = stop.beat !== undefined && stop.beat.length > 0 ? [...stop.beat] : null;
+        if (places === null)
+            return null;
+        const span = Math.max(0, resolved.departAt - resolved.arriveAt);
+        const dwell = stop.beatDwellSeconds ?? span / places.length;
+        return { places, dwellSeconds: Math.max(dwell, 0) };
+    });
+    const postAt = (time, phase) => {
+        if (phase.travelling)
+            return null;
+        const beat = beats[phase.stop] ?? null;
+        if (beat === null)
+            return phase.place;
+        if (!(beat.dwellSeconds > 0))
+            return beat.places[0] ?? phase.place;
+        const elapsed = Math.max(0, time - phase.since);
+        const step = Math.floor(elapsed / beat.dwellSeconds) % beat.places.length;
+        return beat.places[step] ?? phase.place;
+    };
+    const beatOf = (phase) => {
+        if (phase.travelling)
+            return null;
+        const beat = beats[phase.stop] ?? null;
+        return beat !== null && beat.dwellSeconds > 0 ? beat : null;
+    };
+    return {
+        cycleSeconds: timeline.cycleSeconds,
+        stops: config.stops,
+        phaseAt(time) {
+            const phase = timeline.phaseAt(time);
+            const stop = config.stops[phase.stop];
+            return {
+                place: phase.place,
+                nextPlace: phase.nextPlace,
+                activity: phase.activity,
+                post: postAt(time, phase),
+                travelling: phase.travelling,
+                progress: phase.progress,
+                since: phase.since,
+                until: phase.until,
+                stop: phase.stop,
+                refill: stop.refill ?? null,
+            };
+        },
+        nextChangeAfter(time) {
+            const phaseEnd = timeline.nextChangeAfter(time);
+            const beat = beatOf(timeline.phaseAt(time));
+            if (beat === null)
+                return phaseEnd;
+            const phase = timeline.phaseAt(time);
+            const elapsed = Math.max(0, time - phase.since);
+            const beatEnd = phase.since + (Math.floor(elapsed / beat.dwellSeconds) + 1) * beat.dwellSeconds;
+            return beatEnd > time ? Math.min(phaseEnd, beatEnd) : phaseEnd;
+        },
+    };
+}

package/dist/ai/director/boss.d.ts

@@ -0,0 +1,63 @@
+import type { SquadRole } from "../../combat/squadTactics.js";
+/** The role shape a boss fights with in one phase: the same dials a squad role uses. */
+export type BossBehaviour = Omit<SquadRole, "id" | "count">;
+/** The warning a boss gives while it changes phase, and how long the player has to read it. */
+export interface BossTell {
+    /** Game-owned id: an animation, a sound, a HUD banner. */
+    id: string;
+    /** Seconds the tell stays visible after the phase changes. Default `1.5`. */
+    telegraphSeconds?: number;
+}
+/** One authored phase: the health it starts at, how the boss fights, and its tell. */
+export interface BossPhase {
+    id: string;
+    /** Health fraction at or below which this phase is in effect, `0..1`. The opening phase is `1`. */
+    atHealth: number;
+    /** How the boss fights while this phase holds. */
+    behaviour: BossBehaviour;
+    /** Warning shown when the boss enters this phase. Omit for a silent phase. */
+    tell?: BossTell;
+}
+/** Serializable boss state: which phase holds, how long it has held, and the tell still on screen. */
+export interface BossState {
+    /** Index into the authored phase list. Monotone: it never goes back down. */
+    phase: number;
+    /** Id of the current phase, for a HUD read without the definition at hand. */
+    phaseId: string;
+    /** Seconds the current phase has held. */
+    ageSeconds: number;
+    /** Tell still showing, or null. */
+    tellId: string | null;
+    /** Seconds left on the showing tell. */
+    tellRemaining: number;
+}
+/** One step of the boss clock. */
+export interface BossStep {
+    state: BossState;
+    /** The phase in effect after the step. */
+    phase: BossPhase;
+    /** True on the step the phase changed. */
+    changed: boolean;
+    /** The tell to fire now, or null. Only set on a change, so a caller never replays a tell. */
+    tell: BossTell | null;
+}
+/** The phase a boss fights with at a health fraction. Pure read for a HUD; never mutates. */
+export declare function bossPhase(phases: readonly BossPhase[], health: number): BossPhase;
+/**
+ * Fresh boss state for a phase list, opening in phase 0 with no tell showing.
+ *
+ * @capability boss-phase-state fresh serializable boss phase state that opens in the first phase
+ */
+export declare function createBossState(phases: readonly BossPhase[]): BossState;
+/**
+ * Advance the boss by `dt` at a health fraction and return the phase in effect.
+ *
+ * A phase changes when health reaches its threshold, and it changes *behaviour with it*: the phase
+ * carries the same role dials squad combat executes, so a phase change is a different fight (range,
+ * cover, discipline) and a tell the game shows while the player has time to react. Phase order is
+ * monotone hand-written data, so a heal does not rewind the boss into an earlier phase and a caller
+ * cannot stack tells by re-entering the same threshold. Deterministic in `dt` and health.
+ *
+ * @capability boss-phases data-authored boss phases that change behaviour and fire a tell at health thresholds
+ */
+export declare function advanceBoss(phases: readonly BossPhase[], state: BossState, health: number, dt: number): BossStep;

package/dist/ai/director/boss.js

@@ -0,0 +1,87 @@
+const DEFAULT_TELL_SECONDS = 1.5;
+function validate(phases) {
+    if (phases.length === 0)
+        throw new Error("boss needs at least one phase");
+    for (let index = 0; index < phases.length; index += 1) {
+        const phase = phases[index];
+        if (phase.id.length === 0)
+            throw new Error(`boss phase ${index} has an empty id`);
+        if (!Number.isFinite(phase.atHealth) || phase.atHealth < 0 || phase.atHealth > 1) {
+            throw new Error(`boss phase "${phase.id}" atHealth must be between 0 and 1`);
+        }
+        const previous = phases[index - 1];
+        if (previous !== undefined && phase.atHealth > previous.atHealth) {
+            throw new Error(`boss phase "${phase.id}" atHealth must not exceed "${previous.id}" — phases run high to low`);
+        }
+    }
+    if (phases[0].atHealth < 1) {
+        throw new Error(`boss opening phase "${phases[0].id}" must start at atHealth 1`);
+    }
+}
+/** The phase a boss fights with at a health fraction. Pure read for a HUD; never mutates. */
+export function bossPhase(phases, health) {
+    validate(phases);
+    const clamped = Math.max(0, Math.min(1, Number.isFinite(health) ? health : 1));
+    let current = phases[0];
+    for (const phase of phases)
+        if (clamped <= phase.atHealth)
+            current = phase;
+    return current;
+}
+/**
+ * Fresh boss state for a phase list, opening in phase 0 with no tell showing.
+ *
+ * @capability boss-phase-state fresh serializable boss phase state that opens in the first phase
+ */
+export function createBossState(phases) {
+    validate(phases);
+    return { phase: 0, phaseId: phases[0].id, ageSeconds: 0, tellId: null, tellRemaining: 0 };
+}
+/**
+ * Advance the boss by `dt` at a health fraction and return the phase in effect.
+ *
+ * A phase changes when health reaches its threshold, and it changes *behaviour with it*: the phase
+ * carries the same role dials squad combat executes, so a phase change is a different fight (range,
+ * cover, discipline) and a tell the game shows while the player has time to react. Phase order is
+ * monotone hand-written data, so a heal does not rewind the boss into an earlier phase and a caller
+ * cannot stack tells by re-entering the same threshold. Deterministic in `dt` and health.
+ *
+ * @capability boss-phases data-authored boss phases that change behaviour and fire a tell at health thresholds
+ */
+export function advanceBoss(phases, state, health, dt) {
+    validate(phases);
+    const clamped = Math.max(0, Math.min(1, Number.isFinite(health) ? health : 1));
+    const step = Number.isFinite(dt) && dt > 0 ? dt : 0;
+    let phaseIndex = state.phase;
+    let changed = false;
+    for (let index = phaseIndex + 1; index < phases.length; index += 1) {
+        if (clamped <= phases[index].atHealth) {
+            phaseIndex = index;
+            changed = true;
+        }
+    }
+    const phase = phases[phaseIndex] ?? phases[0];
+    let tellId = state.tellId;
+    let tellRemaining = Math.max(0, state.tellRemaining - step);
+    let tell = null;
+    if (changed) {
+        tell = phase.tell ?? null;
+        tellId = tell?.id ?? null;
+        tellRemaining = tell === null ? 0 : Math.max(0, tell.telegraphSeconds ?? DEFAULT_TELL_SECONDS);
+    }
+    else if (tellRemaining <= 0) {
+        tellId = null;
+    }
+    return {
+        state: {
+            phase: phaseIndex,
+            phaseId: phase.id,
+            ageSeconds: changed ? 0 : state.ageSeconds + step,
+            tellId,
+            tellRemaining,
+        },
+        phase,
+        changed,
+        tell,
+    };
+}

package/dist/ai/director/encounter.d.ts

@@ -0,0 +1,146 @@
+import type { FightIntent } from "./roles.js";
+/**
+ * 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.
+ */
+export interface EncounterGroup {
+    /** Unit id the game's catalog knows. */
+    unit: string;
+    /** Authored spawn-point key, resolved by the game against its scene. */
+    entry: string;
+    /** How many enter at this open. Default `1`. */
+    count?: number;
+    /** Seconds into the wave before this group enters. Default `0`. */
+    at?: number;
+    /** Duty the group takes when it engages. Default the encounter's `defaultIntent`. */
+    intent?: FightIntent;
+    /** True when pressure may add copies of this group. Default `false`. */
+    escalates?: boolean;
+    /** True when this group only exists once pressure unlocks an elite slot. Default `false`. */
+    elite?: boolean;
+    /** Seeded scatter of up to ±this many seconds on `at`. Default `0`. */
+    jitterSeconds?: number;
+}
+/** One authored wave. */
+export interface EncounterWave {
+    id: string;
+    /** HUD or screen label. */
+    label?: string;
+    groups: readonly EncounterGroup[];
+    /** Seconds the wave stays open after it opens. Omit to close when the last order lands. */
+    durationSeconds?: number;
+}
+/** A whole encounter, authored as data instead of spawned in game code. */
+export interface EncounterDefinition {
+    id: string;
+    waves: readonly EncounterWave[];
+}
+/** The subset of a pressure plan the encounter layer applies. */
+export interface EncounterPressure {
+    /** Extra copies for `escalates` groups. */
+    countBonus?: number;
+    /** Elite slots to unlock. A group marked `elite` enters only when a slot is free. */
+    eliteSlots?: number;
+    /** Multiplier on authored entry delays (`< 1` sends them sooner). */
+    cadenceScale?: number;
+}
+/** One unit the director says should enter now. */
+export interface EncounterOrder {
+    /** 0-based wave index. */
+    wave: number;
+    waveId: string;
+    unit: string;
+    entry: string;
+    intent: FightIntent;
+    /** Seconds after the wave opened when this unit enters. */
+    atSeconds: number;
+    /** Which authored group this order came from, for logging and tests. */
+    group: number;
+    /** True when pressure added this unit rather than the authored composition. */
+    pressureAdded: boolean;
+}
+/** Serializable encounter state. */
+export interface EncounterState {
+    /** 0-based index of the open wave, or of the next one before it opens. */
+    wave: number;
+    opened: boolean;
+    /** Seconds the open wave has run. */
+    elapsed: number;
+    /** Orders already emitted for the open wave. */
+    emitted: number;
+    completedWaves: number;
+    done: boolean;
+    /** Pressure captured when the open wave opened, so re-deriving the schedule is stable. */
+    countBonus: number;
+    eliteSlots: number;
+    cadenceScale: number;
+}
+/** Pooled per-frame readout of where the encounter stands. */
+export interface EncounterView {
+    /** 1-based wave for display. */
+    wave: number;
+    totalWaves: number;
+    waveId: string | null;
+    label: string | null;
+    /** Orders in the open wave, authored plus pressure-added. */
+    total: number;
+    emitted: number;
+    /** `0..1` through the open wave. */
+    progress: number;
+    /** True once the open wave has landed every order and its duration has run. */
+    ready: boolean;
+    done: boolean;
+}
+/** Live encounter: opens waves, emits timed spawn orders, and round-trips through a save. */
+export interface Encounter {
+    /** Open a wave (next one by default) and return its full ordered schedule. */
+    openWave(index?: number, pressure?: EncounterPressure): EncounterOrder[];
+    /** Advance the open wave and return the orders whose time has come since the last step. */
+    update(dt: number): EncounterOrder[];
+    /** Mark the open wave cleared and make the next one current. */
+    completeWave(): void;
+    /** The wave definition at an index, or null past the end. */
+    waveAt(index: number): EncounterWave | null;
+    /** The pooled readout to render. */
+    view(): EncounterView;
+    snapshot(): EncounterState;
+    restore(state: EncounterState): void;
+}
+/** Construction options for {@link createEncounter}. */
+export interface EncounterConfig {
+    definition: EncounterDefinition;
+    /** Seed for the per-wave entry scatter. Default `1`. */
+    seed?: number;
+    /** Duty for groups that omit `intent`. Default `"assault"`. */
+    defaultIntent?: FightIntent;
+    /** Most pressure may add to one escalating group, whatever the plan says. Default `4`. */
+    maxExtraPerGroup?: number;
+}
+/**
+ * Expand one authored wave into the units it sends, at the times it sends them.
+ *
+ * Authoring stays data: composition (`unit`, `count`), entry (`entry`), timing (`at`, `jitterSeconds`,
+ * `durationSeconds`) and escalation (`escalates`, `elite`) all live in the
+ * definition. Pressure only *adds*: extra copies for `escalates` groups (capped at
+ * `maxExtraPerGroup`) and elite slots, and it shortens delays through `cadenceScale` — it never
+ * rewrites an authored unit or entry. Same definition, seed and pressure always produce the same
+ * schedule.
+ *
+ * @capability encounter-expand turn an authored wave into a deterministic, pressure-adjusted list of timed spawn orders
+ */
+export declare function expandWave(config: EncounterConfig, waveIndex: number, pressure?: EncounterPressure): EncounterOrder[];
+/**
+ * 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.
+ *
+ * This is the composition layer, not a second spawn system: every order names a game-owned `unit`
+ * and `entry`, exactly like a `SpawnRequest` names an `entryId`, and the game builds the entity.
+ * Pair it with `combat/encounterSequence` when a fight needs scripted phase gates, and with
+ * `ai/waveRunner` when a wave should be drawn from a budget instead of authored.
+ *
+ * Pressure is captured when a wave opens, so a wave's composition cannot change mid-arrival; read
+ * `evaluatePressure` when the wave opens and pass the plan in.
+ *
+ * @capability encounter-runner open authored waves, emit their timed orders, and track wave progress through a save
+ */
+export declare function createEncounter(config: EncounterConfig): Encounter;