@its-not-rocket-science/ananke 0.1.0

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

@@ -0,0 +1,251 @@
+import type { IndividualAttributes, EnergyState, PersonalityTraits } from "../types.js";
+import type { WillpowerState } from "../competence/willpower.js";
+import type { Loadout } from "../equipment.js";
+import type { TraitId } from "../traits.js";
+import type { SpeciesPhysiology } from "../species.js";
+import type { Vec3 } from "./vec3.js";
+import type { ConditionState } from "./condition.js";
+import type { InjuryState } from "./injury.js";
+import type { IntentState, AIState } from "./intent.js";
+import type { ActionState } from "./action.js";
+import type { SkillMap } from "./skills.js";
+import type { BodyPlan } from "./bodyplan.js";
+import type { ActiveSubstance } from "./substance.js";
+import type { CapabilitySource, PendingActivation } from "./capability.js";
+import type { ActiveVenom } from "./toxicology.js";
+import type { LimbState } from "./limb.js";
+import type { ExtendedSenses } from "./sensory-extended.js";
+import type { ActiveIngestedToxin, CumulativeExposureRecord, WithdrawalState } from "./systemic-toxicology.js";
+import type { TraumaState } from "./wound-aging.js";
+import type { DiseaseState, ImmunityRecord } from "./disease.js";
+import type { AgeState } from "./aging.js";
+import type { SleepState } from "./sleep.js";
+import type { MountState } from "./mount.js";
+/** Phase 12B: state for an active concentration aura (castTime_ticks = -1 effect). */
+export interface ConcentrationState {
+    sourceId: string;
+    effectId: string;
+    targetId?: number;
+}
+import { Q } from "../units.js";
+import { CompiledAnatomyModel } from "../anatomy/anatomy-contracts.js";
+import { AnatomyHelperRegistry } from "../anatomy/anatomy-helpers.js";
+export type GrapplePosition = "standing" | "prone" | "pinned";
+export interface GrappleState {
+    holdingTargetId: number;
+    heldByIds: number[];
+    gripQ: Q;
+    position: GrapplePosition;
+}
+/**
+ * Core entity shape.
+ *
+ * Fields are annotated with one of three stability tiers:
+ *
+ * - **`@core`** — Required by `stepWorld` on every tick.  Always present; never optional.
+ *   Removing or renaming any `@core` field is a Tier 1 breaking change.
+ *
+ * - **`@subsystem(name)`** — Optional state consumed only by a specific sub-module
+ *   (`src/sim/sleep.ts`, `src/sim/aging.ts`, etc.).  Omitting a subsystem field disables that
+ *   module's behaviour for this entity; the kernel continues to run correctly without it.
+ *   Adding new optional subsystem fields is never a breaking change.
+ *
+ * - **`@extension`** — Not consumed by Ananke at all.  Reserved for host-application data
+ *   that travels alongside entities (e.g. renderer-side metadata, network session IDs).
+ *   Currently no built-in fields carry this tag; hosts may add their own `?` fields freely.
+ */
+export interface Entity {
+    /** @core Unique entity identifier — must be stable across ticks. */
+    id: number;
+    /** @core Combat team / allegiance used by attack resolution and AI targeting. */
+    teamId: number;
+    /** @core Physical and cognitive capabilities (mass, force, reaction time, etc.). */
+    attributes: IndividualAttributes;
+    /** @core Energy reserve and fatigue accumulator — drained by movement and combat. */
+    energy: EnergyState;
+    /**
+     * @subsystem(willpower) Cognitive stamina reserve — depleted by sustained concentration,
+     * replenished by rest.  Consumed by `src/competence/willpower.ts`.
+     */
+    willpower?: WillpowerState;
+    /** @core Equipped items: weapons, armour, held objects. */
+    loadout: Loadout;
+    /** @core Permanent trait flags that modify combat and skill outcomes. */
+    traits: TraitId[];
+    /**
+     * @subsystem(skills) Per-skill proficiency map.
+     * Consumed by skill-contest resolution in `src/sim/combat.ts` and `src/sim/ai/`.
+     */
+    skills?: SkillMap;
+    /**
+     * @subsystem(anatomy) Body plan defining injury segments, mass distribution, and
+     * data-driven impairment tables.  Consumed by `src/sim/injury.ts`, `src/model3d.ts`,
+     * and the anatomy compiler.
+     */
+    bodyPlan?: BodyPlan;
+    /**
+     * @subsystem(pharmacology) Active pharmacological substances currently in the bloodstream.
+     * Consumed by `src/sim/substance.ts`.
+     */
+    substances?: ActiveSubstance[];
+    /**
+     * @subsystem(nutrition) Consumable food items and counts.
+     * Consumed by the nutrition accumulator in `src/sim/kernel.ts` when present.
+     */
+    foodInventory?: Map<string, number> | undefined;
+    /**
+     * @subsystem(anatomy) Molting state for arthropod-type entities.
+     * Active molt: segments in `softeningSegments` take reduced kinetic structural damage.
+     * When `ticksRemaining` reaches 0, `regeneratesViaMolting` segments receive partial repair.
+     * Consumed by `src/sim/injury.ts`.
+     */
+    molting?: {
+        active: boolean;
+        ticksRemaining: number;
+        /** Segment IDs currently softening — take reduced kinetic structural damage (×q(0.70)). */
+        softeningSegments: string[];
+    };
+    /** @core World-space position in fixed-point metres (`SCALE.m` = 1 m). */
+    position_m: Vec3;
+    /** @core Velocity in fixed-point metres per second (`SCALE.mps` = 1 m/s). */
+    velocity_mps: Vec3;
+    /** @core Movement and defence intent derived from the previous tick's commands. */
+    intent: IntentState;
+    /** @core Attack cooldowns, swing momentum, weapon-bind state. */
+    action: ActionState;
+    /** @core Physiological condition: fear, morale, sensory modifiers, fatigue, thermal. */
+    condition: ConditionState;
+    /** @core Per-region damage, shock, consciousness, fluid loss, death flag. */
+    injury: InjuryState;
+    /** @core Active grapple relationships, grip strength, positional lock. */
+    grapple: GrappleState;
+    /**
+     * @subsystem(ai) AI decision state (target selection, last-seen position, threat map).
+     * Consumed by `src/sim/ai/system.ts`; absent for player-controlled or scripted entities.
+     */
+    ai?: AIState;
+    /**
+     * @subsystem(capability) Attached capability sources (mana pools, fusion cells, divine
+     * reserves).  Consumed by `src/sim/capability.ts`.
+     */
+    capabilitySources?: CapabilitySource[];
+    /**
+     * @subsystem(armour) Mutable resist state for ablative armour items.
+     * Key = item id; value = remaining resist in joules.
+     * Initialised automatically by `stepWorld` for entities with ablative items.
+     */
+    armourState?: Map<string, {
+        resistRemaining_J: number;
+    }>;
+    /**
+     * @subsystem(capability) In-flight capability activation — cleared on completion or
+     * concentration break.  Consumed by `src/sim/capability.ts`.
+     */
+    pendingActivation?: PendingActivation;
+    /**
+     * @subsystem(capability) Active concentration aura — cleared when willpower reserve
+     * depletes or shock interrupts.  Consumed by `src/sim/capability.ts`.
+     */
+    activeConcentration?: ConcentrationState;
+    /**
+     * @subsystem(faction) Faction membership identifier.
+     * Consumed by `src/faction.ts` and AI targeting.
+     */
+    faction?: string;
+    /**
+     * @subsystem(party) Adventuring party membership identifier.
+     * Consumed by `src/party.ts` for morale and formation bonuses.
+     */
+    party?: string | undefined;
+    /**
+     * @subsystem(faction) Entity-level faction-standing overrides.
+     * Map<factionId, Q> — takes priority over faction-default standings when set.
+     * Consumed by `src/faction.ts`.
+     */
+    reputations?: Map<string, number>;
+    /**
+     * @subsystem(thermoregulation) Species-level physiological overrides.
+     * Consumed by `src/sim/thermoregulation.ts` for heat/cold stress modelling.
+     */
+    physiology?: SpeciesPhysiology | undefined;
+    /**
+     * @subsystem(toxicology) Active venom/toxin injections — ticked at 1 Hz.
+     * Consumed by `src/sim/toxicology.ts`.
+     */
+    activeVenoms?: ActiveVenom[];
+    /**
+     * @subsystem(anatomy) Per-limb state for multi-limb entities (octopoids, arachnids).
+     * Consumed by `src/sim/limb.ts`.
+     */
+    limbStates?: LimbState[];
+    /**
+     * @subsystem(ai) Individual AI personality traits (aggression, caution, loyalty).
+     * Consumed by `src/sim/ai/personality.ts`.
+     */
+    personality?: PersonalityTraits;
+    /**
+     * @subsystem(sensory) Extended sensory modalities (echolocation, electroreception,
+     * olfaction).  Consumed by `src/sim/sensory-extended.ts`.
+     */
+    extendedSenses?: ExtendedSenses;
+    /**
+     * @subsystem(toxicology) Active ingested toxins (alcohol, sedatives, alkaloids, heavy
+     * metals, radiation).  Consumed by `src/sim/systemic-toxicology.ts`.
+     */
+    activeIngestedToxins?: ActiveIngestedToxin[];
+    /**
+     * @subsystem(toxicology) Cumulative lifetime dose records for heavy metals and radiation.
+     * Consumed by `src/sim/systemic-toxicology.ts`.
+     */
+    cumulativeExposure?: CumulativeExposureRecord[];
+    /**
+     * @subsystem(toxicology) Active withdrawal states from addictive toxin removal.
+     * Consumed by `src/sim/systemic-toxicology.ts`.
+     */
+    withdrawal?: WithdrawalState[];
+    /**
+     * @subsystem(wound-aging) PTSD-like trauma state accumulated from severe shock events.
+     * Reduces effective fear threshold via `deriveFearThresholdMul`.
+     * Consumed by `src/sim/wound-aging.ts`.
+     */
+    traumaState?: TraumaState;
+    /**
+     * @subsystem(disease) Active systemic disease states (incubating or symptomatic).
+     * Consumed by `src/sim/disease.ts`.
+     */
+    activeDiseases?: DiseaseState[];
+    /**
+     * @subsystem(disease) Post-recovery immunity records preventing re-infection.
+     * Consumed by `src/sim/disease.ts`.
+     */
+    immunity?: ImmunityRecord[];
+    /**
+     * @subsystem(aging) Elapsed life-seconds for aging calculations.
+     * Consumed by `src/sim/aging.ts`.
+     */
+    age?: AgeState;
+    /**
+     * @subsystem(sleep) Sleep-phase state, debt accumulator, and continuous wake time.
+     * Consumed by `src/sim/sleep.ts`.
+     */
+    sleep?: SleepState;
+    /**
+     * @subsystem(mount) Rider/mount pair state for cavalry and mounted combat.
+     * Consumed by `src/sim/mount.ts`.
+     */
+    mount?: MountState;
+    /**
+     * @subsystem(anatomy) Compiled anatomy model — cached on first access by
+     * `ensureAnatomyRuntime`.  Do not set manually.
+     */
+    compiledAnatomy?: CompiledAnatomyModel;
+    /**
+     * @subsystem(anatomy) Anatomy helper registry — cached on first access by
+     * `ensureAnatomyRuntime`.  Do not set manually.
+     */
+    anatomyHelpers?: AnatomyHelperRegistry;
+}
+export declare function ensureAnatomyRuntime(e: Entity): {
+    model?: CompiledAnatomyModel;
+    helpers?: AnatomyHelperRegistry;
+};

