@jgengine/core 0.24.0 → 0.26.0

package/dist/combat/squadCombat.d.ts

@@ -0,0 +1,167 @@
+import { type NavCrowdSnapshot } from "../nav/navCrowd.js";
+import type { NavRuntime } from "../nav/navRuntime.js";
+import type { PerceptionService } from "../sensor/perception.js";
+import type { Vec3 } from "../world/geometry.js";
+import { type CoverSource } from "./cover.js";
+import { type SquadComposition, type SquadRole } from "./squadTactics.js";
+/** One combatant the runtime drives: whose side it is on, where it stands, and how hurt it is. */
+export interface SquadMemberSpec {
+    id: string;
+    /** Side the member fights for; only other sides are threats. */
+    team: string;
+    /** Squad it shares roles and cover with. Defaults to its team. */
+    squad?: string;
+    position: Vec3;
+    /** Health fraction at spawn, which is what the runtime reports until `healthOf` is given. */
+    health?: number;
+}
+/** What a member is doing this tick: moving to cover, holding it, leaning out, falling back, or down. */
+export type SquadMode = "advance" | "cover" | "peek" | "retreat" | "down";
+/** In-play dials, every one retunable. */
+export interface SquadCombatTunables {
+    /** Seconds between cover re-selections for one member. Default `0.6`. */
+    reselectSeconds?: number;
+    /** Most cover points one selection pass scores. Default `24`. */
+    maxCoverCandidates?: number;
+    /** Radius a member searches for cover, world units. Default `12`. */
+    coverRadius?: number;
+    /** Most remembered threats one member considers per tick. Default `6`. */
+    maxThreats?: number;
+    /** Seconds a hit keeps a member pinned and unable to shoot. Default `2.5`. */
+    suppressSeconds?: number;
+    /** Suppression at or above this pins a member. Default `0.5`. */
+    pinAt?: number;
+    /** Exposure seconds the run counts as a breach. Default `3`. */
+    exposureLimitSeconds?: number;
+    /** Crowd walking speed, world units per second. Default `3.2`. */
+    speed?: number;
+    /** Crowd avoidance radius, world units. Default `0.4`. */
+    radius?: number;
+    /** How far a goal must move before the crowd is asked to re-plan. Default `0.15`. */
+    goalEpsilon?: number;
+    /** How much better a rival cover point must score before a held one is abandoned. Default `0.8`. */
+    coverSwitchMargin?: number;
+    /** Seconds of continuous exposure before a member stops trusting its point and repositions. Default `1.5`. */
+    relocateAfterSeconds?: number;
+}
+/** Everything the squad AI reads from the game, plus its tunables. */
+export interface SquadCombatOptions extends SquadCombatTunables {
+    nav: NavRuntime;
+    perception: PerceptionService;
+    /** Bounded cover query — authored geometry (`createCoverField`) or the game's own. */
+    cover: CoverSource;
+    /** Roles per squad id, or a function that answers for one squad. */
+    composition: SquadComposition | ((squad: string) => SquadComposition | undefined);
+    /** Role for a squad the composition does not name. Default `{ id: "member" }`. */
+    defaultRole?: SquadRole;
+    members: readonly SquadMemberSpec[];
+    /** Which side an id fights for, so a remembered target can be classed as hostile. */
+    teamOf: (id: string) => string | null;
+    /** Authoritative health fraction for a member. Default the spawn value. */
+    healthOf?: (id: string) => number;
+    /** True when nothing blocks the segment — the game's collision layer. */
+    blocked: (from: Vec3, to: Vec3) => boolean;
+    /**
+     * Fire one paced shot and resolve it in the game's own damage pipeline. Returns damage dealt, which
+     * the runtime only counts; call {@link SquadCombat.underFire} on the victim yourself.
+     */
+    engage?: (memberId: string, targetId: string, distance: number) => number;
+    /** Seeded `[0,1)` stream, used to de-sync each member's peek phase. */
+    rng?: () => number;
+    /** Register a devtools probe under this name so the overlay shows the squad's behavior. */
+    devtoolsName?: string;
+}
+/** One member as a HUD, a probe or a test reads it. Allocates. */
+export interface SquadMemberView {
+    id: string;
+    team: string;
+    squad: string;
+    role: string;
+    mode: SquadMode;
+    target: string | null;
+    /** Cover point the member is heading for or holding. */
+    cover: string | null;
+    position: Vec3;
+    health: number;
+    /** `0..1` incoming-fire meter; high values pin the member to cover and stop its fire. */
+    suppression: number;
+    /** Consecutive seconds visible to a remembered threat. */
+    exposure: number;
+    shots: number;
+}
+/** Counters a probe or a test reads. */
+export interface SquadCombatStats {
+    members: number;
+    ticks: number;
+    coverQueries: number;
+    coverScored: number;
+    losChecks: number;
+    shots: number;
+    /** Worst consecutive exposure against a remembered threat, seconds. */
+    worstExposure: number;
+    /** Exposure spells longer than `exposureLimitSeconds`. */
+    exposuresOverLimit: number;
+    slowestTickMs: number;
+}
+/** Serializable squad state: member decisions, the crowd, and the tuning they ran under. */
+export interface SquadCombatSnapshot {
+    nowMs: number;
+    tunables: Required<SquadCombatTunables>;
+    members: {
+        id: string;
+        team: string;
+        squad: string;
+        role: string;
+        mode: SquadMode;
+        health: number;
+        target: string | null;
+        targetPosition: Vec3 | null;
+        coverId: string | null;
+        coverPosition: Vec3 | null;
+        coverHidden: number;
+        goal: Vec3 | null;
+        reselect: number;
+        peek: number;
+        peeking: boolean;
+        fire: number;
+        suppression: number;
+        exposure: number;
+        shots: number;
+    }[];
+    crowd: NavCrowdSnapshot;
+    ticks: number;
+    coverQueries: number;
+    coverScored: number;
+    losChecks: number;
+    shots: number;
+    worstExposure: number;
+    exposuresOverLimit: number;
+}
+/** Drive a squad: cover by threat, flanking, fire discipline, suppression and retreat. */
+export interface SquadCombat {
+    /** Advance every member one tick; movement goes through the shared nav crowd. */
+    tick(dt: number): void;
+    /** Report incoming fire on a member: raises its suppression and pins it to cover. */
+    underFire(memberId: string, amount?: number): void;
+    member(id: string): SquadMemberView | null;
+    members(): readonly SquadMemberView[];
+    stats(): SquadCombatStats;
+    retune(patch: SquadCombatTunables): void;
+    snapshot(): SquadCombatSnapshot;
+    restore(next: SquadCombatSnapshot): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * One squad's combat behavior per tick, over the perception memory a game already keeps and the nav
+ * crowd it already moves. Each member picks a stand point that hides it from the threats it remembers,
+ * at the distance and angle its role wants; a flanker goes around the side, a support holds and fires,
+ * an assault closes. Incoming fire raises suppression, which pins the member to its cover and stops
+ * its shooting until the meter decays; low health turns it toward the point furthest from the threat.
+ *
+ * Cover refresh runs on a per-member timer, so the per-tick cost is the crowd step plus one bounded
+ * memory read and a handful of segment tests per member — not a world scan.
+ *
+ * @capability squad-combat threat-driven cover, flanking, suppression, retreat and role-driven fire discipline
+ */
+export declare function createSquadCombat(options: SquadCombatOptions): SquadCombat;