@its-not-rocket-science/ananke 0.1.0

package/dist/src/sim/ai/personality.js

@@ -0,0 +1,202 @@
+// src/sim/ai/personality.ts — Phase 47: Advanced AI Personalities
+//
+// Four orthogonal personality axes modulate decision-making on top of the base AIPolicy:
+//
+//   aggression  → retreat range (less retreat) + hesitation override
+//   caution     → defence intensity boost
+//   loyalty     → switches focus target to protect a distressed ally
+//   opportunism → switches focus target to the most-wounded enemy
+//
+// All modifiers are delta-based around q(0.50): neutral personality produces
+// identical behaviour to absent personality.
+import { SCALE, q, clampQ, mulDiv } from "../../units.js";
+import { computeCompanionLoyalty } from "../../party.js";
+import { eventSeed } from "../seeds.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Neutral personality: q(0.50) on all axes.
+ * Produces identical behaviour to an entity with no personality set.
+ */
+export const NEUTRAL_PERSONALITY = {
+    aggression: q(0.50),
+    caution: q(0.50),
+    loyalty: q(0.50),
+    opportunism: q(0.50),
+};
+/** Named predefined personalities. */
+export const PERSONALITIES = {
+    /** Charges into melee, ignores pain and fear, rarely retreats. */
+    berserker: {
+        aggression: q(0.90),
+        caution: q(0.10),
+        loyalty: q(0.30),
+        opportunism: q(0.20),
+    },
+    /** Avoids engagement, maximises defence and retreat distance. */
+    coward: {
+        aggression: q(0.10),
+        caution: q(0.90),
+        loyalty: q(0.20),
+        opportunism: q(0.70),
+    },
+    /** Shields allies at personal cost; steadfast defender. */
+    guardian: {
+        aggression: q(0.55),
+        caution: q(0.55),
+        loyalty: q(0.90),
+        opportunism: q(0.15),
+    },
+    /** Targets the weak; disloyal; always looks for an advantage. */
+    schemer: {
+        aggression: q(0.40),
+        caution: q(0.70),
+        loyalty: q(0.10),
+        opportunism: q(0.90),
+    },
+    /** Disciplined, reliable, protects unit; balanced aggression. */
+    soldier: {
+        aggression: q(0.65),
+        caution: q(0.50),
+        loyalty: q(0.70),
+        opportunism: q(0.35),
+    },
+};
+// ── Derivation from cognitive profile ────────────────────────────────────────
+/**
+ * Derive a personality from existing cognitive and resilience attributes.
+ *
+ * Mapping rationale:
+ *   aggression  ← distressTolerance (pain tolerance → willing to keep fighting)
+ *   caution     ← intrapersonal     (self-awareness → more careful and defensive)
+ *   loyalty     ← interpersonal     (social empathy → protects allies)
+ *   opportunism ← logicalMathematical (planning → targets strategically)
+ */
+export function derivePersonalityFromCognition(attrs) {
+    return {
+        aggression: attrs.resilience.distressTolerance,
+        caution: (attrs.cognition?.intrapersonal ?? q(0.50)),
+        loyalty: (attrs.cognition?.interpersonal ?? q(0.50)),
+        opportunism: (attrs.cognition?.logicalMathematical ?? q(0.50)),
+    };
+}
+// ── Loyalty combination ──────────────────────────────────────────────────────
+/**
+ * Compute effective loyalty combining personality loyalty and companion loyalty to party leader.
+ * If entity belongs to a party and has a relationship with the leader, companion loyalty is used.
+ * Otherwise falls back to personality loyalty (or neutral q(0.50) if no personality).
+ */
+export function computeEffectiveLoyalty(self, world) {
+    const personality = self.personality;
+    const baseLoyalty = personality?.loyalty ?? q(0.50);
+    const partyRegistry = world.__partyRegistry;
+    if (!partyRegistry)
+        return baseLoyalty;
+    const partyId = self.party;
+    if (!partyId)
+        return baseLoyalty;
+    const party = partyRegistry.parties.get(partyId);
+    if (!party)
+        return baseLoyalty;
+    const leaderId = party.leaderId;
+    if (leaderId === self.id)
+        return baseLoyalty; // leader is self
+    const relationshipGraph = world.__relationshipGraph;
+    if (!relationshipGraph)
+        return baseLoyalty;
+    const companionLoyalty = computeCompanionLoyalty(self, leaderId, relationshipGraph);
+    // Use the higher of base loyalty or companion loyalty (max loyalty)
+    return companionLoyalty > baseLoyalty ? companionLoyalty : baseLoyalty;
+}
+// ── Pure formula helpers (exported for unit testing) ──────────────────────────
+/**
+ * Effective retreat range after aggression bias.
+ *
+ * aggression q(0.90) → range reduced by ~0.20m (fights more aggressively)
+ * aggression q(0.50) → unchanged
+ * aggression q(0.10) → range increased by ~0.20m (retreats sooner)
+ */
+export function computeEffectiveRetreatRange(baseRange_m, aggression) {
+    const delta = mulDiv(aggression - q(0.50), Math.trunc(0.40 * SCALE.m), SCALE.Q);
+    return Math.max(0, baseRange_m - delta);
+}
+/**
+ * Effective defence intensity after caution bias.
+ *
+ * caution q(0.90) → +q(0.20) max boost
+ * caution q(0.50) → unchanged
+ * caution q(0.10) → −q(0.20) max reduction
+ */
+export function computeDefenceIntensityBoost(baseIntensity, caution) {
+    const delta = mulDiv(caution - q(0.50), q(0.40), SCALE.Q);
+    return clampQ((baseIntensity + delta), q(0), q(1.0));
+}
+// ── Target bias functions ─────────────────────────────────────────────────────
+/** Ally shock/fluid-loss above this Q value counts as "in distress". */
+const ALLY_DISTRESS_Q = q(0.20);
+/** Enemy must be within this many SCALE.m units of the ally to count as a threat to them. */
+const ALLY_THREAT_RANGE_m = Math.trunc(2.5 * SCALE.m);
+const ALLY_THREAT_RANGE_m2 = ALLY_THREAT_RANGE_m * ALLY_THREAT_RANGE_m;
+/**
+ * Loyalty override: if an ally is in distress and has an enemy nearby, switch target to
+ * that enemy.  Only triggers when loyalty > q(0.50); roll probability = loyaltyQ / SCALE.Q.
+ */
+export function applyLoyaltyBias(self, world, currentTarget, loyaltyQ) {
+    if (loyaltyQ <= q(0.50))
+        return currentTarget;
+    for (const ally of world.entities) {
+        if (ally.teamId !== self.teamId || ally.id === self.id || ally.injury.dead)
+            continue;
+        const distressed = ally.injury.shock > ALLY_DISTRESS_Q
+            || ally.injury.fluidLoss > ALLY_DISTRESS_Q;
+        if (!distressed)
+            continue;
+        // Find the enemy nearest to this distressed ally
+        let threatEnemy;
+        let bestD2 = Infinity;
+        for (const e of world.entities) {
+            if (e.teamId === self.teamId || e.injury.dead)
+                continue;
+            const adx = e.position_m.x - ally.position_m.x;
+            const ady = e.position_m.y - ally.position_m.y;
+            const d2 = adx * adx + ady * ady;
+            if (d2 < ALLY_THREAT_RANGE_m2 && d2 < bestD2) {
+                bestD2 = d2;
+                threatEnemy = e;
+            }
+        }
+        if (!threatEnemy)
+            continue;
+        const seed = eventSeed(world.seed, world.tick, self.id, ally.id, 0x10A1B);
+        if ((seed % SCALE.Q) < loyaltyQ)
+            return threatEnemy;
+    }
+    return currentTarget;
+}
+/** Minimum consciousness difference for the weakest enemy to qualify for an opportunism switch. */
+const OPPORTUNISM_GAP = q(0.30);
+/**
+ * Opportunism override: if a significantly more-wounded enemy is present, switch target.
+ * Only triggers when opportunism > q(0.50); roll probability = opportunismQ / SCALE.Q.
+ */
+export function applyOpportunismBias(self, world, currentTarget, opportunismQ) {
+    if (opportunismQ <= q(0.50))
+        return currentTarget;
+    let weakest;
+    let lowestConsc = SCALE.Q + 1;
+    for (const e of world.entities) {
+        if (e.teamId === self.teamId || e.injury.dead)
+            continue;
+        if (e.injury.consciousness < lowestConsc) {
+            lowestConsc = e.injury.consciousness;
+            weakest = e;
+        }
+    }
+    if (!weakest || !currentTarget || weakest.id === currentTarget.id)
+        return currentTarget;
+    if (currentTarget.injury.consciousness - lowestConsc < OPPORTUNISM_GAP)
+        return currentTarget;
+    const seed = eventSeed(world.seed, world.tick, self.id, weakest.id, 0x06670);
+    if ((seed % SCALE.Q) < opportunismQ)
+        return weakest;
+    return currentTarget;
+}