package/dist/src/sim/entity.js

@@ -0,0 +1,19 @@
+import { createAnatomyHelpers } from "../anatomy/anatomy-helpers.js";
+import { compileAnatomyDefinition } from "../anatomy/anatomy-compiler.js";
+export function ensureAnatomyRuntime(e) {
+    if (!e.bodyPlan)
+        return {};
+    if (!e.compiledAnatomy) {
+        const compiled = compileAnatomyDefinition(e.bodyPlan);
+        if (!compiled.ok)
+            return {};
+        e.compiledAnatomy = compiled.model;
+    }
+    if (!e.anatomyHelpers) {
+        e.anatomyHelpers = createAnatomyHelpers(e.compiledAnatomy);
+    }
+    return {
+        model: e.compiledAnatomy,
+        helpers: e.anatomyHelpers,
+    };
+}

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

@@ -0,0 +1,25 @@
+import type { Weapon } from "../equipment.js";
+import type { Q } from "../units.js";
+export interface ImpactEvent {
+    kind: "impact";
+    attackerId: number;
+    targetId: number;
+    /** Segment id of the struck region (BodyRegion string for humanoid; arbitrary string for other body plans). */
+    region: string;
+    energy_J: number;
+    protectedByArmour: boolean;
+    blocked: boolean;
+    parried: boolean;
+    weaponId: string;
+    wpn: Weapon;
+    hitQuality: Q;
+    shieldBlocked: boolean;
+    /** Phase 26: effective striking mass (weapon head + body fraction, or projectile mass) in SCALE.kg units. */
+    massEff_kg?: number;
+    /** Phase 27: projectile velocity at impact point (pre-armour, post-drag) in SCALE.mps units. */
+    v_impact_mps?: number;
+}
+export declare function sortEventsDeterministic<T extends {
+    attackerId: number;
+    targetId: number;
+}>(ev: T[]): void;

