@its-not-rocket-science/ananke 0.1.0

package/dist/src/sim/formation-unit.js

@@ -0,0 +1,197 @@
+/**
+ * Phase 6 — Formation System
+ *
+ * Pure computation module for tactical formation mechanics:
+ *  - Shield walls: adjacent shield-bearers pool block coverage
+ *  - Rank depth: entities sorted by forward projection; front/rear split
+ *  - Casualty fill: rear-rank entities promote when front rank is lost
+ *  - Push of pike: total formation momentum from mass × velocity
+ *  - Formation cohesion: morale bonus / rout-contagion penalty
+ *
+ * No Entity or WorldState imports — callers extract the needed values and
+ * pass plain numbers / maps.  All arithmetic is integer fixed-point.
+ */
+import { SCALE, q, clampQ, mulDiv, qMul } from "../../src/units.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+/**
+ * Efficiency of shield coverage sharing between adjacent bearers.
+ * Each additional bearer beyond the first contributes at this fraction.
+ */
+export const SHIELD_SHARING_FRAC = q(0.60);
+/** Hard cap on combined shield wall coverage. */
+export const SHIELD_WALL_MAX_COVERAGE = SCALE.Q;
+/** Default rank depth used to split front/rear ranks (2 m in SCALE.m). */
+export const RANK_DEPTH_DEFAULT_m = Math.round(2.0 * SCALE.m);
+/**
+ * Minimum intact fraction for a formation to be considered cohesive.
+ * Below this threshold the rout-contagion penalty applies instead of the
+ * morale bonus.
+ */
+export const FORMATION_INTACT_THRESHOLD = q(0.60);
+/** Fear decay bonus per tick granted to entities in an intact formation. */
+export const FORMATION_MORALE_BONUS = q(0.008);
+/** Fear increment per tick when formation integrity has collapsed. */
+export const FORMATION_MORALE_PENALTY = q(0.010);
+/** Per-tick fear decay granted per alive formation ally (vs q(0.002) unaffiliated). */
+export const FORMATION_ALLY_FEAR_DECAY = q(0.004);
+/** Maximum number of formation allies counted for the fear decay bonus. */
+export const FORMATION_ALLY_DECAY_CAP = 8;
+// ─── Shield wall ──────────────────────────────────────────────────────────────
+/**
+ * Compute the combined block coverage of a shield wall.
+ *
+ * The bearer with the highest individual coverage contributes at full strength.
+ * Each subsequent bearer (sorted descending by coverage) contributes at
+ * SHIELD_SHARING_FRAC efficiency, modelling timing gaps and partial overlap
+ * between adjacent shields.
+ *
+ * Result is capped at SHIELD_WALL_MAX_COVERAGE = q(1.0).
+ */
+export function computeShieldWallCoverage(coverageFracs) {
+    if (coverageFracs.length === 0)
+        return q(0);
+    // Sort descending so the highest coverage bearer contributes fully.
+    const sorted = [...coverageFracs].sort((a, b) => b - a);
+    let total = sorted[0];
+    for (let i = 1; i < sorted.length; i++) {
+        total += mulDiv(sorted[i], SHIELD_SHARING_FRAC, SCALE.Q);
+    }
+    return clampQ(Math.round(total), 0, SHIELD_WALL_MAX_COVERAGE);
+}
+// ─── Rank depth ───────────────────────────────────────────────────────────────
+/**
+ * Split formation entity IDs into front and rear ranks.
+ *
+ * Each entity position is projected onto the facing direction.  The entity
+ * with the greatest projection defines depth = 0.  Entities within
+ * `rankDepth_m` of the frontmost entity are placed in the front rank; the
+ * rest go to the rear rank.  Both ranks are sorted front-to-back.
+ *
+ * @param entityIds   IDs to split
+ * @param positions   Map: entity ID → {x, y} in SCALE.m
+ * @param facingDirQ  Unit vector with components in Q units (SCALE.Q = 1.0)
+ * @param rankDepth_m Depth of front rank in SCALE.m (default: RANK_DEPTH_DEFAULT_m)
+ */
+export function deriveRankSplit(entityIds, positions, facingDirQ, rankDepth_m = RANK_DEPTH_DEFAULT_m) {
+    if (entityIds.length === 0)
+        return { frontRank: [], rearRank: [] };
+    // Project each entity onto the facing direction (result in SCALE.m).
+    const projections = new Map();
+    for (const id of entityIds) {
+        const pos = positions.get(id);
+        if (!pos) {
+            projections.set(id, 0);
+            continue;
+        }
+        const proj = Math.trunc((pos.x * facingDirQ.x + pos.y * facingDirQ.y) / SCALE.Q);
+        projections.set(id, proj);
+    }
+    // Frontmost entity has the largest projection.
+    let maxProj = -Infinity;
+    for (const proj of projections.values()) {
+        if (proj > maxProj)
+            maxProj = proj;
+    }
+    const frontRank = [];
+    const rearRank = [];
+    for (const id of entityIds) {
+        const proj = projections.get(id) ?? 0;
+        if (proj >= maxProj - rankDepth_m) {
+            frontRank.push(id);
+        }
+        else {
+            rearRank.push(id);
+        }
+    }
+    // Sort front-to-back (highest projection first) for determinism.
+    const byProjDesc = (a, b) => (projections.get(b) ?? 0) - (projections.get(a) ?? 0);
+    frontRank.sort(byProjDesc);
+    rearRank.sort(byProjDesc);
+    return { frontRank, rearRank };
+}
+// ─── Casualty fill ────────────────────────────────────────────────────────────
+/**
+ * Promote rear-rank entities to fill vacancies left by front-rank losses.
+ *
+ * Returns new front and rear rank arrays with dead entities removed and
+ * replacements drawn from the front of the (alive) rear rank.
+ */
+export function stepFormationCasualtyFill(rankSplit, deadIds) {
+    const aliveFront = rankSplit.frontRank.filter(id => !deadIds.has(id));
+    const aliveRear = rankSplit.rearRank.filter(id => !deadIds.has(id));
+    const vacancies = rankSplit.frontRank.length - aliveFront.length;
+    const replacements = aliveRear.splice(0, vacancies);
+    return { frontRank: [...aliveFront, ...replacements], rearRank: aliveRear };
+}
+// ─── Push of pike / formation momentum ───────────────────────────────────────
+/**
+ * Compute the total forward momentum of a formation (push-of-pike model).
+ *
+ * `momentum_Skg_mps` is in (SCALE.kg × m/s) units — i.e. fixed-point mass
+ * multiplied by real-valued speed (speed already divided by SCALE.mps).
+ * Divide by SCALE.kg (= 1000) to obtain physical kg·m/s.
+ *
+ * Only entities with speed > 0 contribute.
+ *
+ * @param masses_Skg   Entity masses in SCALE.kg units
+ * @param speeds_Smps  Entity speeds (magnitude) in SCALE.mps units
+ */
+export function computeFormationMomentum(masses_Skg, speeds_Smps) {
+    const n = Math.min(masses_Skg.length, speeds_Smps.length);
+    let sum = 0;
+    let count = 0;
+    for (let i = 0; i < n; i++) {
+        const speed = speeds_Smps[i];
+        if (speed <= 0)
+            continue;
+        sum += Math.trunc(masses_Skg[i] * speed / SCALE.mps);
+        count++;
+    }
+    return { momentum_Skg_mps: sum, entityCount: count };
+}
+// ─── Formation cohesion / morale ─────────────────────────────────────────────
+/**
+ * Derive the morale state of a formation from casualty / rout status.
+ *
+ * An entity is counted as lost if its ID appears in `deadOrRoutedIds`.
+ * When intactFrac_Q ≥ FORMATION_INTACT_THRESHOLD the formation grants a fear
+ * decay bonus; below it a rout-contagion penalty applies instead.
+ *
+ * An empty formation is considered vacuously intact but grants no bonus.
+ */
+export function deriveFormationCohesion(entityIds, deadOrRoutedIds) {
+    const total = entityIds.length;
+    if (total === 0) {
+        return {
+            intact: true,
+            intactFrac_Q: SCALE.Q,
+            moraleBonus_Q: q(0),
+            moralePenalty_Q: q(0),
+        };
+    }
+    let lostCount = 0;
+    for (const id of entityIds) {
+        if (deadOrRoutedIds.has(id))
+            lostCount++;
+    }
+    const intactCount = total - lostCount;
+    const intactFrac_Q = clampQ(Math.round((intactCount * SCALE.Q) / total), 0, SCALE.Q);
+    const intact = intactFrac_Q >= FORMATION_INTACT_THRESHOLD;
+    return {
+        intact,
+        intactFrac_Q,
+        moraleBonus_Q: intact ? FORMATION_MORALE_BONUS : q(0),
+        moralePenalty_Q: intact ? q(0) : FORMATION_MORALE_PENALTY,
+    };
+}
+/**
+ * Compute the per-tick fear decay bonus from alive formation allies.
+ *
+ * Returns a larger bonus than the unaffiliated ally coefficient (q(0.002)):
+ * formation allies grant q(0.004) each, capped at FORMATION_ALLY_DECAY_CAP
+ * allies.  Result is a Q value to be added to the entity's fear decay term.
+ */
+export function deriveFormationAllyFearDecay(aliveFormationAllyCount) {
+    const capped = Math.min(aliveFormationAllyCount, FORMATION_ALLY_DECAY_CAP);
+    return clampQ((capped * FORMATION_ALLY_FEAR_DECAY), 0, qMul(FORMATION_ALLY_FEAR_DECAY, q(FORMATION_ALLY_DECAY_CAP)));
+}

