@its-not-rocket-science/ananke 0.1.0

package/dist/src/sim/step/morale.js

@@ -0,0 +1,130 @@
+import { SCALE, q, clampQ, qMul, mulDiv } from "../../units.js";
+import { queryNearbyIds } from "../spatial.js";
+import { coverFractionAtPosition } from "../terrain.js";
+import { TraceKinds } from "../kinds.js";
+import { FEAR_PER_SUPPRESSION_TICK, FEAR_FOR_ALLY_DEATH, FEAR_INJURY_MUL, FEAR_OUTNUMBERED, FEAR_ROUTING_CASCADE, fearDecayPerTick, isRouting, LEADER_AURA_FEAR_REDUCTION, BANNER_AURA_FEAR_REDUCTION, AURA_RADIUS_m, RALLY_COOLDOWN_TICKS, } from "../morale.js";
+/**
+ * Per-entity morale update — accumulates fear from all sources and applies decay.
+ * Emits a MoraleRoute trace event whenever the entity crosses the routing threshold.
+ */
+export function stepMoraleForEntity(world, e, index, spatial, aliveBeforeTick, teamRoutingFrac, trace, ctx) {
+    if (e.injury.dead)
+        return;
+    const distressTolBase = e.attributes.resilience.distressTolerance;
+    // Phase 33: intrapersonal intelligence boosts effective distress tolerance
+    // Formula: base + intrapersonal × q(0.30); human (0.55) → +0.165; clamped to q(0.98)
+    const intrapersonal = e.attributes.cognition?.intrapersonal ?? 0;
+    const distressTol = intrapersonal
+        ? clampQ((distressTolBase + Math.trunc(mulDiv(q(0.30), intrapersonal, SCALE.Q))), q(0.01), q(0.98))
+        : distressTolBase;
+    const MORALE_RADIUS_m = Math.trunc(30 * SCALE.m); // 30 m awareness radius
+    const nearbyIds = queryNearbyIds(spatial, e.position_m, MORALE_RADIUS_m);
+    let nearbyAllyCount = 0;
+    let nearbyEnemyCount = 0;
+    let allyDeathsThisTick = 0;
+    for (const nId of nearbyIds) {
+        if (nId === e.id)
+            continue;
+        const neighbor = index.byId.get(nId);
+        if (!neighbor)
+            continue;
+        if (neighbor.teamId === e.teamId) {
+            if (!neighbor.injury.dead) {
+                nearbyAllyCount++;
+            }
+            else if (aliveBeforeTick.has(nId)) {
+                allyDeathsThisTick++;
+            }
+        }
+        else if (!neighbor.injury.dead) {
+            nearbyEnemyCount++;
+        }
+    }
+    // Feature 6: berserk entities ignore all fear — always clear fear and return early
+    const fearResponse = (e.attributes.resilience).fearResponse ?? "flight";
+    if (fearResponse === "berserk") {
+        e.condition.fearQ = q(0);
+        return;
+    }
+    let fearQ = e.condition.fearQ;
+    const wasRouting = isRouting(fearQ, distressTol);
+    // 1. Suppression ticks add fear per tick — scaled by caliber multiplier (Feature 1)
+    if (e.condition.suppressedTicks > 0) {
+        const supMul = e.condition.suppressionFearMul ?? SCALE.Q;
+        fearQ = clampQ(fearQ + qMul(FEAR_PER_SUPPRESSION_TICK, supMul), 0, SCALE.Q);
+    }
+    // 2. Ally deaths this tick — with diminishing returns (Feature 2)
+    if (allyDeathsThisTick > 0) {
+        // Reset window if last death was >100 ticks ago (5s at TICK_HZ=20)
+        if (world.tick - e.condition.lastAllyDeathTick > 100) {
+            e.condition.recentAllyDeaths = 0;
+        }
+        // Multiplier: q(1.0) for first death, -q(0.15) per prior, floor q(0.40)
+        const mul = Math.max(q(0.40), q(1.0) - Math.trunc(e.condition.recentAllyDeaths * 1500));
+        fearQ = clampQ(fearQ + Math.trunc(allyDeathsThisTick * qMul(FEAR_FOR_ALLY_DEATH, mul)), 0, SCALE.Q);
+        e.condition.recentAllyDeaths += allyDeathsThisTick;
+        e.condition.lastAllyDeathTick = world.tick;
+    }
+    // 3. Self-injury (shock accumulation) adds fear per tick
+    fearQ = clampQ(fearQ + qMul(e.injury.shock, FEAR_INJURY_MUL), 0, SCALE.Q);
+    // 4. Being outnumbered by visible enemies adds fear per tick
+    // Include self in friendly count: entity + its allies vs enemies.
+    if (nearbyEnemyCount > nearbyAllyCount + 1) {
+        fearQ = clampQ(fearQ + FEAR_OUTNUMBERED, 0, SCALE.Q);
+    }
+    // 5. Routing cascade: more than half the team is already routing
+    if ((teamRoutingFrac.get(e.teamId) ?? 0) > 0.50) {
+        fearQ = clampQ(fearQ + FEAR_ROUTING_CASCADE, 0, SCALE.Q);
+    }
+    // Fear decay — faster with high tolerance and nearby allies (cohesion)
+    fearQ = clampQ(fearQ - fearDecayPerTick(distressTol, nearbyAllyCount), 0, SCALE.Q);
+    // Feature 3: leader and standard-bearer aura decay
+    // Phase 33: interpersonal intelligence scales effective aura reception radius
+    // Formula: base × (0.40 + interpersonal); human (0.60) → ×1.0
+    const interpersonal = e.attributes.cognition?.interpersonal ?? 0;
+    const effectiveAuraRadius_m = interpersonal
+        ? Math.trunc(mulDiv(AURA_RADIUS_m, (4000 + interpersonal), SCALE.Q))
+        : AURA_RADIUS_m;
+    let leaderCount = 0;
+    let bannerCount = 0;
+    const auraIds = queryNearbyIds(spatial, e.position_m, effectiveAuraRadius_m);
+    for (const aId of auraIds) {
+        if (aId === e.id)
+            continue;
+        const ally = index.byId.get(aId);
+        if (!ally || ally.injury.dead || ally.teamId !== e.teamId)
+            continue;
+        const traits = ally.traits ?? [];
+        if (traits.includes("leader"))
+            leaderCount++;
+        if (traits.includes("standardBearer"))
+            bannerCount++;
+    }
+    if (leaderCount > 0) {
+        fearQ = clampQ(fearQ - leaderCount * LEADER_AURA_FEAR_REDUCTION, 0, SCALE.Q);
+    }
+    if (bannerCount > 0) {
+        fearQ = clampQ(fearQ - bannerCount * BANNER_AURA_FEAR_REDUCTION, 0, SCALE.Q);
+    }
+    // Phase 6: cover provides a psychological safety bonus
+    const moraleCellSize = ctx.cellSize_m ?? Math.trunc(4 * SCALE.m);
+    const coverForMorale = ctx.obstacleGrid
+        ? coverFractionAtPosition(ctx.obstacleGrid, moraleCellSize, e.position_m.x, e.position_m.y)
+        : 0;
+    if (coverForMorale > q(0.5)) {
+        fearQ = clampQ(fearQ - q(0.01), 0, SCALE.Q);
+    }
+    // Feature 5: rally — detect routing → normal transition and set cooldown
+    const nowRouting = isRouting(fearQ, distressTol);
+    if (wasRouting && !nowRouting) {
+        e.condition.rallyCooldownTicks = RALLY_COOLDOWN_TICKS;
+    }
+    e.condition.fearQ = fearQ;
+    // Emit trace when routing state crosses threshold
+    if (!wasRouting && nowRouting) {
+        trace.onEvent({ kind: TraceKinds.MoraleRoute, tick: world.tick, entityId: e.id, fearQ });
+    }
+    else if (wasRouting && !nowRouting) {
+        trace.onEvent({ kind: TraceKinds.MoraleRally, tick: world.tick, entityId: e.id, fearQ }); // Phase 18
+    }
+}