package/dist/src/sim/events.js

@@ -0,0 +1,5 @@
+export function sortEventsDeterministic(ev) {
+    ev.sort((a, b) => a.attackerId !== b.attackerId ? a.attackerId - b.attackerId :
+        a.targetId !== b.targetId ? a.targetId - b.targetId :
+            0);
+}

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

@@ -0,0 +1,40 @@
+import type { I32, Q } from "../units.js";
+/**
+ * Point-source explosion specification.
+ *
+ * `fragmentCount` is the expected number of fragment hits on an average
+ * body-sized target at the blast epicentre (dist = 0).  At distance d it
+ * scales quadratically with the same falloff as blast energy.  Set it to
+ * reflect how many fragments realistically hit a human-sized target up close,
+ * not the total count of fragments ejected (which would be spread over a sphere).
+ */
+export interface BlastSpec {
+    /** Peak blast energy at epicentre (J; SCALE.J = 1 so this is SI joules directly). */
+    blastEnergy_J: number;
+    /** Effective blast radius (SCALE.m fixed-point). */
+    radius_m: I32;
+    /** Expected fragment hits on a body-sized target at the epicentre (dist = 0). */
+    fragmentCount: number;
+    /** Mass of each fragment (SCALE.kg fixed-point; e.g. to.kg(0.005) = 5 for 5 g). */
+    fragmentMass_kg: I32;
+    /** Fragment ejection speed (m/s raw integer; e.g. 300 for a typical grenade). */
+    fragmentVelocity_mps: number;
+}
+/**
+ * Blast energy fraction (Q) delivered to a target at squared fixed-point
+ * distance `distSq_m2` from the epicentre.
+ * Quadratic falloff: frac = max(0, 1 − dist²/radius²).
+ * Returns 0 when distSq_m2 ≥ radius_m².
+ */
+export declare function blastEnergyFracQ(spec: BlastSpec, distSq_m2: number): Q;
+/**
+ * Expected number of fragment hits on a target at squared distance `distSq_m2`.
+ * May be fractional; caller should round stochastically with a seed roll for
+ * the fractional part.
+ */
+export declare function fragmentsExpected(spec: BlastSpec, distSq_m2: number): number;
+/**
+ * Kinetic energy (J) of a single fragment at squared distance `distSq_m2`.
+ * KE = 0.5 × mass × velocity²; attenuated by the quadratic falloff.
+ */
+export declare function fragmentKineticEnergy(spec: BlastSpec, distSq_m2: number): number;