package/dist/src/sim/formation.d.ts

@@ -0,0 +1,12 @@
+import type { Entity } from "./entity.js";
+import type { WorldIndex } from "./indexing.js";
+import type { SpatialIndex } from "./spatial.js";
+import type { WorldState } from "./world.js";
+export interface EngagementQuery {
+    reach_m: number;
+    buffer_m: number;
+    maxTargets: number;
+    requireFrontArc?: boolean;
+    minDotQ?: number;
+}
+export declare function pickNearestEnemyInReach(world: WorldState | undefined, attacker: Entity, index: WorldIndex, spatial: SpatialIndex, q: EngagementQuery): Entity | undefined;

package/dist/src/sim/formation.js

@@ -0,0 +1,54 @@
+import { queryNearbyIds } from "./spatial.js";
+import { isEnemy, areEntitiesHostile } from "./team.js";
+import { dotDirQ, normaliseDirCheapQ } from "./vec3.js"; // wherever you keep these
+export function pickNearestEnemyInReach(world, attacker, index, spatial, q) {
+    const radius_m = q.reach_m + q.buffer_m;
+    const ids = queryNearbyIds(spatial, attacker.position_m, radius_m);
+    ids.sort((a, b) => a - b);
+    // Collect candidates
+    const cand = [];
+    for (const id of ids) {
+        if (id === attacker.id)
+            continue;
+        const e = index.byId.get(id);
+        if (!e || e.injury.dead)
+            continue;
+        const hostile = world ? areEntitiesHostile(attacker, e, world) : isEnemy(attacker, e);
+        if (!hostile)
+            continue;
+        if (q.requireFrontArc) {
+            const dx = e.position_m.x - attacker.position_m.x;
+            const dy = e.position_m.y - attacker.position_m.y;
+            const dz = e.position_m.z - attacker.position_m.z;
+            const dir = normaliseDirCheapQ({ x: dx, y: dy, z: dz });
+            const dot = dotDirQ(attacker.action.facingDirQ, dir);
+            const minDot = q.minDotQ ?? 0;
+            if (dot < minDot)
+                continue;
+        }
+        cand.push(e);
+        if (cand.length >= q.maxTargets) {
+            break;
+        }
+    }
+    if (cand.length === 0)
+        return undefined;
+    // Deterministic pick: smallest distance², tie by id
+    let best = cand[0];
+    let bestD2 = dist2(attacker, best);
+    for (let i = 1; i < cand.length; i++) {
+        const e = cand[i];
+        const d2 = dist2(attacker, e);
+        if (d2 < bestD2 || (d2 === bestD2 && e.id < best.id)) {
+            best = e;
+            bestD2 = d2;
+        }
+    }
+    return best;
+}
+function dist2(a, b) {
+    const dx = b.position_m.x - a.position_m.x;
+    const dy = b.position_m.y - a.position_m.y;
+    const dz = b.position_m.z - a.position_m.z;
+    return BigInt(dx) * BigInt(dx) + BigInt(dy) * BigInt(dy) + BigInt(dz) * BigInt(dz);
+}

