@its-not-rocket-science/ananke 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -10,6 +10,43 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.7] — 2026-03-23
+
+  ### Added
+
+  - **CE-9 · World-state Diffing and Incremental Snapshots** (`src/sim/cover.ts`)
+    - diffWorldState(prev, next): top-level-field diff per entity; world
+      scalar/subsystem diffs; added/removed entity tracking
+    - applyDiff(base, diff): reconstruct next state (non-mutating, copy-on-write)
+    - packDiff(diff): custom binary encoding — magic "ANKD", tagged-value
+      format (null/bool/uint8/int32/float64/string/array/object); zero
+      external dependencies, implemented with DataView/Uint8Array
+    - unpackDiff(bytes): full round-trip with magic and version validation
+    - isDiffEmpty(), diffStats() — helpers for logging and network budgeting
+    - 30 tests; verified binary size < full JSON for single-entity changes
+    - Export via src/index.ts
+
+---
+
+---
+
+## [0.1.6] — 2026-03-23
+
+  ### Added
+
+  - **CE-15 · Dynamic Terrain Cover System** (`src/sim/cover.ts`)
+    - CoverSegment type: axis-aligned obstacle with material, height, burn state
+    - isLineOfSightBlocked(): pure integer segment-intersection test (no sqrt)
+    - computeCoverProtection(): multiplicative absorption across stacked cover
+    - arcClearsCover(): indirect/lob fire height check
+    - applyExplosionToTerrain(): proximity-scaled crater + wood ignition
+    - stepCoverDecay(): wood burn-out and crater erosion over real time
+    - 4 sample presets: stone wall, sandbag barricade, wooden palisade, dirt berm
+    - 60 tests
+    - Export via src/index.ts
+
+---
+
 ## [0.1.5] — 2026-03-21
 
   ### Added

package/dist/src/index.d.ts

@@ -18,3 +18,7 @@ export * from "./bridge/index.js";
 export * from "./world-factory.js";
 export * from "./scenario.js";
 export * from "./catalog.js";
+export * from "./sim/formation-combat.js";
+export * from "./sim/cover.js";
+export * from "./sim/ai/behavior-trees.js";
+export * from "./snapshot.js";

package/dist/src/index.js

@@ -27,3 +27,7 @@ export * from "./bridge/index.js"; // BridgeEngine, InterpolatedState, BridgeCon
 export * from "./world-factory.js"; // createWorld(), EntitySpec, ARCHETYPE_MAP, ITEM_MAP
 export * from "./scenario.js"; // loadScenario(), validateScenario(), AnankeScenario
 export * from "./catalog.js"; // CE-12: registerArchetype(), registerWeapon(), registerArmour(), getCatalogEntry()
+export * from "./sim/formation-combat.js"; // Phase 69: FormationUnit, TacticalEngagement, resolveTacticalEngagement()
+export * from "./sim/cover.js"; // CE-15: CoverSegment, computeCoverProtection(), isLineOfSightBlocked(), applyExplosionToTerrain()
+export * from "./sim/ai/behavior-trees.js"; // CE-10: BehaviorNode, FlankTarget, RetreatTo, ProtectAlly, GuardPosition, HealTarget, Sequence, Fallback
+export * from "./snapshot.js"; // CE-9: diffWorldState(), applyDiff(), packDiff(), unpackDiff(), WorldStateDiff

package/dist/src/sim/ai/behavior-trees.d.ts

