@jgengine/core 0.25.0 → 0.27.0

package/dist/combat/squadCombat.js

@@ -0,0 +1,557 @@
+import { devtools } from "../devtools/devtools.js";
+import { createNavCrowd } from "../nav/navCrowd.js";
+import { resolveRng } from "../random/resolveRng.js";
+import { selectCover, scoreCoverPoint } from "./cover.js";
+import { assignSquadRoles, threatsFromMemory, } from "./squadTactics.js";
+const ROLE_DEFAULTS = {
+    preferredRange: 6,
+    flankAngle: 0,
+    retreatBelow: 0,
+    holdCover: false,
+    discipline: { holdSeconds: 1.6, peekSeconds: 1, peekDistance: 1.3, fireInterval: 0.7 },
+};
+const TUNABLE_DEFAULTS = {
+    reselectSeconds: 0.6,
+    maxCoverCandidates: 24,
+    coverRadius: 12,
+    maxThreats: 6,
+    suppressSeconds: 2.5,
+    pinAt: 0.5,
+    exposureLimitSeconds: 3,
+    speed: 3.2,
+    radius: 0.4,
+    goalEpsilon: 0.15,
+    coverSwitchMargin: 0.8,
+    relocateAfterSeconds: 1.5,
+};
+function resolveRole(role) {
+    return {
+        id: role.id,
+        preferredRange: Math.max(0, role.preferredRange ?? ROLE_DEFAULTS.preferredRange),
+        flankAngle: role.flankAngle ?? ROLE_DEFAULTS.flankAngle,
+        retreatBelow: Math.max(0, Math.min(1, role.retreatBelow ?? ROLE_DEFAULTS.retreatBelow)),
+        holdCover: role.holdCover ?? ROLE_DEFAULTS.holdCover,
+        discipline: { ...ROLE_DEFAULTS.discipline, ...(role.discipline ?? {}) },
+        cover: { ...(role.cover ?? {}) },
+    };
+}
+function flatDistance(a, b) {
+    return Math.hypot(a[0] - b[0], a[2] - b[2]);
+}
+function pointToward(from, to, distance) {
+    const dx = to[0] - from[0];
+    const dz = to[2] - from[2];
+    const length = Math.hypot(dx, dz);
+    if (length < 0.0001)
+        return from;
+    return [from[0] + (dx / length) * distance, from[1], from[2] + (dz / length) * distance];
+}
+function samePoint(a, b, epsilon) {
+    if (a === null || b === null)
+        return a === b;
+    return Math.abs(a[0] - b[0]) <= epsilon && Math.abs(a[1] - b[1]) <= epsilon && Math.abs(a[2] - b[2]) <= epsilon;
+}
+function copy(point) {
+    return point === null ? null : [point[0], point[1], point[2]];
+}
+/**
+ * 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 function createSquadCombat(options) {
+    const nav = options.nav;
+    const perception = options.perception;
+    const coverSource = options.cover;
+    const teamOf = options.teamOf;
+    const blocked = options.blocked;
+    const engage = options.engage;
+    const healthOf = options.healthOf;
+    const rng = resolveRng(options.rng, "createSquadCombat");
+    let tunables = { ...TUNABLE_DEFAULTS };
+    const crowd = createNavCrowd({
+        nav,
+        speed: tunables.speed,
+        radius: tunables.radius,
+        // A stand point only hides the body if the body actually reaches it; the default half-metre
+        // arrival tolerance leaves an agent half in the open.
+        goalRadius: 0.15,
+        waypointRadius: 0.2,
+        replanBudget: 6,
+        replanMs: 1.2,
+    });
+    const rolesById = new Map();
+    const defaultRole = resolveRole(options.defaultRole ?? { id: "member" });
+    const members = [];
+    const memberOf = new Map();
+    const squads = new Map();
+    let nowMs = 0;
+    let ticks = 0;
+    let coverQueries = 0;
+    let coverScored = 0;
+    let losChecks = 0;
+    let shots = 0;
+    let worstExposure = 0;
+    let exposuresOverLimit = 0;
+    let slowestTickMs = 0;
+    for (const spec of options.members) {
+        const squad = spec.squad ?? spec.team;
+        const list = squads.get(squad) ?? [];
+        list.push(spec.id);
+        squads.set(squad, list);
+        const member = {
+            id: spec.id,
+            team: spec.team,
+            squad,
+            role: defaultRole,
+            health: spec.health ?? 1,
+            mode: "advance",
+            target: null,
+            targetPosition: null,
+            threatPosition: null,
+            cover: null,
+            goal: null,
+            reselect: 0,
+            peek: 0,
+            peeking: false,
+            fire: 0,
+            suppression: 0,
+            exposure: 0,
+            shots: 0,
+            hostile: (targetId) => teamOf(targetId) !== spec.team,
+        };
+        members.push(member);
+        memberOf.set(member.id, member);
+        crowd.add(member.id, { position: spec.position, goal: spec.position });
+        // De-sync peek phases so a squad does not lean out in lockstep.
+        member.peek = rng() * (member.role.discipline.holdSeconds + member.role.discipline.peekSeconds);
+    }
+    function compositionFor(squad) {
+        return typeof options.composition === "function" ? options.composition(squad) : options.composition;
+    }
+    for (const [squad, ids] of squads) {
+        const squadComposition = compositionFor(squad);
+        if (squadComposition === undefined)
+            continue;
+        for (const [id, role] of assignSquadRoles(ids, squadComposition)) {
+            const resolved = resolveRole(role);
+            rolesById.set(resolved.id, resolved);
+            memberOf.get(id).role = resolved;
+        }
+    }
+    function squadLine(squad) {
+        const ids = squads.get(squad);
+        if (ids === undefined || ids.length === 0)
+            return null;
+        let x = 0;
+        let y = 0;
+        let z = 0;
+        let counted = 0;
+        for (const id of ids) {
+            const body = crowd.agent(id);
+            if (body === null)
+                continue;
+            x += body.position[0];
+            y += body.position[1];
+            z += body.position[2];
+            counted += 1;
+        }
+        return counted === 0 ? null : [x / counted, y / counted, z / counted];
+    }
+    function positionOf(member) {
+        return crowd.agent(member.id)?.position ?? [0, 0, 0];
+    }
+    /**
+     * Where a peek steps to: straight out at the threat when the face already points at it, otherwise
+     * along the wall toward the end of cover, which is where a body actually gets a sight line.
+     */
+    function peekSpot(member) {
+        const point = member.cover.point;
+        const threat = member.threatPosition;
+        const dx = threat[0] - point.position[0];
+        const dz = threat[2] - point.position[2];
+        const [nx, nz] = point.normal;
+        const along = dx * nx + dz * nz;
+        if (along >= 0)
+            return pointToward(point.position, threat, member.role.discipline.peekDistance);
+        const lateralX = dx - nx * along;
+        const lateralZ = dz - nz * along;
+        const length = Math.hypot(lateralX, lateralZ);
+        const step = member.role.discipline.peekDistance;
+        if (length < 1e-6)
+            return [point.position[0] + nx * step, point.position[1], point.position[2] + nz * step];
+        return [point.position[0] + (lateralX / length) * step, point.position[1], point.position[2] + (lateralZ / length) * step];
+    }
+    function lineOfSight(from, to) {
+        losChecks += 1;
+        return !blocked(from, to);
+    }
+    function selectPoint(member, threats, taken, retreating, survival) {
+        const position = positionOf(member);
+        const radius = tunables.coverRadius;
+        coverQueries += 1;
+        const candidates = coverSource.near(position, radius, tunables.maxCoverCandidates);
+        coverScored += candidates.length;
+        if (candidates.length === 0) {
+            member.cover = null;
+            return;
+        }
+        const line = squadLine(member.squad) ?? position;
+        const weights = survival
+            ? { hidden: 6, range: 0, flank: 0, near: 0.2, retreat: 1, path: 1, crowding: 1 }
+            : retreating
+                ? { ...member.role.cover, range: 0, flank: 0, near: 0.3, retreat: 1, hidden: 3 }
+                : member.role.cover;
+        const query = {
+            position,
+            radius,
+            threats,
+            preferredRange: survival || retreating ? radius : member.role.preferredRange,
+            flankAngle: survival || retreating ? 0 : member.role.flankAngle,
+            lineThrough: line,
+            taken,
+            blocked: (from, to) => {
+                losChecks += 1;
+                return blocked(from, to);
+            },
+            hiddenOnly: true,
+            weights,
+        };
+        const choice = selectCover(candidates, query);
+        const held = member.cover === null ? null : scoreCoverPoint(member.cover.point, query);
+        // Retention: keep the held point unless the rival hides from strictly more threats, or ties on
+        // hiding and scores past the margin. Without it a squad churns between equivalent crates and
+        // never stops walking in the open. Under sustained fire there is no retention — move.
+        const better = choice !== null &&
+            (held === null ||
+                choice.hidden > held.hidden + 0.001 ||
+                (choice.hidden >= held.hidden - 0.001 && choice.score >= held.score + tunables.coverSwitchMargin));
+        if (!survival && held !== null && held.hidden > 0 && !better) {
+            member.cover = held;
+            return;
+        }
+        member.cover = choice;
+    }
+    function updateTarget(member, threats, position) {
+        const reach = member.role.preferredRange * 1.8;
+        member.target = null;
+        member.targetPosition = null;
+        member.threatPosition = threats.find((threat) => threat.ageSeconds <= 12)?.position ?? null;
+        for (const threat of threats) {
+            if (threat.ageSeconds > 12)
+                continue;
+            if (flatDistance(position, threat.position) > reach)
+                continue;
+            if (!lineOfSight(position, threat.position))
+                continue;
+            member.target = threat.id;
+            member.targetPosition = threat.position;
+            return;
+        }
+    }
+    /**
+     * The held point is still good only when it hides the member from every remembered threat and the
+     * member is not in the open right now. A point that hides from one of two shooters is not cover —
+     * it is a spot the other one can shoot.
+     */
+    function coverStillGood(member, threats, holders, position) {
+        if (member.cover === null)
+            return false;
+        const holder = holders.get(member.cover.point.id);
+        if (holder !== undefined && holder !== member.id)
+            return false;
+        for (const threat of threats) {
+            if (threat.confidence < 0.05)
+                continue;
+            if (lineOfSight(member.cover.point.position, threat.position))
+                return false;
+            if (lineOfSight(position, threat.position))
+                return false;
+        }
+        return true;
+    }
+    function decide(member, threats, holders, dt) {
+        member.health = healthOf === undefined ? member.health : healthOf(member.id);
+        if (member.health <= 0) {
+            member.mode = "down";
+            member.target = null;
+            member.targetPosition = null;
+            member.cover = null;
+            member.goal = null;
+            return;
+        }
+        const position = positionOf(member);
+        member.suppression = Math.max(0, member.suppression - dt / Math.max(0.001, tunables.suppressSeconds));
+        member.reselect = Math.max(0, member.reselect - dt);
+        member.fire = Math.max(0, member.fire - dt);
+        const pinned = member.suppression >= tunables.pinAt;
+        const retreating = member.role.retreatBelow > 0 && member.health <= member.role.retreatBelow;
+        const survival = member.exposure > tunables.relocateAfterSeconds;
+        updateTarget(member, threats, position);
+        if (member.cover === null || member.reselect <= 0 || survival || !coverStillGood(member, threats, holders, position)) {
+            const taken = new Set();
+            for (const [pointId, holder] of holders)
+                if (holder !== member.id)
+                    taken.add(pointId);
+            // Under sustained fire, stop trusting the point the member is already at.
+            if (survival && member.cover !== null)
+                taken.add(member.cover.point.id);
+            selectPoint(member, threats, taken, retreating, survival);
+            member.reselect = tunables.reselectSeconds;
+        }
+        const atCover = member.cover !== null && flatDistance(position, member.cover.point.position) <= 0.9;
+        const targetVisible = member.target !== null && (member.targetPosition === null || lineOfSight(position, member.targetPosition));
+        if (retreating)
+            member.mode = "retreat";
+        else if (member.cover === null)
+            member.mode = "advance";
+        else if (!atCover)
+            member.mode = "advance";
+        else
+            member.mode = "cover";
+        if (member.mode === "cover" && atCover && member.threatPosition !== null && !pinned && !member.role.holdCover) {
+            member.peek -= dt;
+            if (member.peek <= 0) {
+                member.peeking = !member.peeking;
+                member.peek = member.peeking ? member.role.discipline.peekSeconds : member.role.discipline.holdSeconds;
+            }
+            if (member.peeking)
+                member.mode = "peek";
+        }
+        else {
+            member.peeking = false;
+        }
+        if (pinned) {
+            // Suppression only holds a member that already has cover; in the open it keeps running to it.
+            member.goal = member.cover === null || atCover ? position : member.cover.point.position;
+        }
+        else if (member.cover === null) {
+            const gap = member.targetPosition === null ? 0 : flatDistance(position, member.targetPosition) - member.role.preferredRange;
+            member.goal = member.targetPosition === null || gap <= 0
+                ? position
+                : pointToward(position, member.targetPosition, Math.max(1, gap));
+        }
+        else if (member.mode === "peek" && member.threatPosition !== null) {
+            member.goal = peekSpot(member);
+        }
+        else {
+            member.goal = member.cover.point.position;
+        }
+        if (!retreating && targetVisible && member.target !== null && member.targetPosition !== null && member.fire <= 0) {
+            member.fire = Math.max(0.05, member.role.discipline.fireInterval);
+            member.shots += 1;
+            shots += 1;
+            engage?.(member.id, member.target, flatDistance(position, member.targetPosition));
+        }
+        let visible = false;
+        for (const threat of threats) {
+            if (threat.confidence < 0.05)
+                continue;
+            if (lineOfSight(position, threat.position)) {
+                visible = true;
+                break;
+            }
+        }
+        const wasOver = member.exposure > tunables.exposureLimitSeconds;
+        member.exposure = visible ? member.exposure + dt : 0;
+        if (member.exposure > worstExposure)
+            worstExposure = member.exposure;
+        if (member.exposure > tunables.exposureLimitSeconds && !wasOver)
+            exposuresOverLimit += 1;
+    }
+    function viewOf(member) {
+        return {
+            id: member.id,
+            team: member.team,
+            squad: member.squad,
+            role: member.role.id,
+            mode: member.mode,
+            target: member.target,
+            cover: member.cover?.point.id ?? null,
+            position: positionOf(member),
+            health: member.health,
+            suppression: member.suppression,
+            exposure: member.exposure,
+            shots: member.shots,
+        };
+    }
+    function probeLine() {
+        let pinned = 0;
+        let peeking = 0;
+        for (const member of members) {
+            if (member.suppression >= tunables.pinAt)
+                pinned += 1;
+            if (member.mode === "peek")
+                peeking += 1;
+        }
+        return `${members.length} members ${pinned} pinned ${peeking} peeking · ${shots} shots · ${worstExposure.toFixed(1)}s worst exposure ${exposuresOverLimit} over ${tunables.exposureLimitSeconds}s · ${coverQueries} cover queries`;
+    }
+    const unregister = options.devtoolsName === undefined ? null : devtools.probes.register(options.devtoolsName, () => probeLine());
+    return {
+        tick(dt) {
+            if (!(dt > 0) || members.length === 0)
+                return;
+            const started = performance.now();
+            nowMs += dt * 1000;
+            ticks += 1;
+            const holders = new Map();
+            for (const member of members)
+                if (member.cover !== null)
+                    holders.set(member.cover.point.id, member.id);
+            for (const member of members) {
+                const threats = threatsFromMemory(perception, member.id, nowMs, {
+                    max: tunables.maxThreats,
+                    hostile: member.hostile,
+                });
+                decide(member, threats, holders, dt);
+                for (const [pointId, holder] of holders)
+                    if (holder === member.id)
+                        holders.delete(pointId);
+                if (member.cover !== null)
+                    holders.set(member.cover.point.id, member.id);
+                const body = crowd.agent(member.id);
+                if (body === null)
+                    continue;
+                const goal = member.mode === "down" ? body.position : member.goal ?? body.position;
+                if (!samePoint(body.goal, goal, tunables.goalEpsilon))
+                    crowd.setGoal(member.id, goal);
+            }
+            crowd.tick(dt);
+            slowestTickMs = Math.max(slowestTickMs, performance.now() - started);
+        },
+        underFire(memberId, amount = 1) {
+            const member = memberOf.get(memberId);
+            if (member === undefined || amount <= 0)
+                return;
+            member.suppression = Math.min(1, member.suppression + amount);
+            member.reselect = Math.min(member.reselect, 0.05);
+        },
+        member(id) {
+            const member = memberOf.get(id);
+            return member === undefined ? null : viewOf(member);
+        },
+        members: () => members.map(viewOf),
+        stats: () => ({
+            members: members.length,
+            ticks,
+            coverQueries,
+            coverScored,
+            losChecks,
+            shots,
+            worstExposure,
+            exposuresOverLimit,
+            slowestTickMs,
+        }),
+        retune(patch) {
+            const next = { ...tunables };
+            for (const key of Object.keys(TUNABLE_DEFAULTS)) {
+                const value = patch[key];
+                if (value !== undefined)
+                    next[key] = Math.max(0, value);
+            }
+            tunables = next;
+            crowd.retune({ speed: tunables.speed, radius: tunables.radius });
+        },
+        snapshot() {
+            return {
+                nowMs,
+                tunables: { ...tunables },
+                members: members.map((member) => ({
+                    id: member.id,
+                    team: member.team,
+                    squad: member.squad,
+                    role: member.role.id,
+                    mode: member.mode,
+                    health: member.health,
+                    target: member.target,
+                    targetPosition: copy(member.targetPosition),
+                    coverId: member.cover?.point.id ?? null,
+                    coverPosition: copy(member.cover?.point.position ?? null),
+                    coverHidden: member.cover?.hidden ?? 0,
+                    goal: copy(member.goal),
+                    reselect: member.reselect,
+                    peek: member.peek,
+                    peeking: member.peeking,
+                    fire: member.fire,
+                    suppression: member.suppression,
+                    exposure: member.exposure,
+                    shots: member.shots,
+                })),
+                crowd: crowd.snapshot(),
+                ticks,
+                coverQueries,
+                coverScored,
+                losChecks,
+                shots,
+                worstExposure,
+                exposuresOverLimit,
+            };
+        },
+        restore(next) {
+            nowMs = next.nowMs;
+            ticks = next.ticks;
+            coverQueries = next.coverQueries;
+            coverScored = next.coverScored;
+            losChecks = next.losChecks;
+            shots = next.shots;
+            worstExposure = next.worstExposure;
+            exposuresOverLimit = next.exposuresOverLimit;
+            tunables = { ...next.tunables };
+            crowd.restore(next.crowd);
+            crowd.retune({ speed: tunables.speed, radius: tunables.radius });
+            members.length = 0;
+            memberOf.clear();
+            squads.clear();
+            for (const saved of next.members) {
+                const member = {
+                    id: saved.id,
+                    team: saved.team,
+                    squad: saved.squad,
+                    role: rolesById.get(saved.role) ?? defaultRole,
+                    health: saved.health,
+                    mode: saved.mode,
+                    target: saved.target,
+                    targetPosition: copy(saved.targetPosition),
+                    threatPosition: null,
+                    cover: saved.coverId === null || saved.coverPosition === null
+                        ? null
+                        : {
+                            point: { id: saved.coverId, position: copy(saved.coverPosition), normal: [0, 0] },
+                            score: 0,
+                            hidden: saved.coverHidden,
+                            range: 0,
+                            flank: 0,
+                            near: 0,
+                            retreat: 0,
+                            path: 0,
+                        },
+                    goal: copy(saved.goal),
+                    reselect: saved.reselect,
+                    peek: saved.peek,
+                    peeking: saved.peeking,
+                    fire: saved.fire,
+                    suppression: saved.suppression,
+                    exposure: saved.exposure,
+                    shots: saved.shots,
+                    hostile: (targetId) => teamOf(targetId) !== saved.team,
+                };
+                members.push(member);
+                memberOf.set(member.id, member);
+                const list = squads.get(member.squad) ?? [];
+                list.push(member.id);
+                squads.set(member.squad, list);
+            }
+        },
+        dispose() {
+            unregister?.();
+            crowd.dispose();
+        },
+    };
+}