package/dist/src/sim/ai/presets.d.ts

@@ -0,0 +1,2 @@
+import type { AIPolicy } from "./types.js";
+export declare const AI_PRESETS: Record<string, AIPolicy>;

package/dist/src/sim/ai/presets.js

@@ -0,0 +1,28 @@
+import { q } from "../../units.js";
+import { SCALE } from "../../units.js";
+export const AI_PRESETS = {
+    lineInfantry: {
+        archetype: "lineInfantry",
+        desiredRange_m: Math.trunc(0.9 * SCALE.m),
+        engageRange_m: Math.trunc(1.2 * SCALE.m),
+        retreatRange_m: Math.trunc(0.35 * SCALE.m),
+        threatRange_m: Math.trunc(1.6 * SCALE.m),
+        defendWhenThreatenedQ: q(0.35),
+        parryBiasQ: q(0.55),
+        dodgeBiasQ: q(0.10),
+        retargetCooldownTicks: 15,
+        focusStickinessQ: q(0.75),
+    },
+    skirmisher: {
+        archetype: "skirmisher",
+        desiredRange_m: Math.trunc(1.4 * SCALE.m),
+        engageRange_m: Math.trunc(1.6 * SCALE.m),
+        retreatRange_m: Math.trunc(0.50 * SCALE.m),
+        threatRange_m: Math.trunc(1.6 * SCALE.m),
+        defendWhenThreatenedQ: q(0.25),
+        parryBiasQ: q(0.35),
+        dodgeBiasQ: q(0.45),
+        retargetCooldownTicks: 10,
+        focusStickinessQ: q(0.55),
+    },
+};