package/dist/src/sim/step/movement.d.ts

@@ -0,0 +1,5 @@
+import type { Entity } from "../entity.js";
+import type { WorldState } from "../world.js";
+import type { KernelContext } from "../context.js";
+import type { SimulationTuning } from "../tuning.js";
+export declare function stepMovement(e: Entity, world: WorldState, ctx: KernelContext, tuning: SimulationTuning): void;

package/dist/src/sim/step/movement.js

@@ -0,0 +1,172 @@
+import { eventSeed } from "../seeds.js";
+import { DT_S } from "../tick.js";
+import { SCALE, clampQ, q, qMul, mulDiv } from "../../units.js";
+import { clampSpeed, scaleDirToSpeed, clampI32 } from "../kernel.js";
+import { v3, normaliseDirCheapQ, integratePos } from "../vec3.js";
+import { coverFractionAtPosition, slopeAtPosition, tractionAtPosition, speedMulAtPosition, } from "../terrain.js";
+import { deriveMovementCaps } from "../../derive.js";
+import { deriveFunctionalState } from "../impairment.js";
+import { findExoskeleton } from "../../equipment.js";
+export function stepMovement(e, world, ctx, tuning) {
+    const cellSize = ctx.cellSize_m ?? Math.trunc(4 * SCALE.m);
+    const traction = tractionAtPosition(ctx.terrainGrid, cellSize, e.position_m.x, e.position_m.y, ctx.tractionCoeff);
+    const caps = deriveMovementCaps(e.attributes, e.loadout, { tractionCoeff: traction });
+    const func = deriveFunctionalState(e, tuning);
+    // Capability gating
+    if (!func.canAct) {
+        // unconscious/otherwise incapable: no voluntary movement
+        e.intent.move = { dir: { x: 0, y: 0, z: 0 }, intensity: q(0), mode: "walk" };
+    }
+    if (!func.canStand) {
+        // force prone if unable to stand (tactical/sim)
+        if (tuning.realism !== "arcade")
+            e.condition.prone = true;
+    }
+    if (e.condition.unconsciousTicks > 0) {
+        e.velocity_mps = v3(0, 0, 0);
+        return;
+    }
+    const vmax_mps = caps.maxSprintSpeed_mps;
+    const amax_mps2 = caps.maxAcceleration_mps2;
+    const controlMulBase = clampQ(q(1.0) - qMul(q(0.7), e.condition.stunned), q(0.1), q(1.0));
+    let mobilityMulBase = e.condition.prone ? q(0.25) : q(1.0);
+    // crawl tuning
+    if (e.condition.prone && e.condition.unconsciousTicks === 0 && tuning.realism !== "arcade") {
+        mobilityMulBase = qMul(mobilityMulBase, q(0.20)); // crawling is slow
+    }
+    // impairment affects control and mobility
+    const controlMul = qMul(controlMulBase, func.coordinationMul);
+    const mobilityMul = qMul(mobilityMulBase, func.mobilityMul);
+    const crowd = ctx.density?.crowdingQ.get(e.id) ?? 0;
+    const crowdMul = clampQ(q(1.0) - qMul(q(0.65), crowd), q(0.25), q(1.0));
+    const terrainSpeedMul = speedMulAtPosition(ctx.terrainGrid, cellSize, e.position_m.x, e.position_m.y);
+    // Phase 6: slope direction adjusts effective speed.
+    // uphill: −25% per grade unit, clamped [50%,95%]; downhill: +10% per grade unit, clamped [100%,120%].
+    const slope = slopeAtPosition(ctx.slopeGrid, cellSize, e.position_m.x, e.position_m.y);
+    const slopeMul = slope
+        ? slope.type === "uphill"
+            ? clampQ((SCALE.Q - qMul(slope.grade, q(0.25))), q(0.50), q(0.95))
+            : clampQ((SCALE.Q + qMul(slope.grade, q(0.10))), q(1.0), q(1.20))
+        : SCALE.Q;
+    // Phase 11: powered exoskeleton speed boost
+    const exo = findExoskeleton(e.loadout);
+    const exoSpeedMul = exo ? exo.speedMultiplier : SCALE.Q;
+    // Phase 8B: flight locomotion — boost sprint speed when entity can achieve flight
+    let flightSpeedMul = SCALE.Q;
+    const flightSpec = e.bodyPlan?.locomotion.flight;
+    if (flightSpec) {
+        const mass = e.attributes.morphology.mass_kg;
+        if (mass <= flightSpec.liftCapacity_kg) {
+            // Compute average wing damage
+            let wingDmgSum = 0;
+            let wingCount = 0;
+            for (const wid of flightSpec.wingSegments) {
+                const ws = e.injury.byRegion[wid];
+                if (ws) {
+                    wingDmgSum += ws.structuralDamage;
+                    wingCount++;
+                }
+            }
+            const avgWingDmg = wingCount > 0 ? Math.trunc(wingDmgSum / wingCount) : q(0);
+            const flightMul = clampQ((SCALE.Q - qMul(avgWingDmg, flightSpec.wingDamagePenalty)), q(0), q(1.0));
+            // 1.5× flight speed boost, scaled by wing condition
+            flightSpeedMul = qMul(q(1.50), flightMul);
+        }
+    }
+    // Phase 32A: locomotion mode modifiers
+    // Validate requested mode against entity's declared locomotion capacities.
+    const requestedMode = e.intent.locomotionMode;
+    const locomotionModes = e.attributes.locomotionModes;
+    const activeCapacity = requestedMode && locomotionModes
+        ? locomotionModes.find(c => c.mode === requestedMode)
+        : undefined;
+    // aquatic depth check: entity without swim capacity and below ground (z < 0) cannot act
+    const isSubmerged = e.position_m.z < 0;
+    const canSwim = locomotionModes?.some(c => c.mode === "swim") ?? false;
+    if (isSubmerged && !canSwim) {
+        e.velocity_mps = v3(0, 0, 0);
+        return;
+    }
+    // Locomotion mode speed multipliers
+    let locomotionSpeedMul = SCALE.Q;
+    let skipTraction = false;
+    if (activeCapacity) {
+        switch (activeCapacity.mode) {
+            case "flight":
+                // Flight: bypass ground traction; apply cruiseAlt proportional controller
+                skipTraction = true;
+                if (activeCapacity.cruiseAlt_m !== undefined) {
+                    const targetZ = activeCapacity.cruiseAlt_m;
+                    const dz = targetZ - e.position_m.z;
+                    const dzStep = clampI32(Math.trunc(dz), -Math.trunc(2 * SCALE.m), Math.trunc(2 * SCALE.m));
+                    e.position_m = { ...e.position_m, z: e.position_m.z + dzStep };
+                }
+                // Cap at declared maxSpeed
+                if (activeCapacity.maxSpeed_mps < vmax_mps) {
+                    locomotionSpeedMul = mulDiv(activeCapacity.maxSpeed_mps, SCALE.Q, vmax_mps);
+                }
+                break;
+            case "swim":
+                // Hydrodynamic drag: ~40% of surface sprint speed
+                locomotionSpeedMul = q(0.40);
+                skipTraction = true;
+                break;
+            case "climb":
+                locomotionSpeedMul = q(0.30);
+                break;
+            default:
+                break;
+        }
+    }
+    // If skipping traction, override the traction-derived speed caps
+    const effTrackMul = skipTraction ? SCALE.Q : SCALE.Q; // traction already applied above via caps
+    const baseMul = qMul(qMul(qMul(qMul(qMul(qMul(qMul(controlMul, mobilityMul), crowdMul), skipTraction ? SCALE.Q : terrainSpeedMul), slopeMul), exoSpeedMul), flightSpeedMul), locomotionSpeedMul);
+    void effTrackMul;
+    const effVmax = mulDiv(vmax_mps, baseMul, SCALE.Q);
+    const effAmax = mulDiv(amax_mps2, baseMul, SCALE.Q);
+    let modeMul = e.intent.move.mode === "walk" ? q(0.40) :
+        e.intent.move.mode === "run" ? q(0.70) : q(1.0);
+    if (e.condition.prone && tuning.realism !== "arcade") {
+        // cannot sprint while prone
+        if (e.intent.move.mode === "sprint")
+            modeMul = q(0.40);
+    }
+    const dir = normaliseDirCheapQ(e.intent.move.dir);
+    const intensity = clampQ(e.intent.move.intensity, 0, SCALE.Q);
+    // Sim-only: stumble/fall risk when sprinting with impaired mobility/coordination
+    if (tuning.realism === "sim" && intensity > 0 && e.intent.move.mode === "sprint" && !e.condition.prone) {
+        const instability = (SCALE.Q - qMul(func.mobilityMul, func.coordinationMul));
+        const chance = clampQ(tuning.stumbleBaseChance + qMul(instability, q(0.05)), q(0), q(0.25));
+        if (chance > 0) {
+            const seed = eventSeed(world.seed, world.tick, e.id, 0, 0xF411);
+            const roll = (seed % SCALE.Q);
+            if (roll < chance) {
+                e.condition.prone = true;
+                // a small deterministic shock spike
+                e.injury.shock = clampQ(e.injury.shock + q(0.02), 0, SCALE.Q);
+            }
+        }
+    }
+    const vTargetMag = mulDiv(mulDiv(effVmax, intensity, SCALE.Q), modeMul, SCALE.Q);
+    const targetVel = scaleDirToSpeed(dir, vTargetMag);
+    e.velocity_mps = accelToward(e.velocity_mps, targetVel, effAmax);
+    e.velocity_mps = clampSpeed(e.velocity_mps, effVmax);
+    // Phase 6: obstacle blocking — impassable cells (coverFraction = q(1.0)) prevent entry.
+    const nextPos = integratePos(e.position_m, e.velocity_mps, DT_S);
+    if (ctx.obstacleGrid) {
+        const cov = coverFractionAtPosition(ctx.obstacleGrid, cellSize, nextPos.x, nextPos.y);
+        if (cov >= SCALE.Q) {
+            e.velocity_mps = v3(0, 0, 0);
+            return;
+        }
+    }
+    e.position_m = nextPos;
+}
+function accelToward(v, target, amax_mps2) {
+    const maxDv = Math.trunc((amax_mps2 * DT_S) / SCALE.s);
+    return {
+        x: v.x + clampI32(target.x - v.x, -maxDv, maxDv),
+        y: v.y + clampI32(target.y - v.y, -maxDv, maxDv),
+        z: v.z + clampI32(target.z - v.z, -maxDv, maxDv),
+    };
+}