package/dist/src/sim/frontage.d.ts

@@ -0,0 +1,30 @@
+import type { ImpactEvent } from "./events.js";
+import type { WorldIndex } from "./indexing.js";
+import type { ObstacleGrid } from "./terrain.js";
+export interface FrontageRules {
+    maxEngagersPerTarget: number;
+}
+export declare function applyFrontageCap(impacts: ImpactEvent[], index: WorldIndex, rules: FrontageRules): ImpactEvent[];
+/**
+ * Phase 32E: Compute the passable frontage width (in entity-widths) through a
+ * corridor at `position_m` perpendicular to `facingDir`.
+ *
+ * Scans cells across the perpendicular axis within `scanRange_m` and counts
+ * cells where cover < SCALE.Q (not fully impassable). Returns the count as a
+ * rough maximum engager cap. Falls back to `defaultCap` when no grid is provided.
+ *
+ * @param obstacleGrid   Obstacle grid (may be undefined)
+ * @param cellSize_m     Grid cell size in SCALE.m units
+ * @param position_m     Centre of the corridor query
+ * @param facingDir      Unit direction of movement (used to determine perpendicular)
+ * @param scanRange_m    How far left/right to scan (SCALE.m)
+ * @param entityWidth_m  Average entity body width (SCALE.m; default 0.5 m)
+ * @param defaultCap     Cap to return when obstacleGrid is undefined
+ */
+export declare function computeChokeCapacity(obstacleGrid: ObstacleGrid | undefined, cellSize_m: number, position_m: {
+    x: number;
+    y: number;
+}, facingDir: {
+    x: number;
+    y: number;
+}, scanRange_m: number, entityWidth_m?: number, defaultCap?: number): number;