package/dist/src/sim/ai/system.d.ts

@@ -0,0 +1,6 @@
+import type { WorldState } from "../world.js";
+import type { CommandMap } from "../commands.js";
+import type { WorldIndex } from "../indexing.js";
+import type { SpatialIndex } from "../spatial.js";
+import type { AIPolicy } from "./types.js";
+export declare function buildAICommands(world: WorldState, index: WorldIndex, spatial: SpatialIndex, policyFor: (eId: number) => AIPolicy | undefined): CommandMap;

package/dist/src/sim/ai/system.js

@@ -0,0 +1,13 @@
+import { decideCommandsForEntity } from "./decide.js";
+export function buildAICommands(world, index, spatial, policyFor) {
+    const out = new Map();
+    for (const e of world.entities) {
+        const policy = policyFor(e.id);
+        if (!policy)
+            continue;
+        const cmds = decideCommandsForEntity(world, index, spatial, e, policy);
+        if (cmds.length > 0)
+            out.set(e.id, cmds);
+    }
+    return out;
+}

package/dist/src/sim/ai/targeting.d.ts

@@ -0,0 +1,8 @@
+import type { Entity } from "../entity.js";
+import type { WorldState } from "../world.js";
+import type { WorldIndex } from "../indexing.js";
+import type { SpatialIndex } from "../spatial.js";
+import type { AIPolicy } from "./types.js";
+import { type SensoryEnvironment } from "../sensory.js";
+export declare function pickTarget(world: WorldState, self: Entity, index: WorldIndex, spatial: SpatialIndex, policy: AIPolicy, env?: SensoryEnvironment): Entity | undefined;
+export declare function updateFocus(self: Entity, target: Entity | undefined, policy: AIPolicy): void;