package/dist/src/sim/step/push.d.ts

@@ -0,0 +1,11 @@
+import type { WorldState } from "../world.js";
+import type { SpatialIndex } from "../spatial.js";
+import type { WorldIndex } from "../indexing.js";
+import type { Q } from "../../units.js";
+export interface PushTuning {
+    personalRadius_m: number;
+    repelAccel_mps2: number;
+    pushTransfer: Q;
+    maxNeighbours: number;
+}
+export declare function stepPushAndRepulsion(world: WorldState, index: WorldIndex, spatial: SpatialIndex, tuning: PushTuning): void;

package/dist/src/sim/step/push.js

@@ -0,0 +1,79 @@
+import { queryNearbyIds } from "../spatial.js";
+import { SCALE, clampQ } from "../../units.js";
+export function stepPushAndRepulsion(world, index, spatial, tuning) {
+    const R = tuning.personalRadius_m;
+    const R2 = BigInt(R) * BigInt(R);
+    // 1) collect all candidate pairs (order-independent)
+    const pairs = [];
+    // Deterministic: world.entities already sorted by id in stepWorld
+    for (const e of world.entities) {
+        if (e.injury.dead)
+            continue;
+        const ids = queryNearbyIds(spatial, e.position_m, R, tuning.maxNeighbours);
+        ids.sort((x, y) => x - y);
+        for (const id of ids) {
+            if (id === e.id)
+                continue;
+            const a = Math.min(e.id, id);
+            const b = Math.max(e.id, id);
+            pairs.push({ a, b });
+        }
+    }
+    // 2) de-dupe pairs deterministically
+    pairs.sort((p, q) => (p.a - q.a) || (p.b - q.b));
+    const uniq = [];
+    for (const p of pairs) {
+        const last = uniq[uniq.length - 1];
+        if (!last || last.a !== p.a || last.b !== p.b)
+            uniq.push(p);
+    }
+    // 3) compute dv per pair, accumulate into dv map (NO entity mutation here)
+    const dv = new Map();
+    for (const { a, b } of uniq) {
+        const A = index.byId.get(a);
+        const B = index.byId.get(b);
+        if (!A || !B)
+            continue;
+        if (A.injury.dead || B.injury.dead)
+            continue;
+        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;
+        const d2 = BigInt(dx) * BigInt(dx) + BigInt(dy) * BigInt(dy) + BigInt(dz) * BigInt(dz);
+        if (d2 >= R2 || d2 === 0n)
+            continue;
+        // repel along x/y only
+        const d = approxDist(dx, dy);
+        const overlap = Math.max(0, R - d);
+        if (overlap <= 0)
+            continue;
+        const strengthQ = clampQ(Math.trunc((overlap * SCALE.Q) / R), 0, SCALE.Q);
+        const ax = Math.trunc((dx * tuning.repelAccel_mps2 * strengthQ) / (Math.max(1, d) * SCALE.Q));
+        const ay = Math.trunc((dy * tuning.repelAccel_mps2 * strengthQ) / (Math.max(1, d) * SCALE.Q));
+        // equal + opposite dv
+        addDv(dv, A.id, -ax, -ay, 0);
+        addDv(dv, B.id, ax, ay, 0);
+    }
+    // 4) apply dv in stable order (world.entities is stable-sorted)
+    for (const e of world.entities) {
+        const d = dv.get(e.id);
+        if (!d)
+            continue;
+        e.velocity_mps.x += d.x;
+        e.velocity_mps.y += d.y;
+        e.velocity_mps.z += d.z;
+    }
+}
+function addDv(dv, id, dx, dy, dz) {
+    const cur = dv.get(id) ?? { x: 0, y: 0, z: 0 };
+    cur.x += dx;
+    cur.y += dy;
+    cur.z += dz;
+    dv.set(id, cur);
+}
+// cheap approx: max + 0.5*min
+function approxDist(dx, dy) {
+    const adx = dx < 0 ? -dx : dx;
+    const ady = dy < 0 ? -dy : dy;
+    return adx > ady ? adx + (ady >> 1) : ady + (adx >> 1);
+}