package/dist/src/sim/frontage.js

@@ -0,0 +1,84 @@
+import { SCALE } from "../units.js";
+import { coverFractionAtPosition } from "./terrain.js";
+export function applyFrontageCap(impacts, index, rules) {
+    const maxK = Math.max(1, rules.maxEngagersPerTarget);
+    // group by targetId
+    const byTarget = new Map();
+    for (const ev of impacts) {
+        let arr = byTarget.get(ev.targetId);
+        if (!arr) {
+            arr = [];
+            byTarget.set(ev.targetId, arr);
+        }
+        arr.push(ev);
+    }
+    const kept = [];
+    for (const [targetId, arr] of byTarget.entries()) {
+        if (arr.length <= maxK) {
+            for (const ev of arr)
+                kept.push(ev);
+            continue;
+        }
+        const target = index.byId.get(targetId);
+        if (!target)
+            continue;
+        // sort attackers by distance² then attackerId
+        arr.sort((a, b) => {
+            const da = dist2ByIds(index, a.attackerId, target);
+            const db = dist2ByIds(index, b.attackerId, target);
+            if (da < db)
+                return -1;
+            if (da > db)
+                return 1;
+            return a.attackerId - b.attackerId;
+        });
+        for (let i = 0; i < maxK; i++)
+            kept.push(arr[i]);
+    }
+    return kept;
+}
+/**
+ * Phase 32E: Compute the passable frontage width (in entity-widths) through a
+ * corridor at `position_m` perpendicular to `facingDir`.
+ *
+ * Scans cells across the perpendicular axis within `scanRange_m` and counts
+ * cells where cover < SCALE.Q (not fully impassable). Returns the count as a
+ * rough maximum engager cap. Falls back to `defaultCap` when no grid is provided.
+ *
+ * @param obstacleGrid   Obstacle grid (may be undefined)
+ * @param cellSize_m     Grid cell size in SCALE.m units
+ * @param position_m     Centre of the corridor query
+ * @param facingDir      Unit direction of movement (used to determine perpendicular)
+ * @param scanRange_m    How far left/right to scan (SCALE.m)
+ * @param entityWidth_m  Average entity body width (SCALE.m; default 0.5 m)
+ * @param defaultCap     Cap to return when obstacleGrid is undefined
+ */
+export function computeChokeCapacity(obstacleGrid, cellSize_m, position_m, facingDir, scanRange_m, entityWidth_m = Math.trunc(0.5 * SCALE.m), defaultCap = 100) {
+    if (!obstacleGrid)
+        return defaultCap;
+    if (cellSize_m <= 0 || entityWidth_m <= 0)
+        return defaultCap;
+    // Perpendicular to facing (rotate 90°)
+    const perpX = -facingDir.y;
+    const perpY = facingDir.x;
+    let passableCells = 0;
+    const steps = Math.max(1, Math.round(scanRange_m / cellSize_m));
+    for (let i = -steps; i <= steps; i++) {
+        const cx = position_m.x + Math.trunc(perpX * i * cellSize_m);
+        const cy = position_m.y + Math.trunc(perpY * i * cellSize_m);
+        const cov = coverFractionAtPosition(obstacleGrid, cellSize_m, cx, cy);
+        if (cov < SCALE.Q)
+            passableCells++;
+    }
+    const passableWidth = passableCells * cellSize_m;
+    return Math.max(1, Math.floor(passableWidth / entityWidth_m));
+}
+function dist2ByIds(index, attackerId, target) {
+    const a = index.byId.get(attackerId);
+    if (!a)
+        return (1n << 62n); // big + safe, avoids magic decimal
+    const dx = target.position_m.x - a.position_m.x;
+    const dy = target.position_m.y - a.position_m.y;
+    const dz = target.position_m.z - a.position_m.z;
+    return BigInt(dx) * BigInt(dx) + BigInt(dy) * BigInt(dy) + BigInt(dz) * BigInt(dz);
+}