package/dist/src/sim/ai/targeting.js

@@ -0,0 +1,42 @@
+import { perceiveLocal } from "./perception.js";
+import { SCALE, mulDiv } from "../../units.js";
+import { eventSeed } from "../seeds.js";
+import { DEFAULT_PERCEPTION, DEFAULT_SENSORY_ENV } from "../sensory.js";
+export function pickTarget(world, self, index, spatial, policy, env = DEFAULT_SENSORY_ENV) {
+    const ai = self.ai ?? { focusTargetId: 0, retargetCooldownTicks: 0, decisionCooldownTicks: 0 };
+    const focused = ai.focusTargetId !== 0 ? index.byId.get(ai.focusTargetId) : undefined;
+    // keep focus if still valid and cooldown active
+    if (focused && !focused.injury.dead && ai.retargetCooldownTicks > 0)
+        return focused;
+    // Phase 4: use entity's own threat horizon as perception radius
+    // Phase 33: spatial intelligence scales the effective horizon
+    // Formula: base × (0.40 + cognSpatial) — human baseline (0.60) → no change (×1.0)
+    const perc = (self.attributes).perception ?? DEFAULT_PERCEPTION;
+    const cognSpatial = self.attributes.cognition?.spatial ?? 0;
+    const perceptionRadius = cognSpatial
+        ? Math.trunc(mulDiv(perc.threatHorizon_m, (4000 + cognSpatial), SCALE.Q))
+        : perc.threatHorizon_m;
+    const p = perceiveLocal(world, self, index, spatial, perceptionRadius, perc.attentionDepth, env);
+    if (p.enemies.length === 0)
+        return undefined;
+    // Stickiness: prefer keeping previous target if present and alive
+    if (focused && !focused.injury.dead) {
+        const seed = eventSeed(world.seed, world.tick, self.id, ai.focusTargetId, 0xF0C05);
+        const rollQ = (seed % SCALE.Q);
+        if (rollQ < policy.focusStickinessQ)
+            return focused;
+    }
+    // Otherwise choose nearest (already sorted)
+    return p.enemies[0];
+}
+export function updateFocus(self, target, policy) {
+    if (!self.ai)
+        self.ai = { focusTargetId: 0, retargetCooldownTicks: 0, decisionCooldownTicks: 0 };
+    if (!target) {
+        self.ai.focusTargetId = 0;
+        self.ai.retargetCooldownTicks = 0;
+        return;
+    }
+    self.ai.focusTargetId = target.id;
+    self.ai.retargetCooldownTicks = policy.retargetCooldownTicks;
+}

package/dist/src/sim/ai/types.d.ts

@@ -0,0 +1,14 @@
+import type { Q } from "../../units.js";
+export type AIArchetype = "skirmisher" | "lineInfantry" | "berserker" | "defender";
+export interface AIPolicy {
+    archetype: AIArchetype;
+    desiredRange_m: number;
+    engageRange_m: number;
+    retreatRange_m: number;
+    threatRange_m: number;
+    defendWhenThreatenedQ: Q;
+    parryBiasQ: Q;
+    dodgeBiasQ: Q;
+    retargetCooldownTicks: number;
+    focusStickinessQ: Q;
+}

package/dist/src/sim/ai/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,9 @@
+import type { Q } from "../units.js";
+import type { HitArea } from "./combat.js";
+export type BodyRegion = "head" | "torso" | "leftArm" | "rightArm" | "leftLeg" | "rightLeg";
+export declare const ALL_REGIONS: readonly BodyRegion[];
+export type MajorOrgan = "brain" | "lung" | "liver" | "spleen";
+export type BoneRegion = "bone" | "skull" | "femur" | "tibia";
+export declare const DEFAULT_REGION_WEIGHTS: Record<BodyRegion, Q>;
+export declare function regionFromHit(area: HitArea, sideBit: 0 | 1): BodyRegion;
+export declare function weightedMean01(values: Record<BodyRegion, Q>, weights?: Record<BodyRegion, Q>): Q;

package/dist/src/sim/body.js