package/dist/src/sim/step/substances.d.ts

@@ -0,0 +1,3 @@
+import type { Entity } from "../entity.js";
+import { type Q } from "../../units.js";
+export declare function stepSubstances(e: Entity, ambientTemperature_Q?: Q): void;

package/dist/src/sim/step/substances.js

@@ -0,0 +1,75 @@
+import { q, clampQ, qMul, mulDiv, SCALE } from "../../units.js";
+import { hasSubstanceType } from "../substance.js";
+export function stepSubstances(e, ambientTemperature_Q) {
+    if (!e.substances || e.substances.length === 0)
+        return;
+    for (const active of e.substances) {
+        const sub = active.substance;
+        // Absorption: pendingDose → concentration
+        const absorbed = qMul(active.pendingDose, sub.absorptionRate);
+        active.pendingDose = clampQ(active.pendingDose - absorbed, q(0), q(1.0));
+        active.concentration = clampQ(active.concentration + absorbed, q(0), q(1.0));
+        // Elimination — base rate, then modifiers
+        let effectiveElimRate = sub.eliminationRate;
+        // Phase 10C: substance interactions — modify elimination rate
+        if (sub.effectType === "haemostatic" && hasSubstanceType(e, "stimulant")) {
+            // Stimulant-induced vasoconstriction antagonises haemostatic absorption: clears 30% faster
+            effectiveElimRate = qMul(effectiveElimRate, q(1.30));
+        }
+        if (sub.effectType === "anaesthetic" && hasSubstanceType(e, "stimulant")) {
+            // Stimulant partially counteracts anaesthetic: clears 25% faster
+            effectiveElimRate = qMul(effectiveElimRate, q(1.25));
+        }
+        if (sub.effectType === "haemostatic" && hasSubstanceType(e, "poison")) {
+            // Haemostatic partially counteracts poison-induced bleeding: clears 20% slower
+            effectiveElimRate = qMul(effectiveElimRate, q(0.80));
+        }
+        // Phase 10C: temperature-dependent metabolism — cold slows hepatic clearance
+        if (ambientTemperature_Q !== undefined && ambientTemperature_Q < q(0.35)) {
+            const coldFrac = Math.max(q(0.50), mulDiv(ambientTemperature_Q, SCALE.Q, q(0.35)));
+            effectiveElimRate = qMul(effectiveElimRate, coldFrac);
+        }
+        const eliminated = qMul(active.concentration, effectiveElimRate);
+        active.concentration = clampQ(active.concentration - eliminated, q(0), q(1.0));
+        // Effects — only when above threshold
+        if (active.concentration <= sub.effectThreshold)
+            continue;
+        const delta = clampQ(active.concentration - sub.effectThreshold, q(0), q(1.0));
+        // Phase 10C: anaesthetic onset/strength is reduced when a stimulant is active
+        let effectStrengthMod = sub.effectStrength;
+        if (sub.effectType === "anaesthetic" && hasSubstanceType(e, "stimulant")) {
+            effectStrengthMod = qMul(effectStrengthMod, q(0.75));
+        }
+        const effectDose = qMul(delta, effectStrengthMod);
+        switch (sub.effectType) {
+            case "stimulant":
+                // Reduces fear and slows fatigue accumulation
+                e.condition.fearQ = clampQ((e.condition.fearQ ?? 0) - qMul(effectDose, q(0.005)), q(0), q(1.0));
+                e.energy.fatigue = clampQ(e.energy.fatigue - qMul(effectDose, q(0.003)), q(0), q(1.0));
+                break;
+            case "anaesthetic":
+                // Erodes consciousness
+                e.injury.consciousness = clampQ(e.injury.consciousness - qMul(effectDose, q(0.008)), q(0), q(1.0));
+                break;
+            case "poison": {
+                // Internal damage to torso (or first region)
+                const torsoReg = e.injury.byRegion["torso"] ?? Object.values(e.injury.byRegion)[0];
+                if (torsoReg) {
+                    torsoReg.internalDamage = clampQ(torsoReg.internalDamage + qMul(effectDose, q(0.002)), q(0), q(1.0));
+                }
+                e.injury.shock = clampQ(e.injury.shock + qMul(effectDose, q(0.001)), 0, SCALE.Q);
+                break;
+            }
+            case "haemostatic":
+                // Reduces bleeding rate across all regions
+                for (const reg of Object.values(e.injury.byRegion)) {
+                    if (reg.bleedingRate > 0) {
+                        reg.bleedingRate = clampQ(reg.bleedingRate - qMul(effectDose, q(0.003)), q(0), q(1.0));
+                    }
+                }
+                break;
+        }
+    }
+    // Remove exhausted substances (keep only those with meaningful dose or concentration)
+    e.substances = e.substances.filter(a => a.pendingDose > 1 || a.concentration > 1);
+}

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

