@its-not-rocket-science/ananke 0.1.0

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

@@ -0,0 +1,141 @@
+import type { Vec3 } from "./vec3.js";
+import type { Q, I32 } from "../units.js";
+import { TraceKinds, type HitArea } from "./kinds.js";
+import type { MedicalAction } from "./medical.js";
+import { BodyRegion } from "./body.js";
+import { BodySegmentId } from "./bodyplan.js";
+export type TraceEvent = {
+    kind: typeof TraceKinds.TickStart;
+    tick: number;
+} | {
+    kind: typeof TraceKinds.TickEnd;
+    tick: number;
+} | {
+    kind: typeof TraceKinds.Intent;
+    tick: number;
+    entityId: number;
+    intent: unknown;
+} | {
+    kind: typeof TraceKinds.Move;
+    tick: number;
+    entityId: number;
+    pos: Vec3;
+    vel: Vec3;
+} | {
+    kind: typeof TraceKinds.Injury;
+    tick: number;
+    entityId: number;
+    dead: boolean;
+    shockQ: Q;
+    fluidLossQ: Q;
+    consciousnessQ: Q;
+} | {
+    kind: typeof TraceKinds.Attack;
+    tick: number;
+    attackerId: number;
+    targetId: number;
+    weaponId?: string;
+    region: BodyRegion | BodySegmentId;
+    energy_J: number;
+    blocked: boolean;
+    parried: boolean;
+    shieldBlocked: boolean;
+    armoured: boolean;
+    hitQuality: Q;
+} | {
+    kind: typeof TraceKinds.AttackAttempt;
+    tick: number;
+    attackerId: number;
+    targetId: number;
+    hit: boolean;
+    blocked: boolean;
+    parried: boolean;
+    hitQuality: number;
+    area: HitArea;
+} | {
+    kind: typeof TraceKinds.KO;
+    tick: number;
+    entityId: number;
+} | {
+    kind: typeof TraceKinds.Death;
+    tick: number;
+    entityId: number;
+} | {
+    kind: typeof TraceKinds.Grapple;
+    tick: number;
+    attackerId: number;
+    targetId: number;
+    phase: "start" | "tick" | "break";
+    strengthQ?: number;
+} | {
+    kind: typeof TraceKinds.WeaponBind;
+    tick: number;
+    attackerId: number;
+    targetId: number;
+    durationTicks: number;
+} | {
+    kind: typeof TraceKinds.WeaponBindBreak;
+    tick: number;
+    entityId: number;
+    partnerId: number;
+    reason: "timeout" | "forced";
+} | {
+    kind: typeof TraceKinds.ProjectileHit;
+    tick: number;
+    shooterId: number;
+    targetId: number;
+    weaponId?: string;
+    hit: boolean;
+    region?: BodyRegion | BodySegmentId;
+    distance_m: I32;
+    energyAtImpact_J: number;
+    suppressed: boolean;
+} | {
+    kind: typeof TraceKinds.MoraleRoute;
+    tick: number;
+    entityId: number;
+    fearQ: Q;
+} | {
+    kind: typeof TraceKinds.MoraleRally;
+    tick: number;
+    entityId: number;
+    fearQ: Q;
+} | {
+    kind: typeof TraceKinds.Fracture;
+    tick: number;
+    entityId: number;
+    region: BodyRegion | BodySegmentId;
+} | {
+    kind: typeof TraceKinds.TreatmentApplied;
+    tick: number;
+    treaterId: number;
+    targetId: number;
+    action: MedicalAction;
+    regionId?: string;
+} | {
+    kind: typeof TraceKinds.BlastHit;
+    tick: number;
+    entityId: number;
+    blastEnergy_J: number;
+    fragHits: number;
+} | {
+    kind: typeof TraceKinds.CapabilityActivated;
+    tick: number;
+    entityId: number;
+    sourceId: string;
+    effectId: string;
+} | {
+    kind: typeof TraceKinds.CapabilitySuppressed;
+    tick: number;
+    entityId: number;
+    sourceId: string;
+    effectId: string;
+} | {
+    kind: typeof TraceKinds.CastInterrupted;
+    tick: number;
+    entityId: number;
+};
+export interface TraceSink {
+    onEvent(ev: TraceEvent): void;
+}
+export declare const nullTrace: TraceSink;