@@ -0,0 +1,32 @@
+import { q, SCALE } from "../units.js";
+export const ALL_REGIONS = [
+    "head",
+    "torso",
+    "leftArm",
+    "rightArm",
+    "leftLeg",
+    "rightLeg",
+];
+export const DEFAULT_REGION_WEIGHTS = {
+    head: q(0.12),
+    torso: q(0.50),
+    leftArm: q(0.095),
+    rightArm: q(0.095),
+    leftLeg: q(0.095),
+    rightLeg: q(0.095),
+};
+export function regionFromHit(area, sideBit) {
+    if (area === "head")
+        return "head";
+    if (area === "torso")
+        return "torso";
+    if (area === "arm")
+        return sideBit === 0 ? "leftArm" : "rightArm";
+    return sideBit === 0 ? "leftLeg" : "rightLeg";
+}
+export function weightedMean01(values, weights = DEFAULT_REGION_WEIGHTS) {
+    let acc = 0;
+    for (const k of ALL_REGIONS)
+        acc += Math.trunc((values[k] * weights[k]) / SCALE.Q);
+    return acc;
+}

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

@@ -0,0 +1,161 @@
+import type { Q, I32 } from "../units.js";
+import { DamageChannel } from "../channels.js";
+import { SegmentCoverageProfile } from "../anatomy/anatomy-contracts.js";
+export interface LocomotionModel {
+    /** Primary locomotion mechanism. */
+    type: "biped" | "quadruped" | "hexapod" | "undulation" | "flight" | "distributed";
+    /**
+     * Phase 8B: flight capability.  Present only for winged body plans.
+     * Wings are segments; liftCapacity_kg is the total mass the creature can sustain aloft.
+     */
+    flight?: {
+        /** Segment IDs used for lift (must match BodySegment.id values in the same plan). */
+        wingSegments: string[];
+        /** Maximum liftable mass (SCALE.kg units; e.g. 3000 = 3 kg). */
+        liftCapacity_kg: I32;
+        /** Energy cost multiplier relative to ground movement (Q; q(2.0) = double cost). */
+        flightStaminaCost: Q;
+        /** Mobility reduction per unit of average wing structural damage (Q multiplier). */
+        wingDamagePenalty: Q;
+    };
+}
+export interface CNSLayout {
+    /** Whether the nervous system is concentrated or spread through the body. */
+    type: "centralized" | "distributed";
+}
+/**
+ * One functional segment in a body plan.
+ * The `id` is also the key in InjuryState.byRegion.
+ */
+export interface BodySegment {
+    /** Unique within the plan; used as the injury region key. */
+    id: string;
+    /** Parent segment id (for anatomical hierarchy); null for the root segment. */
+    parent: string | null;
+    /** Mass in fixed-point kg units (SCALE.kg = 1000, so 5 kg = 5000). */
+    mass_kg: I32;
+    /**
+     * Hit probability weight per damage channel (Q, 0..SCALE.Q).
+     * Omitted channels fall back to the Kinetic weight.
+     * The kinetic weights should sum to approximately SCALE.Q across all segments.
+     */
+    exposureWeight: Partial<Record<DamageChannel, Q>>;
+    /** Contribution to locomotion capability. */
+    locomotionRole?: "primary" | "secondary" | "none";
+    /** Contribution to manipulation capability. */
+    manipulationRole?: "primary" | "secondary" | "none";
+    /** Central nervous system contribution. */
+    cnsRole?: "central" | "ganglionic" | "none";
+    tags?: string[];
+    /** Structural biology of this segment.  Absent = endoskeleton default. */
+    structureType?: "endoskeleton" | "exoskeleton" | "hydrostatic" | "gelatinous";
+    /**
+     * For exoskeletons: structural damage level (Q) at which the shell is breached.
+     * Below breach: all incoming damage routes to structuralDamage only.
+     * At or above breach: normal surface / internal / structural split applies.
+     */
+    breachThreshold?: Q;
+    /**
+     * Fluid transport system type.
+     * "open" = arthropod hemolymph; "closed" = vertebrate blood; "none" = dry.
+     */
+    fluidSystem?: "closed" | "open" | "none";
+    /**
+     * Hemolymph loss rate (Q) per tick when an open-fluid segment is breached.
+     * Feeds InjuryState.hemolymphLoss (parallel to the vertebrate fluidLoss model).
+     */
+    hemolymphLossRate?: Q;
+    /**
+     * Is this segment a joint (articulation between hardened plates)?
+     * Joints take extra structural damage from kinetic impacts.
+     */
+    isJoint?: boolean;
+    /**
+     * Structural damage multiplier applied to strInc when isJoint = true.
+     * e.g. q(1.5) = joints take 50% more structural damage than adjacent plates.
+     */
+    jointDamageMultiplier?: Q;
+    /**
+     * Can this segment regenerate structural integrity via a molt event?
+     * When true, completing a molt cycle reduces structuralDamage by q(0.10).
+     */
+    regeneratesViaMolting?: boolean;
+    /**
+     * Intrinsic structural armor resist (joules) — energy absorbed by the shell
+     * before damage channels are allocated.  Distinct from worn equipment armour.
+     * Absent or 0 = no intrinsic resistance.
+     */
+    intrinsicArmor_J?: number;
+}
+export type BodySegmentId = BodySegment["id"];
+export interface BodyPlan {
+    id: string;
+    segments: BodySegment[];
+    locomotion: LocomotionModel;
+    cnsLayout: CNSLayout;
+    coverageProfiles?: readonly SegmentCoverageProfile[];
+}
+/**
+ * Get the exposure weight for a segment on a given damage channel.
+ * Falls back to the kinetic weight when the channel is not explicitly specified.
+ */
+export declare function getExposureWeight(seg: BodySegment, channel: DamageChannel): Q;
+/**
+ * Resolve which segment is struck, given a uniform [0, SCALE.Q) random value.
+ * Uses kinetic exposure weights for physical-impact hits.
+ */
+export declare function resolveHitSegment(plan: BodyPlan, r01: Q): BodySegmentId;
+/** Return all segment ids from a body plan. */
+export declare function segmentIds(plan: BodyPlan): readonly string[];
+/**
+ * Standard humanoid (human, elf, robot):
+ * bilateral upright, 4 limbs, centralized CNS.
+ */
+export declare const HUMANOID_PLAN: BodyPlan;
+/**
+ * Quadruped (dog, horse, bear):
+ * 4 locomotion limbs, lower centre of gravity, no dedicated manipulation.
+ */
+export declare const QUADRUPED_PLAN: BodyPlan;
+/**
+ * Theropod (large bipedal predator, fantasy drake):
+ * bipedal, heavy tail counterbalance, vestigial forelimbs.
+ */
+export declare const THEROPOD_PLAN: BodyPlan;
+/**
+ * Sauropod (long neck and tail, 4 locomotion limbs):
+ * brachiosaurus-type, massive torso, slow-moving.
+ */
+export declare const SAUROPOD_PLAN: BodyPlan;
+/**
+ * Avian (bird, winged creature):
+ * hollow bones, wings as forelimbs, legs for perching/walking.
+ */
+export declare const AVIAN_PLAN: BodyPlan;
+/**
+ * Vermiform (snake, worm):
+ * no discrete limbs, lateral undulation locomotion.
+ */
+export declare const VERMIFORM_PLAN: BodyPlan;
+/**
+ * Centaur (combined horse and humanoid upper body):
+ * 4 locomotion limbs + 2 manipulation limbs.
+ */
+export declare const CENTAUR_PLAN: BodyPlan;
+/**
+ * Octopoid (octopus-type):
+ * distributed manipulation, all arms contribute to locomotion.
+ */
+export declare const OCTOPOID_PLAN: BodyPlan;
+/**
+ * Phase 8B reference plan: giant grasshopper (arthropod exoskeleton).
+ * Demonstrates all Phase 8B fields:
+ *  - All segments have structureType: "exoskeleton"
+ *  - Thorax has fluidSystem: "open" + hemolymphLossRate
+ *  - Wings have breachThreshold, isJoint, jointDamageMultiplier
+ *  - Legs have regeneratesViaMolting: true
+ *  - locomotion.flight wired to wing segment IDs
+ *
+ * Kinetic exposure weights sum to exactly 10000 (SCALE.Q).
+ */
+export declare const GRASSHOPPER_PLAN: BodyPlan;