@@ -0,0 +1,38 @@
+import type { Q } from "../units.js";
+import type { Entity } from "./entity.js";
+export type SubstanceEffectType = "stimulant" | "anaesthetic" | "poison" | "haemostatic";
+export interface Substance {
+    id: string;
+    name: string;
+    /** Fraction of pendingDose absorbed into concentration per tick (0..1 Q). */
+    absorptionRate: Q;
+    /** Fraction of current concentration cleared per tick (0..1 Q). */
+    eliminationRate: Q;
+    /** Minimum concentration for effects to activate (0..1 Q). */
+    effectThreshold: Q;
+    /** Nature of biological effect. */
+    effectType: SubstanceEffectType;
+    /**
+     * Strength multiplier applied to the above-threshold concentration delta.
+     * A value of q(1.0) produces the standard effect magnitude.
+     */
+    effectStrength: Q;
+}
+/**
+ * An active dose of a substance present in an entity's system.
+ * Add to `entity.substances` when a substance is ingested or injected.
+ */
+export interface ActiveSubstance {
+    substance: Substance;
+    /** Remaining unabsorbed dose (Q 0..1); decreases each tick as absorption occurs. */
+    pendingDose: Q;
+    /** Current systemic concentration (Q 0..1); rises with absorption, falls with elimination. */
+    concentration: Q;
+}
+/**
+ * Phase 10C: returns true if the entity has an active substance of the given type
+ * with concentration above its effectThreshold.
+ */
+export declare function hasSubstanceType(e: Entity, type: SubstanceEffectType): boolean;
+/** Ready-made substance catalogue for common game scenarios. */
+export declare const STARTER_SUBSTANCES: Record<string, Substance>;