package/dist/src/sim/trace.js

@@ -0,0 +1 @@
+export const nullTrace = { onEvent() { } };

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

@@ -0,0 +1,16 @@
+import type { Q } from "../units.js";
+export type RealismLevel = "arcade" | "tactical" | "sim";
+export interface SimulationTuning {
+    realism: RealismLevel;
+    armDisableThreshold: Q;
+    legDisableThreshold: Q;
+    standFailThreshold: Q;
+    unconsciousThreshold: Q;
+    stumbleBaseChance: Q;
+    fallBaseChance: Q;
+    dropWeaponsOnUnconscious: boolean;
+    standUpBaseTicks: number;
+    standUpMaxExtraTicks: number;
+    unconsciousBaseTicks: number;
+}
+export declare const TUNING: Record<RealismLevel, SimulationTuning>;

package/dist/src/sim/tuning.js

@@ -0,0 +1,42 @@
+import { q } from "../units.js";
+export const TUNING = {
+    arcade: {
+        realism: "arcade",
+        armDisableThreshold: q(0.98),
+        legDisableThreshold: q(0.98),
+        standFailThreshold: q(0.05),
+        unconsciousThreshold: q(0.03),
+        stumbleBaseChance: q(0.0),
+        fallBaseChance: q(0.0),
+        dropWeaponsOnUnconscious: false,
+        standUpBaseTicks: 0,
+        standUpMaxExtraTicks: 0,
+        unconsciousBaseTicks: 5,
+    },
+    tactical: {
+        realism: "tactical",
+        armDisableThreshold: q(0.85),
+        legDisableThreshold: q(0.90),
+        standFailThreshold: q(0.20),
+        unconsciousThreshold: q(0.10),
+        stumbleBaseChance: q(0.002),
+        fallBaseChance: q(0.001),
+        dropWeaponsOnUnconscious: false,
+        standUpBaseTicks: 15,
+        standUpMaxExtraTicks: 45,
+        unconsciousBaseTicks: 30,
+    },
+    sim: {
+        realism: "sim",
+        armDisableThreshold: q(0.75),
+        legDisableThreshold: q(0.80),
+        standFailThreshold: q(0.30),
+        unconsciousThreshold: q(0.15),
+        stumbleBaseChance: q(0.010),
+        fallBaseChance: q(0.005),
+        dropWeaponsOnUnconscious: true,
+        standUpBaseTicks: 25,
+        standUpMaxExtraTicks: 80,
+        unconsciousBaseTicks: 60,
+    },
+};

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

@@ -0,0 +1,14 @@
+import { type I32 } from "../units.js";
+import type { Q } from "../units.js";
+export interface Vec3 {
+    x: I32;
+    y: I32;
+    z: I32;
+}
+export declare const v3: (x?: I32, y?: I32, z?: I32) => Vec3;
+export declare const vAdd: (a: Vec3, b: Vec3) => Vec3;
+export declare const vSub: (a: Vec3, b: Vec3) => Vec3;
+export declare const vScaleQ: (a: Vec3, q: Q) => Vec3;
+export declare function normaliseDirCheapQ(d: Vec3): Vec3;
+export declare const integratePos: (pos: Vec3, vel_mps: Vec3, dt_s: I32) => Vec3;
+export declare function dotDirQ(a: Vec3, b: Vec3): Q;

package/dist/src/sim/vec3.js

