@its-not-rocket-science/ananke 0.1.0

package/dist/src/sim/grapple.js

@@ -0,0 +1,480 @@
+/**
+ * Phase 2A: Grapple resolution — deterministic close-combat control.
+ *
+ * Design rules:
+ *  - All randomness via eventSeed() + salt, never Math.random()
+ *  - Pair-based ordering: idLo = Math.min(a, b), idHi = Math.max(a, b)
+ *  - No mutation of entities mid-resolution across independent pairs
+ *  - All physical quantities in SI fixed-point (SCALE.*)
+ */
+import { SCALE, q, qMul, clampQ, mulDiv, to } from "../units.js";
+import { getSkill } from "./skills.js";
+import { eventSeed } from "./seeds.js";
+import { deriveFunctionalState } from "./impairment.js";
+import { TraceKinds } from "./kinds.js";
+import { effectiveLimbForceMul } from "./limb.js";
+import { TICK_HZ } from "./tick.js";
+// ---------- Deterministic salts ----------
+const SALT_ATTEMPT = 0x4A41B1;
+const SALT_BREAK = 0xB4EA44;
+const SALT_THROW = 0xF177C0;
+const SALT_JOINTLOCK = 0x6B1D44;
+// ---------- Reference values (human baseline for normalisation) ----------
+const REF_FORCE = to.N(1840); // 184_000 fixed-point units
+const REF_MASS = to.kg(75); //  75_000 fixed-point units
+const REF_H = to.m(1.75); //  17_500 fixed-point units
+// ---------- Grip decay per tick ----------
+// 0.5% per tick → released after ~200 ticks (10 s) without maintenance
+export const GRIP_DECAY_PER_TICK = 50; // = q(0.005)
+// ============================================================
+//  Physics-derived cost helpers
+// ============================================================
+/**
+ * Effective grapple reach for an entity (m, fixed-point).
+ * Derived from stature × reachScale — arm-span is approximately equal
+ * to body height, scaled by individual proportions.
+ * Clamped to [1.0 m, 3.0 m].
+ */
+function grappleReach_m(e) {
+    const reach = mulDiv(e.attributes.morphology.stature_m, e.attributes.morphology.reachScale, SCALE.Q);
+    return Math.max(to.m(1.0), Math.min(to.m(3.0), reach));
+}
+/**
+ * Energy cost (J) of a single grapple/break attempt.
+ * Modelled as ~70 ms burst at peak power:
+ *   cost ≈ peakPower_W × 0.07 s
+ * Calibration: 1200 W peak → 84 J ≈ 80 J reference.
+ * Minimum 20 J to avoid zero cost on very weak entities.
+ */
+function attemptCost_J(e) {
+    return Math.max(20, mulDiv(e.attributes.performance.peakPower_W, 7, 100));
+}
+/**
+ * Energy cost (J) of a throw attempt.
+ * ~100 ms burst at peak power: cost ≈ peakPower_W × 0.10 s
+ * Calibration: 1200 W → 120 J reference. Minimum 40 J.
+ */
+function throwCost_J(e) {
+    return Math.max(40, mulDiv(e.attributes.performance.peakPower_W, 10, 100));
+}
+/**
+ * Energy cost (J) of a joint-lock application.
+ * ~50 ms burst at peak power: cost ≈ peakPower_W × 0.05 s
+ * Calibration: 1200 W → 60 J reference. Minimum 20 J.
+ */
+function lockCost_J(e) {
+    return Math.max(20, mulDiv(e.attributes.performance.peakPower_W, 5, 100));
+}
+/**
+ * Energy cost (J) per tick of maintaining a grapple hold.
+ * Modelled as isometric hold work at continuous aerobic power:
+ *   cost = continuousPower_W / TICK_HZ
+ * Calibration: 200 W / 20 Hz = 10 J/tick reference. Minimum 5 J.
+ */
+function tickCost_J(e) {
+    return Math.max(5, Math.trunc(e.attributes.performance.continuousPower_W / TICK_HZ));
+}
+/**
+ * Leverage differential threshold above which an immediate trip occurs on a
+ * successful grapple attempt.
+ *
+ * Higher (harder to trip) when the target is:
+ *   - heavier relative to the attacker
+ *   - more stable (higher stability coefficient)
+ *
+ * Formula: base 0.20 + 0.30 × (massRatio × targetStability)
+ * Clamped to [0.10, 0.70].
+ *
+ * Average vs average: ≈ 0.20 + 0.30 × (1.0 × 0.70) = 0.41
+ * Light/unstable target: ≈ 0.10 (easier to trip)
+ * Heavy/stable target: ≈ 0.60–0.70 (hard to trip immediately)
+ */
+function tripThreshold(attacker, target) {
+    const massRatioQ = clampQ(mulDiv(target.attributes.morphology.mass_kg, SCALE.Q, Math.max(1, attacker.attributes.morphology.mass_kg)), q(0.20), q(2.0));
+    const stability = target.attributes.control.stability;
+    return clampQ(q(0.20) + qMul(q(0.30), qMul(massRatioQ, stability)), q(0.10), q(0.70));
+}
+// ---------- Synthetic Weapon objects for grapple impacts ----------
+// These are used only as damage-profile carriers; they never appear in a Loadout.
+export const GRAPPLE_THROW_WPN = {
+    id: "__grapple_throw__",
+    name: "Grapple Throw",
+    mass_kg: 0,
+    bulk: q(0),
+    kind: "weapon",
+    damage: {
+        surfaceFrac: q(0.05),
+        internalFrac: q(0.35),
+        structuralFrac: q(0.60),
+        bleedFactor: q(0.10),
+        penetrationBias: q(0.0),
+    },
+};
+export const GRAPPLE_JOINTLOCK_WPN = {
+    id: "__grapple_jointlock__",
+    name: "Joint Lock",
+    mass_kg: 0,
+    bulk: q(0),
+    kind: "weapon",
+    damage: {
+        surfaceFrac: q(0.02),
+        internalFrac: q(0.20),
+        structuralFrac: q(0.78),
+        bleedFactor: q(0.05),
+        penetrationBias: q(0.0),
+    },
+};
+// ============================================================
+//  Score computation
+// ============================================================
+/**
+ * Compute an entity's grapple contest score in Q [0.05, 0.95].
+ *
+ * Combines:
+ *   50% peak force (normalised to human baseline)
+ *   30% technique  (controlQuality × stability)
+ *   20% body mass  (normalised to human baseline)
+ *
+ * The result is modulated by the entity's current functional state
+ * (injury, fatigue) via manipulationMul.
+ *
+ * A healthy average human scores ≈ q(0.47).
+ */
+export function grappleContestScore(e, func) {
+    const f = e.attributes.performance.peakForce_N;
+    const m = e.attributes.morphology.mass_kg;
+    const ctrl = e.attributes.control.controlQuality;
+    const stab = e.attributes.control.stability;
+    // Normalise to Q (q(1.0) = human baseline)
+    const forceQ = clampQ(mulDiv(f, SCALE.Q, REF_FORCE), q(0.10), q(2.50));
+    const massQ = clampQ(mulDiv(m, SCALE.Q, REF_MASS), q(0.20), q(2.50));
+    const tech = qMul(ctrl, stab);
+    // Weighted sum — result is Q-scaled
+    const raw = mulDiv(forceQ, 5, 10) +
+        mulDiv(tech, 3, 10) +
+        mulDiv(massQ, 2, 10);
+    // Apply functional impairment; clamp to [q(0.02), q(1.80)]
+    const impaired = clampQ(qMul(raw, func.manipulationMul), q(0.02), q(1.80));
+    // Phase 7: grappling.energyTransferMul applies a leverage bonus to the contest score
+    const grapSkill = getSkill(e.skills, "grappling");
+    const adjusted = clampQ(qMul(impaired, grapSkill.energyTransferMul), q(0.02), q(1.80));
+    // Linear map [q(0.02), q(1.80)] → [q(0.05), q(0.95)]
+    const range = q(1.80) - q(0.02); // 17 800
+    return clampQ(q(0.05) + mulDiv(Math.max(0, adjusted - q(0.02)), q(0.90), range), q(0.05), q(0.95));
+}
+// ============================================================
+//  Internal helpers
+// ============================================================
+/**
+ * Signed leverage differential (Q) for throw/trip outcome.
+ * Positive = attacker has the advantage.
+ * Based on F × stature × 0.35 (approximate effective arm in standing grapple).
+ */
+function leverageDiff(attacker, target, funcA, funcB) {
+    const fA = attacker.attributes.performance.peakForce_N;
+    const fB = target.attributes.performance.peakForce_N;
+    const hA = attacker.attributes.morphology.stature_m;
+    const hB = target.attributes.morphology.stature_m;
+    // Raw leverage ∝ F × h × 0.35 (keep BigInt-safe via mulDiv)
+    const levA = mulDiv(mulDiv(fA, hA, SCALE.m), 35, 100);
+    const levB = mulDiv(mulDiv(fB, hB, SCALE.m), 35, 100);
+    const refLev = mulDiv(mulDiv(REF_FORCE, REF_H, SCALE.m), 35, 100);
+    // Normalise and apply functional multipliers
+    const sA = clampQ(qMul(clampQ(mulDiv(levA, SCALE.Q, refLev), q(0.10), q(2.0)), funcA.manipulationMul), q(0.05), q(2.0));
+    const sB = clampQ(qMul(clampQ(mulDiv(levB, SCALE.Q, refLev), q(0.10), q(2.0)), funcB.manipulationMul), q(0.05), q(2.0));
+    return clampQ((sA - sB), q(-0.90), q(0.90));
+}
+function pushImpact(impacts, attackerId, targetId, region, energy_J, wpn, hitQuality) {
+    if (energy_J <= 0)
+        return;
+    impacts.push({
+        kind: "impact",
+        attackerId,
+        targetId,
+        region,
+        energy_J,
+        protectedByArmour: false,
+        blocked: false,
+        parried: false,
+        shieldBlocked: false,
+        hitQuality,
+        weaponId: wpn.id,
+        wpn,
+    });
+}
+// ============================================================
+//  Public API
+// ============================================================
+/**
+ * Attempt to initiate a grapple on the target.
+ *
+ * Contest: scoreA × intensity vs scoreB. Success probability centred at 0.50
+ * with ±40% swing per unit score difference (mirrors melee hit formula).
+ *
+ * On success:
+ *   - Attacker's grapple.holdingTargetId and gripQ are set
+ *   - Target's grapple.heldByIds is updated (sorted, deduplicated)
+ *   - Overwhelming leverage differential causes immediate trip (prone + small impact)
+ *
+ * On failure: grappleCooldownTicks set, energy still drained.
+ */
+export function resolveGrappleAttempt(world, attacker, target, intensity, tuning, impacts, trace) {
+    if (attacker.action.grappleCooldownTicks > 0)
+        return;
+    // Reach check
+    const dx = target.position_m.x - attacker.position_m.x;
+    const dy = target.position_m.y - attacker.position_m.y;
+    const dz = target.position_m.z - attacker.position_m.z;
+    const dist2 = BigInt(dx) * BigInt(dx) + BigInt(dy) * BigInt(dy) + BigInt(dz) * BigInt(dz);
+    const reach = grappleReach_m(attacker);
+    if (dist2 > BigInt(reach) * BigInt(reach))
+        return;
+    const funcA = deriveFunctionalState(attacker, tuning);
+    const funcB = deriveFunctionalState(target, tuning);
+    if (!funcA.canAct)
+        return;
+    const clampedIntensity = clampQ(intensity, q(0.1), q(1.0));
+    // Phase 32B: reduce contest score by active limb fraction (severed limbs excluded)
+    const limbMul = attacker.limbStates
+        ? effectiveLimbForceMul(attacker.limbStates, attacker.injury)
+        : q(1.0);
+    const scoreA = clampQ(qMul(qMul(grappleContestScore(attacker, funcA), clampedIntensity), limbMul), q(0.05), q(0.95));
+    const scoreB = grappleContestScore(target, funcB);
+    const diff = (scoreA - scoreB);
+    const p = clampQ(q(0.50) + mulDiv(diff, q(0.40), SCALE.Q), q(0.05), q(0.95));
+    const seed = eventSeed(world.seed, world.tick, attacker.id, target.id, SALT_ATTEMPT);
+    const success = (seed % SCALE.Q) < p;
+    // Energy drain regardless of outcome
+    attacker.energy.reserveEnergy_J = Math.max(0, attacker.energy.reserveEnergy_J - attemptCost_J(attacker));
+    if (!success) {
+        attacker.action.grappleCooldownTicks = tuning.realism === "arcade" ? 2 : 4;
+        trace.onEvent({
+            kind: TraceKinds.Grapple,
+            tick: world.tick, attackerId: attacker.id, targetId: target.id,
+            phase: "break", strengthQ: 0,
+        });
+        return;
+    }
+    // Grip quality: higher when score differential is larger
+    const gripQ = clampQ(q(0.20) + mulDiv(Math.max(0, diff), q(0.60), SCALE.Q), q(0.10), q(0.90));
+    attacker.grapple.holdingTargetId = target.id;
+    attacker.grapple.gripQ = gripQ;
+    attacker.grapple.position = "standing";
+    // Add to target's heldByIds (sorted, no duplicates)
+    if (!target.grapple.heldByIds.includes(attacker.id)) {
+        target.grapple.heldByIds.push(attacker.id);
+        target.grapple.heldByIds.sort((a, b) => a - b);
+    }
+    // Overwhelming leverage → immediate trip in tactical/sim
+    if (tuning.realism !== "arcade") {
+        const levDiff = leverageDiff(attacker, target, funcA, funcB);
+        if (levDiff > tripThreshold(attacker, target)) {
+            target.condition.prone = true;
+            attacker.grapple.position = "prone";
+            // Small kinetic impact from the trip (~1 J/kg of target)
+            const tripEnergy_J = mulDiv(target.attributes.morphology.mass_kg, 1, SCALE.kg);
+            pushImpact(impacts, attacker.id, target.id, "torso", tripEnergy_J, GRAPPLE_THROW_WPN, q(0.50));
+        }
+    }
+    trace.onEvent({
+        kind: TraceKinds.Grapple,
+        tick: world.tick, attackerId: attacker.id, targetId: target.id,
+        phase: "start", strengthQ: gripQ,
+    });
+}
+/**
+ * Attempt to throw or trip the grappled target.
+ *
+ * Requires: attacker already holds the target (holdingTargetId === target.id).
+ * Success probability based on signed leverage differential.
+ *
+ * On success: target goes prone, kinetic impact queued, grapple released.
+ * On failure: cooldown set, energy still drained.
+ *
+ * Impact energy ∝ target mass × leverage advantage × intensity (see formula in code).
+ */
+export function resolveGrappleThrow(world, attacker, target, intensity, tuning, impacts, trace) {
+    if (attacker.grapple.holdingTargetId !== target.id)
+        return;
+    if (attacker.action.grappleCooldownTicks > 0)
+        return;
+    const funcA = deriveFunctionalState(attacker, tuning);
+    const funcB = deriveFunctionalState(target, tuning);
+    if (!funcA.canAct)
+        return;
+    // Probability centred at 30% base; leverage advantage pushes toward 90%
+    const levDiff = leverageDiff(attacker, target, funcA, funcB);
+    const levAdv = clampQ((levDiff + q(0.90)), q(0.20), q(1.80));
+    const p = clampQ(q(0.30) + mulDiv(levAdv, q(0.35), q(1.80)), q(0.05), q(0.90));
+    const seed = eventSeed(world.seed, world.tick, attacker.id, target.id, SALT_THROW);
+    const success = (seed % SCALE.Q) < p;
+    attacker.energy.reserveEnergy_J = Math.max(0, attacker.energy.reserveEnergy_J - throwCost_J(attacker));
+    attacker.action.grappleCooldownTicks = tuning.realism === "arcade" ? 4 : 6;
+    if (!success) {
+        trace.onEvent({
+            kind: TraceKinds.Grapple,
+            tick: world.tick, attackerId: attacker.id, targetId: target.id,
+            phase: "tick", strengthQ: attacker.grapple.gripQ,
+        });
+        return;
+    }
+    target.condition.prone = true;
+    attacker.grapple.position = "prone";
+    // throwEnergy = targetMass_kg × 2 × levAdv × intensity
+    // mulDiv(mB, 2, SCALE.kg) converts fixed-point kg → 2×kg (Joules at ~1 m/s effective)
+    const mB = target.attributes.morphology.mass_kg;
+    const throwEnergy_J = mulDiv(mulDiv(mB, 2, SCALE.kg), qMul(levAdv, clampQ(intensity, q(0.1), q(1.0))), SCALE.Q);
+    pushImpact(impacts, attacker.id, target.id, "torso", throwEnergy_J, GRAPPLE_THROW_WPN, q(0.70));
+    releaseGrapple(attacker, target);
+    trace.onEvent({
+        kind: TraceKinds.Grapple,
+        tick: world.tick, attackerId: attacker.id, targetId: target.id,
+        phase: "break", strengthQ: 0,
+    });
+}
+/**
+ * Apply a choke hold: accumulates suffocation on the target.
+ *
+ * Requires position !== "standing" in tactical/sim (must be on the ground).
+ * Sufficient grip quality (> 0.60) transitions the position to "pinned" and
+ * sets target.condition.pinned.
+ */
+export function resolveGrappleChoke(attacker, target, intensity, tuning) {
+    if (attacker.grapple.holdingTargetId !== target.id)
+        return;
+    if (attacker.grapple.position === "standing" && tuning.realism !== "arcade")
+        return;
+    const funcA = deriveFunctionalState(attacker, tuning);
+    if (!funcA.canAct)
+        return;
+    // Choke dose = grip × intensity × technique; builds suffocation at fixed rate
+    const CHOKE_RATE = q(0.008);
+    const dose = qMul(qMul(attacker.grapple.gripQ, clampQ(intensity, q(0.1), q(1.0))), funcA.manipulationMul);
+    target.condition.suffocation = clampQ(target.condition.suffocation + qMul(dose, CHOKE_RATE), 0, SCALE.Q);
+    // Strong grip → advance to pinned
+    if (attacker.grapple.gripQ > q(0.60)) {
+        attacker.grapple.position = "pinned";
+        target.condition.pinned = true;
+    }
+}
+/**
+ * Apply a joint-lock: structural damage to a target limb.
+ *
+ * Requires position !== "standing" in tactical/sim.
+ * Target limb selected deterministically (stable across seeds).
+ *
+ * Impact energy = peakForce × 0.05 m effective displacement × grip × intensity.
+ */
+export function resolveGrappleJointLock(world, attacker, target, intensity, tuning, impacts) {
+    if (attacker.grapple.holdingTargetId !== target.id)
+        return;
+    if (attacker.grapple.position === "standing" && tuning.realism !== "arcade")
+        return;
+    const funcA = deriveFunctionalState(attacker, tuning);
+    if (!funcA.canAct)
+        return;
+    attacker.energy.reserveEnergy_J = Math.max(0, attacker.energy.reserveEnergy_J - lockCost_J(attacker));
+    // Energy: (F / SCALE.N) × 0.05 m × grip × intensity
+    // mulDiv(f, 5, SCALE.N * 100) = f_N × 0.05 in J (SCALE.N=100; 5/100 = 0.05/SCALE.N→J)
+    const f = attacker.attributes.performance.peakForce_N;
+    const gripEffect = qMul(qMul(attacker.grapple.gripQ, clampQ(intensity, q(0.1), q(1.0))), funcA.manipulationMul);
+    const lockEnergy_J = mulDiv(mulDiv(f, 5, SCALE.N * 100), gripEffect, SCALE.Q);
+    if (lockEnergy_J <= 0)
+        return;
+    // Deterministic region: 0=leftArm, 1=rightArm, 2=leftLeg, 3=rightLeg
+    const seed = eventSeed(world.seed, world.tick, attacker.id, target.id, SALT_JOINTLOCK);
+    const regionBit = seed & 3;
+    const region = regionBit === 0 ? "leftArm" :
+        regionBit === 1 ? "rightArm" :
+            regionBit === 2 ? "leftLeg" : "rightLeg";
+    pushImpact(impacts, attacker.id, target.id, region, lockEnergy_J, GRAPPLE_JOINTLOCK_WPN, q(0.80));
+}
+/**
+ * Attempt to break free from all current holders.
+ *
+ * Pair-based: each holder gets an independent contest (lower id owns the seed).
+ * On success: releaseGrapple() called for that holder.
+ * Energy drained per holder attempt regardless of outcome.
+ */
+export function resolveBreakGrapple(world, breaker, intensity, tuning, index, trace) {
+    if (breaker.grapple.heldByIds.length === 0)
+        return;
+    const funcB = deriveFunctionalState(breaker, tuning);
+    const toRelease = [];
+    for (const holderId of breaker.grapple.heldByIds) {
+        const holder = index.byId.get(holderId);
+        // Auto-release stale links
+        if (!holder || holder.injury.dead || holder.grapple.holdingTargetId !== breaker.id) {
+            toRelease.push(holderId);
+            continue;
+        }
+        const funcA = deriveFunctionalState(holder, tuning);
+        const scoreBreaker = clampQ(qMul(grappleContestScore(breaker, funcB), clampQ(intensity, q(0.1), q(1.0))), q(0.05), q(0.95));
+        const scoreHolder = clampQ(qMul(grappleContestScore(holder, funcA), holder.grapple.gripQ), q(0.05), q(0.95));
+        const diff = (scoreBreaker - scoreHolder);
+        const p = clampQ(q(0.40) + mulDiv(diff, q(0.40), SCALE.Q), q(0.05), q(0.90));
+        // Stable pair seed: lower id first
+        const idLo = Math.min(breaker.id, holderId);
+        const idHi = Math.max(breaker.id, holderId);
+        const seed = eventSeed(world.seed, world.tick, idLo, idHi, SALT_BREAK);
+        const success = (seed % SCALE.Q) < p;
+        breaker.energy.reserveEnergy_J = Math.max(0, breaker.energy.reserveEnergy_J - attemptCost_J(breaker));
+        if (success) {
+            toRelease.push(holderId);
+            trace.onEvent({
+                kind: TraceKinds.Grapple,
+                tick: world.tick, attackerId: holderId, targetId: breaker.id,
+                phase: "break", strengthQ: 0,
+            });
+        }
+    }
+    for (const holderId of toRelease) {
+        const holder = index.byId.get(holderId);
+        if (holder) {
+            releaseGrapple(holder, breaker);
+        }
+        else {
+            breaker.grapple.heldByIds = breaker.grapple.heldByIds.filter(id => id !== holderId);
+        }
+    }
+    if (breaker.grapple.heldByIds.length === 0) {
+        breaker.condition.pinned = false;
+    }
+}
+/**
+ * Per-tick maintenance for active grapples.
+ * Call once per entity per tick (regardless of whether a grapple command was issued).
+ *
+ *  - Drains stamina from the holder
+ *  - Decays gripQ by GRIP_DECAY_PER_TICK
+ *  - Releases grapple when grip reaches 0 or target is dead/missing
+ */
+export function stepGrappleTick(world, entity, index) {
+    if (!entity.grapple || entity.grapple.holdingTargetId === 0)
+        return;
+    const target = index.byId.get(entity.grapple.holdingTargetId);
+    if (!target || target.injury.dead) {
+        releaseGrapple(entity, target ?? null);
+        return;
+    }
+    entity.energy.reserveEnergy_J = Math.max(0, entity.energy.reserveEnergy_J - tickCost_J(entity));
+    entity.grapple.gripQ = clampQ(entity.grapple.gripQ - GRIP_DECAY_PER_TICK, 0, SCALE.Q);
+    if (entity.grapple.gripQ <= 0) {
+        releaseGrapple(entity, target);
+    }
+}
+/**
+ * Release a grapple link, updating both the holder and (optionally) the target.
+ * Safe to call with a null target (e.g. when target entity was already removed).
+ */
+export function releaseGrapple(holder, target) {
+    holder.grapple.holdingTargetId = 0;
+    holder.grapple.gripQ = q(0);
+    holder.grapple.position = "standing";
+    if (target) {
+        target.grapple.heldByIds = target.grapple.heldByIds.filter(id => id !== holder.id);
+        if (target.grapple.heldByIds.length === 0) {
+            target.condition.pinned = false;
+        }
+    }
+}

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