package/dist/src/sim/substance.js

@@ -0,0 +1,57 @@
+// src/sim/substance.ts — Phase 10: pharmacokinetics model
+//
+// One-compartment model:
+//   d[concentration]/dt = absorptionRate × pendingDose − eliminationRate × concentration
+//
+// Effects activate when concentration exceeds effectThreshold.
+// The engine consumes substance definitions; the host application manages which
+// substances an entity has ingested/injected (by populating entity.substances).
+import { q } from "../units.js";
+/**
+ * Phase 10C: returns true if the entity has an active substance of the given type
+ * with concentration above its effectThreshold.
+ */
+export function hasSubstanceType(e, type) {
+    if (!e.substances)
+        return false;
+    return e.substances.some(a => a.substance.effectType === type && a.concentration > a.substance.effectThreshold);
+}
+/** Ready-made substance catalogue for common game scenarios. */
+export const STARTER_SUBSTANCES = {
+    stimulant: {
+        id: "stimulant",
+        name: "Combat Stimulant",
+        absorptionRate: q(0.15), // 15%/tick — fast-acting injection
+        eliminationRate: q(0.02), // 2%/tick  — clears in ~50 ticks (2.5 s)
+        effectThreshold: q(0.10),
+        effectType: "stimulant",
+        effectStrength: q(0.80),
+    },
+    anaesthetic: {
+        id: "anaesthetic",
+        name: "Anaesthetic",
+        absorptionRate: q(0.08), // slower onset
+        eliminationRate: q(0.008), // slow clearance — lasts many ticks
+        effectThreshold: q(0.05),
+        effectType: "anaesthetic",
+        effectStrength: q(1.00),
+    },
+    poison: {
+        id: "poison",
+        name: "Contact Poison",
+        absorptionRate: q(0.06), // slow skin absorption
+        eliminationRate: q(0.004), // very slow clearance
+        effectThreshold: q(0.05),
+        effectType: "poison",
+        effectStrength: q(0.80),
+    },
+    haemostatic: {
+        id: "haemostatic",
+        name: "Haemostatic Agent",
+        absorptionRate: q(0.20), // rapid absorption (injected/applied)
+        eliminationRate: q(0.03), // clears in ~33 ticks (1.6 s)
+        effectThreshold: q(0.10),
+        effectType: "haemostatic",
+        effectStrength: q(0.60),
+    },
+};