package/dist/src/sim/explosion.js

@@ -0,0 +1,40 @@
+// src/sim/explosion.ts — Phase 10: blast and fragmentation physics
+import { SCALE, q, mulDiv } from "../units.js";
+/**
+ * Blast energy fraction (Q) delivered to a target at squared fixed-point
+ * distance `distSq_m2` from the epicentre.
+ * Quadratic falloff: frac = max(0, 1 − dist²/radius²).
+ * Returns 0 when distSq_m2 ≥ radius_m².
+ */
+export function blastEnergyFracQ(spec, distSq_m2) {
+    const radiusSq = spec.radius_m * spec.radius_m;
+    if (distSq_m2 >= radiusSq)
+        return q(0);
+    return mulDiv(radiusSq - distSq_m2, SCALE.Q, radiusSq);
+}
+/**
+ * Expected number of fragment hits on a target at squared distance `distSq_m2`.
+ * May be fractional; caller should round stochastically with a seed roll for
+ * the fractional part.
+ */
+export function fragmentsExpected(spec, distSq_m2) {
+    const fracQ = blastEnergyFracQ(spec, distSq_m2);
+    if (fracQ <= 0)
+        return 0;
+    return spec.fragmentCount * fracQ / SCALE.Q;
+}
+/**
+ * Kinetic energy (J) of a single fragment at squared distance `distSq_m2`.
+ * KE = 0.5 × mass × velocity²; attenuated by the quadratic falloff.
+ */
+export function fragmentKineticEnergy(spec, distSq_m2) {
+    const fracQ = blastEnergyFracQ(spec, distSq_m2);
+    if (fracQ <= 0)
+        return 0;
+    // KE_base = mass_kg_real × vel² / 2
+    // = (fragmentMass_kg / SCALE.kg) × fragmentVelocity_mps² / 2
+    // = fragmentMass_kg × velocity² / (2 × SCALE.kg)
+    const keBase = Math.trunc((spec.fragmentMass_kg * spec.fragmentVelocity_mps * spec.fragmentVelocity_mps) /
+        (2 * SCALE.kg));
+    return mulDiv(keBase, fracQ, SCALE.Q);
+}

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