@@ -0,0 +1,166 @@
+/**
+ * CE-10 — Pre-built AI Behavior Tree Library
+ *
+ * A thin, composable layer over the existing AI decision system.  Each
+ * `BehaviorNode` receives the ticking entity, the current world state, and
+ * kernel context, and either returns a `Command` (success) or `null` (failure /
+ * not applicable).
+ *
+ * ## Semantics
+ * - `null`  — node failed / condition not met
+ * - Command — node succeeded; caller should use this command
+ *
+ * ## Composite nodes
+ * - `Sequence`  — run children left-to-right; return first **non-null** result
+ *                 (priority / fallback selector pattern)
+ * - `Fallback`  — identical semantics to Sequence for this usage:
+ *                 try children in order, first non-null wins
+ *
+ * Note: The ROADMAP spec uses "first success wins" for both Sequence and
+ * Fallback (i.e. both are priority-selectors).  A traditional BT Sequence
+ * would return the *last* child result; here all composites return the first
+ * non-null command for practical game-AI use.
+ *
+ * ## Determinism constraint
+ * All nodes are deterministic.  Any tie-breaking or random sampling uses
+ * `eventSeed(world.seed, world.tick, entity.id, salt)` — never `Math.random()`.
+ */
+import type { Entity } from "../entity.js";
+import type { WorldState } from "../world.js";
+import type { KernelContext } from "../context.js";
+import type { Command } from "../commands.js";
+import { type Q } from "../../units.js";
+/**
+ * A single node in a behavior tree.
+ *
+ * `tick` is called once per AI frame (typically once per `stepWorld` tick).
+ * Returns a `Command` if this node produces an action, or `null` if the node's
+ * condition is not satisfied (pass control to the next node in a composite).
+ */
+export interface BehaviorNode {
+    tick(entity: Entity, world: WorldState, ctx: KernelContext): Command | null;
+}
+/**
+ * Move toward a target entity and attack when in range.
+ *
+ * If the target is dead or missing, returns null.
+ * Flanks by approaching from the target's perpendicular when `flankOffset > 0`.
+ *
+ * @param targetId     Id of the entity to flank/attack.
+ * @param flankOffset  Lateral offset in SCALE.m units (0 = direct approach).
+ */
+export declare function FlankTarget(targetId: number, flankOffset?: number): BehaviorNode;
+/**
+ * Move to a fixed world position and stop when within `arrivalRadius_m` metres.
+ *
+ * Returns null when already at the destination (no command needed).
+ *
+ * @param x_m           Destination x [SCALE.m].
+ * @param y_m           Destination y [SCALE.m].
+ * @param arrivalRadius_m  Stop radius [SCALE.m]. Default 5 000 (0.5 m).
+ */
+export declare function RetreatTo(x_m: number, y_m: number, arrivalRadius_m?: number): BehaviorNode;
+/**
+ * Move toward an allied entity and interpose between it and the nearest threat.
+ *
+ * - If ally is missing or dead, returns null.
+ * - If no threats (other entities) are present, returns null.
+ * - Otherwise moves toward the ally.
+ *
+ * @param allyId   Id of the entity to protect.
+ */
+export declare function ProtectAlly(allyId: number): BehaviorNode;
+/**
+ * Hold a position: move toward the guard point if outside `radius_m`, defend
+ * if inside.  Returns null when the entity is already inside the radius and
+ * there are no threats to defend against.
+ *
+ * @param x_m       Guard point x [SCALE.m].
+ * @param y_m       Guard point y [SCALE.m].
+ * @param radius_m  Patrol radius [SCALE.m].
+ */
+export declare function GuardPosition(x_m: number, y_m: number, radius_m: number): BehaviorNode;
+/**
+ * Move toward a target entity and issue a Treat command when in range.
+ *
+ * - Returns null if target is missing, already dead, or has no injuries.
+ * - Healing uses the first injured region found (deterministic iteration order).
+ *
+ * @param targetId   Id of the entity to heal.
+ */
+export declare function HealTarget(targetId: number): BehaviorNode;
+/**
+ * Priority selector: tries each child node in order and returns the first
+ * non-null command.  If all children return null, returns null.
+ *
+ * This is the most commonly used composite.  Place higher-priority behaviours
+ * earlier in the list.
+ *
+ * @param nodes  Child nodes to evaluate in order.
+ */
+export declare function Sequence(...nodes: BehaviorNode[]): BehaviorNode;
+/**
+ * Fallback: identical to `Sequence` — tries children in order, returns first
+ * non-null result.  Provided as a semantic alias for callers who prefer the
+ * standard BT naming convention (Sequence = AND-chain; Fallback = OR-chain).
+ *
+ * @param nodes  Child nodes to evaluate in order.
+ */
+export declare function Fallback(...nodes: BehaviorNode[]): BehaviorNode;
+/**
+ * Gate: return `inner.tick()` only if the entity's shock is below `maxShockQ`.
+ * When the entity is in severe shock it cannot act — returns null instead.
+ *
+ * Useful for wrapping aggressive nodes: "attack only if not badly shocked."
+ *
+ * @param maxShockQ  Q threshold; entity.injury.shock must be below this.
+ * @param inner      Wrapped node.
+ */
+export declare function IfNotShocked(maxShockQ: Q, inner: BehaviorNode): BehaviorNode;
+/**
+ * Gate: return `inner.tick()` only when `entity.energy.fatigue` is below
+ * `maxFatigueQ`.  Prevents exhausted entities from taking high-intensity actions.
+ *
+ * @param maxFatigueQ  Q threshold; fatigue must be below this.
+ * @param inner        Wrapped node.
+ */
+export declare function IfNotExhausted(maxFatigueQ: Q, inner: BehaviorNode): BehaviorNode;
+/**
+ * Probabilistic gate: run `inner` only when
+ * `eventSeed(world.seed, world.tick, entity.id, salt) % SCALE.Q < probability_Q`.
+ *
+ * Allows stochastic variation without `Math.random()`.
+ *
+ * @param probability_Q  Q probability [0..SCALE.Q]; q(1.0) = always, q(0) = never.
+ * @param salt           Arbitrary integer to distinguish independent rolls on the
+ *                       same entity+tick (default 0).
+ * @param inner          Wrapped node.
+ */
+export declare function WithProbability(probability_Q: Q, inner: BehaviorNode, salt?: number): BehaviorNode;
+/**
+ * Standard aggressive attacker: attack `targetId` at full intensity.
+ * Falls back to retreat if badly shocked (shock ≥ q(0.70)).
+ *
+ * @param targetId   Primary attack target.
+ * @param retreatX   Fallback retreat x [SCALE.m].
+ * @param retreatY   Fallback retreat y [SCALE.m].
+ */
+export declare function aggressorTree(targetId: number, retreatX: number, retreatY: number): BehaviorNode;
+/**
+ * Standard defender: hold position, heal allies when in range, defend otherwise.
+ *
+ * @param guardX     Guard point x [SCALE.m].
+ * @param guardY     Guard point y [SCALE.m].
+ * @param radius_m   Guard radius [SCALE.m].
+ * @param allyIds    Ally ids to heal (checked in order; first injured ally wins).
+ */
+export declare function defenderTree(guardX: number, guardY: number, radius_m: number, allyIds: number[]): BehaviorNode;
+/**
+ * Medic tree: prioritise healing each ally in the given list (first injured wins),
+ * then retreat to a safe point if badly shocked.
+ *
+ * @param allyIds    Allies to heal in priority order.
+ * @param safeX      Retreat x [SCALE.m].
+ * @param safeY      Retreat y [SCALE.m].
+ */
+export declare function medicTree(allyIds: number[], safeX: number, safeY: number): BehaviorNode;