package/dist/src/sim/grapple.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Phase 2A: Grapple resolution — deterministic close-combat control.
+ *
+ * Design rules:
+ *  - All randomness via eventSeed() + salt, never Math.random()
+ *  - Pair-based ordering: idLo = Math.min(a, b), idHi = Math.max(a, b)
+ *  - No mutation of entities mid-resolution across independent pairs
+ *  - All physical quantities in SI fixed-point (SCALE.*)
+ */
+import { type Q } from "../units.js";
+import type { Entity } from "./entity.js";
+import type { WorldState } from "./world.js";
+import type { WorldIndex } from "./indexing.js";
+import type { FunctionalState } from "./impairment.js";
+import type { TraceSink } from "./trace.js";
+import type { SimulationTuning } from "./tuning.js";
+import type { ImpactEvent } from "./events.js";
+import type { Weapon } from "../equipment.js";
+export declare const GRIP_DECAY_PER_TICK: Q;
+export declare const GRAPPLE_THROW_WPN: Weapon;
+export declare const GRAPPLE_JOINTLOCK_WPN: Weapon;
+/**
+ * Compute an entity's grapple contest score in Q [0.05, 0.95].
+ *
+ * Combines:
+ *   50% peak force (normalised to human baseline)
+ *   30% technique  (controlQuality × stability)
+ *   20% body mass  (normalised to human baseline)
+ *
+ * The result is modulated by the entity's current functional state
+ * (injury, fatigue) via manipulationMul.
+ *
+ * A healthy average human scores ≈ q(0.47).
+ */
+export declare function grappleContestScore(e: Entity, func: FunctionalState): Q;
+/**
+ * Attempt to initiate a grapple on the target.
+ *
+ * Contest: scoreA × intensity vs scoreB. Success probability centred at 0.50
+ * with ±40% swing per unit score difference (mirrors melee hit formula).
+ *
+ * On success:
+ *   - Attacker's grapple.holdingTargetId and gripQ are set
+ *   - Target's grapple.heldByIds is updated (sorted, deduplicated)
+ *   - Overwhelming leverage differential causes immediate trip (prone + small impact)
+ *
+ * On failure: grappleCooldownTicks set, energy still drained.
+ */
+export declare function resolveGrappleAttempt(world: WorldState, attacker: Entity, target: Entity, intensity: Q, tuning: SimulationTuning, impacts: ImpactEvent[], trace: TraceSink): void;
+/**
+ * Attempt to throw or trip the grappled target.
+ *
+ * Requires: attacker already holds the target (holdingTargetId === target.id).
+ * Success probability based on signed leverage differential.
+ *
+ * On success: target goes prone, kinetic impact queued, grapple released.
+ * On failure: cooldown set, energy still drained.
+ *
+ * Impact energy ∝ target mass × leverage advantage × intensity (see formula in code).
+ */
+export declare function resolveGrappleThrow(world: WorldState, attacker: Entity, target: Entity, intensity: Q, tuning: SimulationTuning, impacts: ImpactEvent[], trace: TraceSink): void;
+/**
+ * Apply a choke hold: accumulates suffocation on the target.
+ *
+ * Requires position !== "standing" in tactical/sim (must be on the ground).
+ * Sufficient grip quality (> 0.60) transitions the position to "pinned" and
+ * sets target.condition.pinned.
+ */
+export declare function resolveGrappleChoke(attacker: Entity, target: Entity, intensity: Q, tuning: SimulationTuning): void;
+/**
+ * Apply a joint-lock: structural damage to a target limb.
+ *
+ * Requires position !== "standing" in tactical/sim.
+ * Target limb selected deterministically (stable across seeds).
+ *
+ * Impact energy = peakForce × 0.05 m effective displacement × grip × intensity.
+ */
+export declare function resolveGrappleJointLock(world: WorldState, attacker: Entity, target: Entity, intensity: Q, tuning: SimulationTuning, impacts: ImpactEvent[]): void;
+/**
+ * Attempt to break free from all current holders.
+ *
+ * Pair-based: each holder gets an independent contest (lower id owns the seed).
+ * On success: releaseGrapple() called for that holder.
+ * Energy drained per holder attempt regardless of outcome.
+ */
+export declare function resolveBreakGrapple(world: WorldState, breaker: Entity, intensity: Q, tuning: SimulationTuning, index: WorldIndex, trace: TraceSink): void;
+/**
+ * Per-tick maintenance for active grapples.
+ * Call once per entity per tick (regardless of whether a grapple command was issued).
+ *
+ *  - Drains stamina from the holder
+ *  - Decays gripQ by GRIP_DECAY_PER_TICK
+ *  - Releases grapple when grip reaches 0 or target is dead/missing
+ */
+export declare function stepGrappleTick(world: WorldState, entity: Entity, index: WorldIndex): void;
+/**
+ * Release a grapple link, updating both the holder and (optionally) the target.
+ * Safe to call with a null target (e.g. when target entity was already removed).
+ */
+export declare function releaseGrapple(holder: Entity, target: Entity | null): void;