@@ -0,0 +1,104 @@
+import { type Q } from "../units.js";
+/** The five environmental threat categories. */
+export type HazardType = "fire" | "radiation" | "toxic_gas" | "acid" | "extreme_cold";
+/** All hazard type identifiers (useful for validation and iteration). */
+export declare const ALL_HAZARD_TYPES: HazardType[];
+/** A persistent circular hazard zone in world-space. */
+export interface HazardZone {
+    id: string;
+    type: HazardType;
+    /** Centre x-coordinate [SCALE.m]. */
+    x_Sm: number;
+    /** Centre y-coordinate [SCALE.m]. */
+    y_Sm: number;
+    /** Radius beyond which exposure is zero [SCALE.m]. */
+    radius_Sm: number;
+    /** Peak intensity at the hazard centre [Q]. */
+    intensity_Q: Q;
+    /**
+     * Remaining lifetime in seconds.
+     * `-1` = permanent (never expires; stepHazardZone is a no-op).
+     * Decremented by `stepHazardZone`. Clamped to 0 at expiry.
+     */
+    durationSeconds: number;
+}
+/**
+ * Per-second hazard effect rates.
+ *
+ * All Q fields are non-negative except `thermalDelta_Q` (negative = cooling).
+ * The host multiplies by `dt` before applying, except `thermalDelta_Q` which
+ * is a continuous ambient offset (applied as-is each tick).
+ */
+export interface HazardEffect {
+    /** Fatigue added per second of exposure [Q/s]. */
+    fatigueInc_Q: Q;
+    /**
+     * Thermal bias while inside the hazard [Q].
+     * Positive = heating (fire), negative = cooling (extreme_cold).
+     * Uses Phase 29/51 Q encoding: 185 Q ≈ 1 °C.
+     */
+    thermalDelta_Q: Q;
+    /** Cumulative radiation dose per second [Q/s]. Maps to Phase 53 radiation_dose. */
+    radiationDose_Q: Q;
+    /** Surface integrity damage per second [Q/s]. */
+    surfaceDamageInc_Q: Q;
+    /** Disease profile ID to test for exposure this tick (or undefined). */
+    diseaseExposureId?: string;
+}
+/** A modest campfire — 3 m radius, 1-hour duration. */
+export declare const CAMPFIRE: HazardZone;
+/** A contaminated crater — 50 m radius, permanent. */
+export declare const RADIATION_ZONE: HazardZone;
+/** A drifting toxic-gas cloud — 20 m radius, 30-minute duration. */
+export declare const MUSTARD_GAS: HazardZone;
+/** A corrosive acid pool — 2 m radius, 2-hour duration. */
+export declare const ACID_POOL: HazardZone;
+/** A severe cold zone — 100 m radius, 6-hour duration. */
+export declare const BLIZZARD_ZONE: HazardZone;
+/** All sample hazard zones. */
+export declare const ALL_SAMPLE_HAZARDS: HazardZone[];
+/**
+ * Euclidean distance from a world position to the hazard centre [SCALE.m].
+ *
+ * Uses float sqrt for a one-time calculation; result is truncated to integer.
+ */
+export declare function computeDistToHazard(x_Sm: number, y_Sm: number, hazard: HazardZone): number;
+/**
+ * True if the given position is within or on the hazard boundary.
+ *
+ * Uses integer squared-distance comparison to avoid float precision issues.
+ */
+export declare function isInsideHazard(x_Sm: number, y_Sm: number, hazard: HazardZone): boolean;
+/**
+ * Compute the exposure intensity at a given distance from the hazard centre.
+ *
+ * Linear falloff:  `exposure = (radius − dist) × intensity / radius`
+ * Returns `q(0)` when `dist >= radius`.
+ *
+ * @param dist_Sm  Distance from hazard centre [SCALE.m].
+ */
+export declare function computeHazardExposure(dist_Sm: number, hazard: HazardZone): Q;
+/**
+ * Derive per-second hazard effect rates from an exposure level.
+ *
+ * `exposureQ` is the output of `computeHazardExposure` — already in [0, intensity_Q].
+ * Each base rate is scaled linearly: `rate = base × exposureQ / SCALE.Q`.
+ *
+ * `thermalDelta_Q` uses the same scaling so the thermal offset fades toward the
+ * hazard boundary.
+ *
+ * Returns a zero-effect record when `exposureQ <= 0`.
+ */
+export declare function deriveHazardEffect(hazard: HazardZone, exposureQ: Q): HazardEffect;
+/**
+ * Advance a hazard zone's lifetime by `elapsedSeconds`.
+ *
+ * Permanent hazards (`durationSeconds === -1`) are untouched.
+ * Mutates: `hazard.durationSeconds`.
+ */
+export declare function stepHazardZone(hazard: HazardZone, elapsedSeconds: number): void;
+/**
+ * True when the hazard has run out of duration and should be removed from the world.
+ * Always false for permanent hazards.
+ */
+export declare function isHazardExpired(hazard: HazardZone): boolean;