@@ -0,0 +1,31 @@
+import { SCALE } from "../units.js";
+import { mulDiv } from "../units.js";
+export const v3 = (x = 0, y = 0, z = 0) => ({ x, y, z });
+export const vAdd = (a, b) => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z });
+export const vSub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z });
+export const vScaleQ = (a, q) => ({
+    x: Math.trunc((a.x * q) / SCALE.Q),
+    y: Math.trunc((a.y * q) / SCALE.Q),
+    z: Math.trunc((a.z * q) / SCALE.Q),
+});
+// Normalise direction into "Q-space": components scaled so max(|x|,|y|,|z|) becomes SCALE.Q.
+// Deterministic, no sqrt. Good enough for movement intents and facing.
+export function normaliseDirCheapQ(d) {
+    const ax = Math.abs(d.x), ay = Math.abs(d.y), az = Math.abs(d.z);
+    const m = Math.max(1, ax, ay, az);
+    return {
+        x: Math.trunc((d.x * SCALE.Q) / m),
+        y: Math.trunc((d.y * SCALE.Q) / m),
+        z: Math.trunc((d.z * SCALE.Q) / m),
+    };
+}
+// velocity is fixed m/s (SCALE.mps), dt is fixed seconds (SCALE.s)
+export const integratePos = (pos, vel_mps, dt_s) => ({
+    x: pos.x + Math.trunc((vel_mps.x * dt_s) / SCALE.s),
+    y: pos.y + Math.trunc((vel_mps.y * dt_s) / SCALE.s),
+    z: pos.z + Math.trunc((vel_mps.z * dt_s) / SCALE.s),
+});
+export function dotDirQ(a, b) {
+    const d = mulDiv(a.x, b.x, SCALE.Q) + mulDiv(a.y, b.y, SCALE.Q) + mulDiv(a.z, b.z, SCALE.Q);
+    return Math.max(-SCALE.Q, Math.min(SCALE.Q, d));
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Phase 2C: Weapon Dynamics Expansion
+ *
+ * Pure functions for:
+ *   - Reach dominance: short weapon penalised vs longer weapon
+ *   - Two-handed leverage bonus: N·m advantage on attack energy
+ *   - Miss recovery: extra cooldown ticks from weapon angular momentum
+ *   - Weapon bind: opposing weapons locked on parry; requires contest to clear
+ */
+import { type Q, type I32 } from "../units.js";
+import type { Weapon } from "../equipment.js";
+/**
+ * Attack skill multiplier when attacker has shorter reach than target.
+ *
+ * The penalty ramps linearly with the reach deficit fraction:
+ *   penalty_frac = (targetReach - attackerReach) / targetReach × 0.40
+ *   multiplier   = clamp(1.0 - penalty_frac, 0.60, 1.0)
+ *
+ * Examples (at 20 Hz):
+ *   knife (0.20 m) vs sword (0.80 m) → deficit 75 % → penalty 30 % → ×0.70
+ *   club  (0.70 m) vs club  (0.70 m) → no penalty                   → ×1.00
+ *   sword (0.80 m) vs knife (0.20 m) → no penalty (attacker longer)  → ×1.00
+ */
+export declare function reachDomPenaltyQ(attackerReach_m: I32, targetReach_m: I32): Q;
+/**
+ * Attack energy multiplier for two-handed weapons.
+ * Two-handed grip extends effective moment arm → more torque → higher energy transfer.
+ * Calibrated to the 1.10× parry leverage bonus: attack gets 1.12× (slightly higher, as
+ * a powered swing benefits more than a static parry).
+ *
+ * The bonus only applies when both arms are functional and no off-hand item is present.
+ *
+ * @param leftArmDisabled  from FunctionalState.leftArmDisabled
+ * @param rightArmDisabled from FunctionalState.rightArmDisabled
+ * @param hasOffHand       true if entity carries a shield or second weapon
+ */
+export declare function twoHandedAttackBonusQ(wpn: Weapon, leftArmDisabled: boolean, rightArmDisabled: boolean, hasOffHand: boolean): Q;
+/**
+ * Extra attack cooldown ticks after a missed strike.
+ * Derived from angular momentum proxy: mass × reach.
+ *
+ * Formula: floor(mass_kg_real × reach_m_real × 2)
+ *   where *_real means the value in SI units (not fixed-point).
+ *
+ * Calibration (at 20 Hz = 50 ms per tick):
+ *   knife  (0.30 kg, 0.20 m) → 0 ticks   (0 ms extra)
+ *   club   (1.20 kg, 0.70 m) → 1 tick    (50 ms extra)
+ *   sword  (1.20 kg, 0.80 m) → 1 tick    (50 ms extra)
+ *   halberd(2.00 kg, 1.50 m) → 6 ticks   (300 ms extra)
+ */
+export declare function missRecoveryTicks(wpn: Weapon): number;
+/**
+ * Probability of weapon bind occurring on a successful parry.
+ *
+ * Longer moment arms on both weapons → higher contact surface → more likely to lock.
+ *
+ * Formula:
+ *   aFrac = clamp(aArm / ref, 0.1, 2.0)
+ *   dFrac = clamp(dArm / ref, 0.1, 2.0)
+ *   chance = clamp(arithmetic_mean(aFrac, dFrac) × 0.25, 0, 0.45)
+ *
+ * Reference arm = 0.60 m (≈ arming sword).
+ *
+ * Examples:
+ *   two knives  (arm 0.18 m each): chance ≈ 7.5 %
+ *   two swords  (arm 0.45 m each): chance ≈ 18.8 %
+ *   two polearms (arm 1.50 m each, capped at 2.0): chance = 45 %
+ */
+export declare function bindChanceQ(attackerWpn: Weapon, defenderWpn: Weapon): Q;
+/**
+ * Bind duration in ticks (at 20 Hz).
+ * Heavier weapons take longer to disengage.
+ *
+ * Formula: clamp(2 + floor(avgMass_kg_real), 2, 8)
+ *
+ * Examples:
+ *   two knives (0.3 kg each):  2 ticks (100 ms)
+ *   two clubs  (1.2 kg each):  3 ticks (150 ms)
+ *   heavy axes (3.0 kg each):  5 ticks (250 ms)
+ */
+export declare function bindDurationTicks(attackerWpn: Weapon, defenderWpn: Weapon): number;
+/**
+ * Win probability Q for the entity trying to actively break a weapon bind.
+ *
+ * Contest: torque = peakForce_N × momentArm_m (both fixed-point, units cancel in ratio).
+ * P(break) = torque_breaker / (torque_breaker + torque_holder)
+ *
+ * Uses BigInt to avoid overflow (force ~184000 × arm ~5500 ≈ 1 billion).
+ *
+ * Returns Q ∈ [q(0.05), q(0.95)].
+ *
+ * Examples (both average humans with same weapon):
+ *   Equal: P = 0.50
+ *   Stronger breaker (2× force): P ≈ 0.67
+ *   Much longer lever (2× arm):  P ≈ 0.67
+ *
+ * @param breakerForce_N  attacker's peakForce_N (fixed-point)
+ * @param holderForce_N   partner's peakForce_N  (fixed-point)
+ * @param breakerArm_m    attacker's weapon momentArm_m (fixed-point)
+ * @param holderArm_m     partner's weapon momentArm_m  (fixed-point)
+ */
+export declare function breakBindContestQ(breakerForce_N: number, holderForce_N: number, breakerArm_m: number, holderArm_m: number): Q;

package/dist/src/sim/weapon_dynamics.js

@@ -0,0 +1,142 @@
+/**
+ * Phase 2C: Weapon Dynamics Expansion
+ *
+ * Pure functions for:
+ *   - Reach dominance: short weapon penalised vs longer weapon
+ *   - Two-handed leverage bonus: N·m advantage on attack energy
+ *   - Miss recovery: extra cooldown ticks from weapon angular momentum
+ *   - Weapon bind: opposing weapons locked on parry; requires contest to clear
+ */
+import { SCALE, q, clampQ, qMul, mulDiv } from "../units.js";
+// ---- Reach dominance ----
+/**
+ * Attack skill multiplier when attacker has shorter reach than target.
+ *
+ * The penalty ramps linearly with the reach deficit fraction:
+ *   penalty_frac = (targetReach - attackerReach) / targetReach × 0.40
+ *   multiplier   = clamp(1.0 - penalty_frac, 0.60, 1.0)
+ *
+ * Examples (at 20 Hz):
+ *   knife (0.20 m) vs sword (0.80 m) → deficit 75 % → penalty 30 % → ×0.70
+ *   club  (0.70 m) vs club  (0.70 m) → no penalty                   → ×1.00
+ *   sword (0.80 m) vs knife (0.20 m) → no penalty (attacker longer)  → ×1.00
+ */
+export function reachDomPenaltyQ(attackerReach_m, targetReach_m) {
+    if (attackerReach_m >= targetReach_m)
+        return q(1.0);
+    const deficit = targetReach_m - attackerReach_m;
+    const deficitFrac = clampQ(mulDiv(deficit, SCALE.Q, Math.max(1, targetReach_m)), q(0), q(1.0));
+    return clampQ((q(1.0) - qMul(deficitFrac, q(0.40))), q(0.60), q(1.0));
+}
+// ---- Two-handed leverage bonus ----
+/**
+ * Attack energy multiplier for two-handed weapons.
+ * Two-handed grip extends effective moment arm → more torque → higher energy transfer.
+ * Calibrated to the 1.10× parry leverage bonus: attack gets 1.12× (slightly higher, as
+ * a powered swing benefits more than a static parry).
+ *
+ * The bonus only applies when both arms are functional and no off-hand item is present.
+ *
+ * @param leftArmDisabled  from FunctionalState.leftArmDisabled
+ * @param rightArmDisabled from FunctionalState.rightArmDisabled
+ * @param hasOffHand       true if entity carries a shield or second weapon
+ */
+export function twoHandedAttackBonusQ(wpn, leftArmDisabled, rightArmDisabled, hasOffHand) {
+    if ((wpn.handedness ?? "oneHand") !== "twoHand")
+        return q(1.0);
+    if (leftArmDisabled || rightArmDisabled || hasOffHand)
+        return q(1.0);
+    return q(1.12);
+}
+// ---- Miss recovery ----
+/**
+ * Extra attack cooldown ticks after a missed strike.
+ * Derived from angular momentum proxy: mass × reach.
+ *
+ * Formula: floor(mass_kg_real × reach_m_real × 2)
+ *   where *_real means the value in SI units (not fixed-point).
+ *
+ * Calibration (at 20 Hz = 50 ms per tick):
+ *   knife  (0.30 kg, 0.20 m) → 0 ticks   (0 ms extra)
+ *   club   (1.20 kg, 0.70 m) → 1 tick    (50 ms extra)
+ *   sword  (1.20 kg, 0.80 m) → 1 tick    (50 ms extra)
+ *   halberd(2.00 kg, 1.50 m) → 6 ticks   (300 ms extra)
+ */
+export function missRecoveryTicks(wpn) {
+    const reach_m = wpn.reach_m ?? Math.trunc(0.7 * SCALE.m);
+    const num = BigInt(wpn.mass_kg) * BigInt(reach_m) * 2n;
+    const den = BigInt(SCALE.kg) * BigInt(SCALE.m);
+    return Math.max(0, Number(num / den));
+}
+// ---- Weapon bind ----
+/**
+ * Probability of weapon bind occurring on a successful parry.
+ *
+ * Longer moment arms on both weapons → higher contact surface → more likely to lock.
+ *
+ * Formula:
+ *   aFrac = clamp(aArm / ref, 0.1, 2.0)
+ *   dFrac = clamp(dArm / ref, 0.1, 2.0)
+ *   chance = clamp(arithmetic_mean(aFrac, dFrac) × 0.25, 0, 0.45)
+ *
+ * Reference arm = 0.60 m (≈ arming sword).
+ *
+ * Examples:
+ *   two knives  (arm 0.18 m each): chance ≈ 7.5 %
+ *   two swords  (arm 0.45 m each): chance ≈ 18.8 %
+ *   two polearms (arm 1.50 m each, capped at 2.0): chance = 45 %
+ */
+export function bindChanceQ(attackerWpn, defenderWpn) {
+    const refArm = Math.trunc(0.6 * SCALE.m);
+    const aArm = attackerWpn.momentArm_m ?? Math.trunc(0.55 * SCALE.m);
+    const dArm = defenderWpn.momentArm_m ?? Math.trunc(0.55 * SCALE.m);
+    const aFrac = clampQ(mulDiv(aArm, SCALE.Q, refArm), q(0.1), q(2.0));
+    const dFrac = clampQ(mulDiv(dArm, SCALE.Q, refArm), q(0.1), q(2.0));
+    const mean = ((aFrac + dFrac) >>> 1);
+    return clampQ(qMul(mean, q(0.25)), q(0.0), q(0.45));
+}
+/**
+ * Bind duration in ticks (at 20 Hz).
+ * Heavier weapons take longer to disengage.
+ *
+ * Formula: clamp(2 + floor(avgMass_kg_real), 2, 8)
+ *
+ * Examples:
+ *   two knives (0.3 kg each):  2 ticks (100 ms)
+ *   two clubs  (1.2 kg each):  3 ticks (150 ms)
+ *   heavy axes (3.0 kg each):  5 ticks (250 ms)
+ */
+export function bindDurationTicks(attackerWpn, defenderWpn) {
+    const avgMass = (attackerWpn.mass_kg + defenderWpn.mass_kg) >>> 1;
+    const massReal = avgMass / SCALE.kg;
+    return Math.max(2, Math.min(8, Math.trunc(2 + massReal)));
+}
+// ---- Bind breaking contest ----
+/**
+ * Win probability Q for the entity trying to actively break a weapon bind.
+ *
+ * Contest: torque = peakForce_N × momentArm_m (both fixed-point, units cancel in ratio).
+ * P(break) = torque_breaker / (torque_breaker + torque_holder)
+ *
+ * Uses BigInt to avoid overflow (force ~184000 × arm ~5500 ≈ 1 billion).
+ *
+ * Returns Q ∈ [q(0.05), q(0.95)].
+ *
+ * Examples (both average humans with same weapon):
+ *   Equal: P = 0.50
+ *   Stronger breaker (2× force): P ≈ 0.67
+ *   Much longer lever (2× arm):  P ≈ 0.67
+ *
+ * @param breakerForce_N  attacker's peakForce_N (fixed-point)
+ * @param holderForce_N   partner's peakForce_N  (fixed-point)
+ * @param breakerArm_m    attacker's weapon momentArm_m (fixed-point)
+ * @param holderArm_m     partner's weapon momentArm_m  (fixed-point)
+ */
+export function breakBindContestQ(breakerForce_N, holderForce_N, breakerArm_m, holderArm_m) {
+    const tBreaker = BigInt(breakerForce_N) * BigInt(breakerArm_m);
+    const tHolder = BigInt(holderForce_N) * BigInt(holderArm_m);
+    const total = tBreaker + tHolder;
+    if (total === 0n)
+        return q(0.5);
+    return clampQ(Number(tBreaker * BigInt(SCALE.Q) / total), q(0.05), q(0.95));
+}

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

@@ -0,0 +1,95 @@
+import type { Q } from "../units.js";
+/** Precipitation category. */
+export type PrecipitationType = "none" | "rain" | "heavy_rain" | "snow" | "blizzard" | "hail";
+/**
+ * 2D wind vector.
+ * `dx_m` and `dy_m` form a unit vector in SCALE.m space: |(dx_m, dy_m)| = SCALE.m.
+ * `speed_mps` is the wind speed in SCALE.mps units.
+ */
+export interface WindField {
+    /** X component of wind direction (SCALE.m = 1000; unit vector). */
+    dx_m: number;
+    /** Y component of wind direction (SCALE.m = 1000; unit vector). */
+    dy_m: number;
+    /** Wind speed [SCALE.mps]. 1000 = 10 m/s. */
+    speed_mps: number;
+}
+/** Weather conditions passed into a simulation tick via KernelContext.weather. */
+export interface WeatherState {
+    wind?: WindField;
+    precipitation?: PrecipitationType;
+    /**
+     * Fog density (Q 0..SCALE.Q).
+     * q(0) = clear; q(1.0) = pea-soup fog → vision capped to q(0.10) of normal.
+     */
+    fogDensity_Q?: Q;
+}
+/** Derived modifiers ready for the kernel to apply each tick. */
+export interface WeatherModifiers {
+    /**
+     * Multiply KernelContext.tractionCoeff.
+     * q(1.0) = unchanged; q(0.70) = 30% slipperier surface.
+     */
+    tractionMul_Q: Q;
+    /**
+     * Multiply SensoryEnvironment.lightMul (fog + precipitation combined).
+     * q(1.0) = clear; q(0.30) = dense blizzard / fog.
+     */
+    lightMul_Q: Q;
+    /**
+     * Multiply SensoryEnvironment.smokeMul (precipitation visual masking only).
+     * Heavy rain / blizzard partially obscures vision like smoke.
+     */
+    precipVisionMul_Q: Q;
+    /**
+     * Additive offset to KernelContext.thermalAmbient_Q (Phase-29 Q encoding).
+     * Negative = cooling effect.  1 °C ≈ WEATHER_Q_PER_DEG_C Q units.
+     */
+    thermalOffset_Q: number;
+}
+/**
+ * Approximate Q units per degree Celsius in the Phase-29 thermal encoding.
+ * (SCALE.Q / 54) where 54 = 64°C − 10°C temperature range).
+ */
+export declare const WEATHER_Q_PER_DEG_C = 185;
+/**
+ * Compute all derived modifiers for a WeatherState.
+ * Pure function — no side effects.
+ */
+export declare function deriveWeatherModifiers(weather: WeatherState): WeatherModifiers;
+/**
+ * Additional aim grouping radius from wind drift [SCALE.m].
+ *
+ * Physics: drift = v_wind_perp × (range / v_proj)
+ *
+ * The perpendicular wind component is the 2D cross product of shot direction
+ * and wind direction.  Algebraic simplification yields:
+ *
+ *   drift_scaled_m = wind.speed_mps × |shot × wind| / (SCALE.m × v_proj_mps)
+ *
+ * where |shot × wind| is the cross-product magnitude in SCALE.m² units with
+ * shot direction of magnitude `dist_m` and wind direction of magnitude SCALE.m.
+ * The `dist_m` factors cancel, leaving a formula independent of scale choice.
+ *
+ * @param wind        Wind field (direction + speed).
+ * @param shotDx_m    Shot direction x [SCALE.m] (raw, not normalised).
+ * @param shotDy_m    Shot direction y [SCALE.m] (raw, not normalised).
+ * @param dist_m      Range to target [SCALE.m].
+ * @param v_proj_mps  Projectile speed [SCALE.mps].
+ * @returns Additional grouping radius [SCALE.m] (≥ 0).
+ */
+export declare function computeWindAimError(wind: WindField, shotDx_m: number, shotDy_m: number, dist_m: number, v_proj_mps: number): number;
+/**
+ * Adjust cone range for wind effects (breath weapons, gas clouds, flamethrowers).
+ *
+ * - Headwind (wind opposes cone direction) reduces range up to −20%.
+ * - Tailwind extends range up to +10%.
+ * - Crosswind (perpendicular) has no effect on range.
+ *
+ * @param wind      Wind field.
+ * @param coneDx_m  Cone facing direction x (SCALE.m unit vector).
+ * @param coneDy_m  Cone facing direction y (SCALE.m unit vector).
+ * @param range_m   Base cone range [SCALE.m].
+ * @returns Adjusted range [SCALE.m] (≥ 0).
+ */
+export declare function adjustConeRange(wind: WindField, coneDx_m: number, coneDy_m: number, range_m: number): number;