@@ -0,0 +1,138 @@
+/**
+ * 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 { type Q } from "../../src/units.js";
+export type FormationShape = "line" | "shield_wall" | "wedge" | "column";
+export interface FormationUnit {
+    id: string;
+    name: string;
+    shape: FormationShape;
+    entityIds: number[];
+}
+export interface RankSplit {
+    /** Entity IDs nearest the enemy (most-forward projection). */
+    frontRank: number[];
+    /** Entity IDs behind the front rank. */
+    rearRank: number[];
+}
+export interface FormationMomentum {
+    /**
+     * Total formation momentum in (SCALE.kg × m/s) units.
+     * Divide by SCALE.kg (= 1000) to obtain physical kg·m/s.
+     */
+    momentum_Skg_mps: number;
+    /** Number of entities that contributed (speed > 0). */
+    entityCount: number;
+}
+export interface FormationCohesionState {
+    /** True when intact fraction ≥ FORMATION_INTACT_THRESHOLD. */
+    intact: boolean;
+    /** Fraction of entities still alive and not routed, as a Q value. */
+    intactFrac_Q: Q;
+    /** Per-tick fear decay bonus when formation is intact. */
+    moraleBonus_Q: Q;
+    /** Per-tick fear increment when formation integrity has collapsed. */
+    moralePenalty_Q: Q;
+}
+/**
+ * Efficiency of shield coverage sharing between adjacent bearers.
+ * Each additional bearer beyond the first contributes at this fraction.
+ */
+export declare const SHIELD_SHARING_FRAC: Q;
+/** Hard cap on combined shield wall coverage. */
+export declare const SHIELD_WALL_MAX_COVERAGE: Q;
+/** Default rank depth used to split front/rear ranks (2 m in SCALE.m). */
+export declare const RANK_DEPTH_DEFAULT_m: number;
+/**
+ * Minimum intact fraction for a formation to be considered cohesive.
+ * Below this threshold the rout-contagion penalty applies instead of the
+ * morale bonus.
+ */
+export declare const FORMATION_INTACT_THRESHOLD: Q;
+/** Fear decay bonus per tick granted to entities in an intact formation. */
+export declare const FORMATION_MORALE_BONUS: Q;
+/** Fear increment per tick when formation integrity has collapsed. */
+export declare const FORMATION_MORALE_PENALTY: Q;
+/** Per-tick fear decay granted per alive formation ally (vs q(0.002) unaffiliated). */
+export declare const FORMATION_ALLY_FEAR_DECAY: Q;
+/** Maximum number of formation allies counted for the fear decay bonus. */
+export declare const FORMATION_ALLY_DECAY_CAP = 8;
+/**
+ * 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 declare function computeShieldWallCoverage(coverageFracs: readonly Q[]): Q;
+/**
+ * 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 declare function deriveRankSplit(entityIds: readonly number[], positions: ReadonlyMap<number, {
+    x: number;
+    y: number;
+}>, facingDirQ: {
+    x: number;
+    y: number;
+}, rankDepth_m?: number): RankSplit;
+/**
+ * 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 declare function stepFormationCasualtyFill(rankSplit: RankSplit, deadIds: ReadonlySet<number>): RankSplit;
+/**
+ * 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 declare function computeFormationMomentum(masses_Skg: readonly number[], speeds_Smps: readonly number[]): FormationMomentum;
+/**
+ * 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 declare function deriveFormationCohesion(entityIds: readonly number[], deadOrRoutedIds: ReadonlySet<number>): FormationCohesionState;
+/**
+ * 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 declare function deriveFormationAllyFearDecay(aliveFormationAllyCount: number): Q;