package/dist/src/sim/ai/behavior-trees.js

@@ -0,0 +1,340 @@
+/**
+ * CE-10 — Pre-built AI Behavior Tree Library
+ *
+ * A thin, composable layer over the existing AI decision system.  Each
+ * `BehaviorNode` receives the ticking entity, the current world state, and
+ * kernel context, and either returns a `Command` (success) or `null` (failure /
+ * not applicable).
+ *
+ * ## Semantics
+ * - `null`  — node failed / condition not met
+ * - Command — node succeeded; caller should use this command
+ *
+ * ## Composite nodes
+ * - `Sequence`  — run children left-to-right; return first **non-null** result
+ *                 (priority / fallback selector pattern)
+ * - `Fallback`  — identical semantics to Sequence for this usage:
+ *                 try children in order, first non-null wins
+ *
+ * Note: The ROADMAP spec uses "first success wins" for both Sequence and
+ * Fallback (i.e. both are priority-selectors).  A traditional BT Sequence
+ * would return the *last* child result; here all composites return the first
+ * non-null command for practical game-AI use.
+ *
+ * ## Determinism constraint
+ * All nodes are deterministic.  Any tie-breaking or random sampling uses
+ * `eventSeed(world.seed, world.tick, entity.id, salt)` — never `Math.random()`.
+ */
+import { CommandKinds, MoveModes, DefenceModes } from "../kinds.js";
+import { q, SCALE } from "../../units.js";
+import { eventSeed } from "../seeds.js";
+// ── Internal geometry helpers ─────────────────────────────────────────────────
+/** Squared distance between two entities (position_m, 2-D x/y). */
+function distSq2D(a, b) {
+    const dx = b.position_m.x - a.position_m.x;
+    const dy = b.position_m.y - a.position_m.y;
+    return dx * dx + dy * dy;
+}
+/** Integer square-root approximation via Newton's method (no float dependency). */
+function isqrt(n) {
+    if (n <= 0)
+        return 0;
+    let x = Math.round(Math.sqrt(n));
+    // One Newton step for accuracy at fixed-point scales
+    x = Math.trunc((x + Math.trunc(n / Math.max(1, x))) / 2);
+    return Math.max(0, x);
+}
+/** Signed direction from `from` to `to`, normalised to unit Q vector. */
+function dirTo(fromX, fromY, toX, toY) {
+    const dx = toX - fromX;
+    const dy = toY - fromY;
+    const len = isqrt(dx * dx + dy * dy);
+    if (len === 0)
+        return { x: 0, y: 0, z: 0 };
+    return {
+        x: Math.round((dx * SCALE.Q) / len),
+        y: Math.round((dy * SCALE.Q) / len),
+        z: 0,
+    };
+}
+/** Find an entity by id in the world, or undefined. */
+function findEntity(world, id) {
+    return world.entities.find(e => e.id === id);
+}
+/** True if entity is dead or unconscious. */
+function isIncapacitated(e) {
+    return (e.injury?.dead ?? false) || (e.injury?.consciousness ?? SCALE.Q) <= 0;
+}
+// ── Leaf nodes ────────────────────────────────────────────────────────────────
+/**
+ * Move toward a target entity and attack when in range.
+ *
+ * If the target is dead or missing, returns null.
+ * Flanks by approaching from the target's perpendicular when `flankOffset > 0`.
+ *
+ * @param targetId     Id of the entity to flank/attack.
+ * @param flankOffset  Lateral offset in SCALE.m units (0 = direct approach).
+ */
+export function FlankTarget(targetId, flankOffset = 0) {
+    return {
+        tick(entity, world) {
+            const target = findEntity(world, targetId);
+            if (!target || isIncapacitated(target))
+                return null;
+            const tx = target.position_m.x + flankOffset;
+            const ty = target.position_m.y;
+            const threshold = 15_000 * 15_000; // ~1.5 m in SCALE.m
+            if (distSq2D(entity, target) <= threshold) {
+                // In melee range — attack
+                return { kind: CommandKinds.Attack, targetId, intensity: q(1.0) };
+            }
+            const dir = dirTo(entity.position_m.x, entity.position_m.y, tx, ty);
+            return { kind: CommandKinds.Move, dir, intensity: q(1.0), mode: MoveModes.Run };
+        },
+    };
+}
+/**
+ * Move to a fixed world position and stop when within `arrivalRadius_m` metres.
+ *
+ * Returns null when already at the destination (no command needed).
+ *
+ * @param x_m           Destination x [SCALE.m].
+ * @param y_m           Destination y [SCALE.m].
+ * @param arrivalRadius_m  Stop radius [SCALE.m]. Default 5 000 (0.5 m).
+ */
+export function RetreatTo(x_m, y_m, arrivalRadius_m = 5_000) {
+    return {
+        tick(entity) {
+            const dx = x_m - entity.position_m.x;
+            const dy = y_m - entity.position_m.y;
+            const r = arrivalRadius_m;
+            if (dx * dx + dy * dy <= r * r)
+                return null; // already there
+            const dir = dirTo(entity.position_m.x, entity.position_m.y, x_m, y_m);
+            return { kind: CommandKinds.Move, dir, intensity: q(1.0), mode: MoveModes.Run };
+        },
+    };
+}
+/**
+ * Move toward an allied entity and interpose between it and the nearest threat.
+ *
+ * - If ally is missing or dead, returns null.
+ * - If no threats (other entities) are present, returns null.
+ * - Otherwise moves toward the ally.
+ *
+ * @param allyId   Id of the entity to protect.
+ */
+export function ProtectAlly(allyId) {
+    return {
+        tick(entity, world) {
+            const ally = findEntity(world, allyId);
+            if (!ally || isIncapacitated(ally))
+                return null;
+            // Require at least one other living entity to protect against
+            const threats = world.entities.filter(e => e.id !== entity.id && e.id !== allyId && !isIncapacitated(e));
+            if (threats.length === 0)
+                return null;
+            const threshold = 20_000 * 20_000; // 2 m
+            if (distSq2D(entity, ally) <= threshold) {
+                // Close enough — defend
+                return { kind: CommandKinds.Defend, mode: DefenceModes.Block, intensity: q(1.0) };
+            }
+            const dir = dirTo(entity.position_m.x, entity.position_m.y, ally.position_m.x, ally.position_m.y);
+            return { kind: CommandKinds.Move, dir, intensity: q(1.0), mode: MoveModes.Run };
+        },
+    };
+}
+/**
+ * Hold a position: move toward the guard point if outside `radius_m`, defend
+ * if inside.  Returns null when the entity is already inside the radius and
+ * there are no threats to defend against.
+ *
+ * @param x_m       Guard point x [SCALE.m].
+ * @param y_m       Guard point y [SCALE.m].
+ * @param radius_m  Patrol radius [SCALE.m].
+ */
+export function GuardPosition(x_m, y_m, radius_m) {
+    return {
+        tick(entity, world) {
+            const dx = x_m - entity.position_m.x;
+            const dy = y_m - entity.position_m.y;
+            const rSq = radius_m * radius_m;
+            const insideRadius = dx * dx + dy * dy <= rSq;
+            if (!insideRadius) {
+                const dir = dirTo(entity.position_m.x, entity.position_m.y, x_m, y_m);
+                return { kind: CommandKinds.Move, dir, intensity: q(1.0), mode: MoveModes.Walk };
+            }
+            // Inside radius — defend if threats present
+            const threats = world.entities.filter(e => e.id !== entity.id && !isIncapacitated(e));
+            if (threats.length === 0)
+                return null;
+            return { kind: CommandKinds.Defend, mode: DefenceModes.Block, intensity: q(0.5) };
+        },
+    };
+}
+/**
+ * Move toward a target entity and issue a Treat command when in range.
+ *
+ * - Returns null if target is missing, already dead, or has no injuries.
+ * - Healing uses the first injured region found (deterministic iteration order).
+ *
+ * @param targetId   Id of the entity to heal.
+ */
+export function HealTarget(targetId) {
+    return {
+        tick(entity, world) {
+            const target = findEntity(world, targetId);
+            if (!target || target.injury?.dead)
+                return null;
+            // Find an injured region with surface or internal damage
+            const byRegion = target.injury?.byRegion;
+            if (!byRegion)
+                return null;
+            let injuredRegionId;
+            for (const [regionId, region] of Object.entries(byRegion)) {
+                if ((region.surfaceDamage ?? 0) > 0 || (region.internalDamage ?? 0) > 0) {
+                    injuredRegionId = regionId;
+                    break;
+                }
+            }
+            if (!injuredRegionId)
+                return null;
+            const threshold = 10_000 * 10_000; // 1 m
+            if (distSq2D(entity, target) > threshold) {
+                const dir = dirTo(entity.position_m.x, entity.position_m.y, target.position_m.x, target.position_m.y);
+                return { kind: CommandKinds.Move, dir, intensity: q(0.5), mode: MoveModes.Walk };
+            }
+            return {
+                kind: CommandKinds.Treat,
+                targetId,
+                action: "bandage",
+                tier: "bandage",
+                regionId: injuredRegionId,
+            };
+        },
+    };
+}
+// ── Composite nodes ───────────────────────────────────────────────────────────
+/**
+ * Priority selector: tries each child node in order and returns the first
+ * non-null command.  If all children return null, returns null.
+ *
+ * This is the most commonly used composite.  Place higher-priority behaviours
+ * earlier in the list.
+ *
+ * @param nodes  Child nodes to evaluate in order.
+ */
+export function Sequence(...nodes) {
+    return {
+        tick(entity, world, ctx) {
+            for (const node of nodes) {
+                const result = node.tick(entity, world, ctx);
+                if (result !== null)
+                    return result;
+            }
+            return null;
+        },
+    };
+}
+/**
+ * Fallback: identical to `Sequence` — tries children in order, returns first
+ * non-null result.  Provided as a semantic alias for callers who prefer the
+ * standard BT naming convention (Sequence = AND-chain; Fallback = OR-chain).
+ *
+ * @param nodes  Child nodes to evaluate in order.
+ */
+export function Fallback(...nodes) {
+    return Sequence(...nodes);
+}
+// ── Condition-gate nodes ──────────────────────────────────────────────────────
+/**
+ * Gate: return `inner.tick()` only if the entity's shock is below `maxShockQ`.
+ * When the entity is in severe shock it cannot act — returns null instead.
+ *
+ * Useful for wrapping aggressive nodes: "attack only if not badly shocked."
+ *
+ * @param maxShockQ  Q threshold; entity.injury.shock must be below this.
+ * @param inner      Wrapped node.
+ */
+export function IfNotShocked(maxShockQ, inner) {
+    return {
+        tick(entity, world, ctx) {
+            if ((entity.injury?.shock ?? 0) >= maxShockQ)
+                return null;
+            return inner.tick(entity, world, ctx);
+        },
+    };
+}
+/**
+ * Gate: return `inner.tick()` only when `entity.energy.fatigue` is below
+ * `maxFatigueQ`.  Prevents exhausted entities from taking high-intensity actions.
+ *
+ * @param maxFatigueQ  Q threshold; fatigue must be below this.
+ * @param inner        Wrapped node.
+ */
+export function IfNotExhausted(maxFatigueQ, inner) {
+    return {
+        tick(entity, world, ctx) {
+            if ((entity.energy?.fatigue ?? 0) >= maxFatigueQ)
+                return null;
+            return inner.tick(entity, world, ctx);
+        },
+    };
+}
+/**
+ * Probabilistic gate: run `inner` only when
+ * `eventSeed(world.seed, world.tick, entity.id, salt) % SCALE.Q < probability_Q`.
+ *
+ * Allows stochastic variation without `Math.random()`.
+ *
+ * @param probability_Q  Q probability [0..SCALE.Q]; q(1.0) = always, q(0) = never.
+ * @param salt           Arbitrary integer to distinguish independent rolls on the
+ *                       same entity+tick (default 0).
+ * @param inner          Wrapped node.
+ */
+export function WithProbability(probability_Q, inner, salt = 0) {
+    return {
+        tick(entity, world, ctx) {
+            const roll = eventSeed(world.seed, world.tick, entity.id, 0, salt) % SCALE.Q;
+            if (roll >= probability_Q)
+                return null;
+            return inner.tick(entity, world, ctx);
+        },
+    };
+}
+// ── Pre-built behavior tree presets ──────────────────────────────────────────
+/**
+ * Standard aggressive attacker: attack `targetId` at full intensity.
+ * Falls back to retreat if badly shocked (shock ≥ q(0.70)).
+ *
+ * @param targetId   Primary attack target.
+ * @param retreatX   Fallback retreat x [SCALE.m].
+ * @param retreatY   Fallback retreat y [SCALE.m].
+ */
+export function aggressorTree(targetId, retreatX, retreatY) {
+    return Sequence(IfNotShocked(q(0.70), FlankTarget(targetId)), RetreatTo(retreatX, retreatY));
+}
+/**
+ * Standard defender: hold position, heal allies when in range, defend otherwise.
+ *
+ * @param guardX     Guard point x [SCALE.m].
+ * @param guardY     Guard point y [SCALE.m].
+ * @param radius_m   Guard radius [SCALE.m].
+ * @param allyIds    Ally ids to heal (checked in order; first injured ally wins).
+ */
+export function defenderTree(guardX, guardY, radius_m, allyIds) {
+    const healNodes = allyIds.map(id => HealTarget(id));
+    return Sequence(...healNodes, GuardPosition(guardX, guardY, radius_m));
+}
+/**
+ * Medic tree: prioritise healing each ally in the given list (first injured wins),
+ * then retreat to a safe point if badly shocked.
+ *
+ * @param allyIds    Allies to heal in priority order.
+ * @param safeX      Retreat x [SCALE.m].
+ * @param safeY      Retreat y [SCALE.m].
+ */
+export function medicTree(allyIds, safeX, safeY) {
+    const healNodes = allyIds.map(id => HealTarget(id));
+    return Sequence(IfNotShocked(q(0.80), Sequence(...healNodes)), RetreatTo(safeX, safeY));
+}