package/dist/combat/squadTactics.d.ts

@@ -0,0 +1,73 @@
+import type { PerceptionService } from "../sensor/perception.js";
+import type { CoverThreat, CoverWeights } from "./cover.js";
+/**
+ * Fire discipline: how long a member stays down between shots, how long it leans out, and how fast
+ * it fires while it has a target. A role that peeks for longer holds an angle better and spends more
+ * time in the open — the trade is the caller's to tune.
+ */
+export interface FireDiscipline {
+    /** Seconds held in cover between peeks. Default `1.6`. */
+    holdSeconds?: number;
+    /** Seconds exposed while shooting. Default `0.8`. */
+    peekSeconds?: number;
+    /** How far toward the threat a peek steps out of cover. Default `0.9`. */
+    peekDistance?: number;
+    /** Seconds between shots while a target is visible. Default `0.7`. */
+    fireInterval?: number;
+}
+/**
+ * One caller-defined squad role. The engine ships the machinery and no role list: a game names its
+ * own roles and dials them, so `"assault"`, `"breacher"` and `"sniper"` are content, not engine
+ * concepts.
+ */
+export interface SquadRole {
+    /** Id the game names and its HUD, logs and tests read. */
+    id: string;
+    /** Members this role takes when a squad is assigned. Default `1`. */
+    count?: number;
+    /** Distance from the threat this role wants to fight at, world units. Default `6`. */
+    preferredRange?: number;
+    /** Angle around the threat this role attacks from, radians off the squad's line. Default `0`. */
+    flankAngle?: number;
+    /** Health fraction at or below which this role falls back. Default `0` (never). */
+    retreatBelow?: number;
+    /** True when the role holds its point instead of closing to `preferredRange`. Default `false`. */
+    holdCover?: boolean;
+    discipline?: FireDiscipline;
+    /** Cover weights this role scores with; omitted fields take the shared defaults. */
+    cover?: CoverWeights;
+}
+/** A squad's roles in assignment order. */
+export interface SquadComposition {
+    readonly roles: readonly SquadRole[];
+}
+/**
+ * Deterministic role per member: declared order, `count` copies of each role, and the list repeats
+ * when the squad is larger than the composition. Same members and composition give the same answer
+ * on every host and after a reload.
+ *
+ * @capability squad-roles deterministic role assignment over a caller-authored composition
+ */
+export declare function assignSquadRoles(members: readonly string[], composition: SquadComposition): Map<string, SquadRole>;
+/** One remembered enemy with its age, so a role can treat a stale sighting differently. */
+export interface ThreatReading extends CoverThreat {
+    readonly ageSeconds: number;
+    /** Whose senses produced the fact: this member's own id, or the squadmate that shared it. */
+    readonly sourceId: string;
+}
+/** Bounds for {@link threatsFromMemory}. */
+export interface ThreatReadOptions {
+    /** Most threats to return, strongest first. Default `6`. */
+    max?: number;
+    /** Memories weaker than this are ignored. Default `0.05`. */
+    minConfidence?: number;
+    /** Only these ids count as hostile; omit to treat every remembered id as a threat. */
+    hostile?: (targetId: string) => boolean;
+}
+/**
+ * Read one member's threat list out of its perception memory — the only source of threat. Sorted by
+ * confidence, then recency, then id, and bounded by `max`, so a crowded memory cannot grow the tick.
+ *
+ * @capability threats-from-memory turn perception memory into a bounded, ranked threat list
+ */
+export declare function threatsFromMemory(perception: PerceptionService, observerId: string, nowMs: number, options?: ThreatReadOptions): ThreatReading[];

package/dist/combat/squadTactics.js

@@ -0,0 +1,49 @@
+/**
+ * Deterministic role per member: declared order, `count` copies of each role, and the list repeats
+ * when the squad is larger than the composition. Same members and composition give the same answer
+ * on every host and after a reload.
+ *
+ * @capability squad-roles deterministic role assignment over a caller-authored composition
+ */
+export function assignSquadRoles(members, composition) {
+    const slots = [];
+    for (const role of composition.roles) {
+        const count = Math.max(0, Math.floor(role.count ?? 1));
+        for (let i = 0; i < count; i += 1)
+            slots.push(role);
+    }
+    const assigned = new Map();
+    if (slots.length === 0)
+        return assigned;
+    for (let i = 0; i < members.length; i += 1)
+        assigned.set(members[i], slots[i % slots.length]);
+    return assigned;
+}
+/**
+ * Read one member's threat list out of its perception memory — the only source of threat. Sorted by
+ * confidence, then recency, then id, and bounded by `max`, so a crowded memory cannot grow the tick.
+ *
+ * @capability threats-from-memory turn perception memory into a bounded, ranked threat list
+ */
+export function threatsFromMemory(perception, observerId, nowMs, options = {}) {
+    const minConfidence = options.minConfidence ?? 0.05;
+    const max = Math.max(0, Math.floor(options.max ?? 6));
+    const out = [];
+    for (const memory of perception.memory(observerId)) {
+        if (memory.confidence < minConfidence)
+            continue;
+        if (options.hostile !== undefined && !options.hostile(memory.targetId))
+            continue;
+        out.push({
+            id: memory.targetId,
+            position: memory.lastKnownPos,
+            confidence: memory.confidence,
+            ageSeconds: Math.max(0, nowMs - memory.lastSeenAt) / 1000,
+            sourceId: memory.sourceId,
+        });
+    }
+    out.sort((a, b) => b.confidence - a.confidence ||
+        a.ageSeconds - b.ageSeconds ||
+        (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return out.slice(0, max);
+}