@its-not-rocket-science/ananke 0.1.0

package/dist/src/sim/occlusion.js

@@ -0,0 +1,71 @@
+import { queryNearbyIds } from "./spatial.js";
+import { isEnemy, areEntitiesHostile } from "./team.js";
+export function isMeleeLaneOccludedByFriendly(world, attacker, target, index, spatial, q) {
+    // Only matters if same team as attacker (friendly body blocking)
+    const laneR = q.laneRadius_m;
+    const ax = attacker.position_m.x, ay = attacker.position_m.y, az = attacker.position_m.z;
+    const tx = target.position_m.x, ty = target.position_m.y, tz = target.position_m.z;
+    const dx = tx - ax, dy = ty - ay, dz = tz - az;
+    // If target is on same team, don't treat as occlusion here (that’s friendly fire prevention elsewhere)
+    // Occlusion checks FRIENDLIES between attacker and ENEMY target
+    const hostile = world ? areEntitiesHostile(attacker, target, world) : isEnemy(attacker, target);
+    if (!hostile)
+        return false;
+    // Search near the midpoint with radius ~= half-distance + laneR
+    // This bounds the search to local neighbourhood (fast at scale)
+    const mx = ax + (dx >> 1);
+    const my = ay + (dy >> 1);
+    const mz = az + (dz >> 1);
+    // radius = half distance + lane radius
+    // sqrt not needed: use conservative bound in fixed-point
+    const halfDist = approxHalfDist(ax, ay, tx, ty); // metres scaled
+    const searchR = halfDist + laneR;
+    const ids = queryNearbyIds(spatial, { x: mx, y: my, z: mz }, searchR);
+    ids.sort((a, b) => a - b);
+    // Check for any friendly that lies between attacker and target AND within lane radius of the segment
+    for (const id of ids) {
+        if (id === attacker.id || id === target.id)
+            continue;
+        const e = index.byId.get(id);
+        if (!e || e.injury.dead)
+            continue;
+        if (e.teamId !== attacker.teamId)
+            continue; // only friendlies block
+        // must be between along the segment (0 < t < 1) and close to it
+        if (pointNearSegmentQ(e.position_m.x, e.position_m.y, ax, ay, tx, ty, laneR)) {
+            return true;
+        }
+    }
+    return false;
+}
+function approxHalfDist(ax, ay, tx, ty) {
+    const dx = tx - ax;
+    const dy = ty - ay;
+    const adx = dx < 0 ? -dx : dx;
+    const ady = dy < 0 ? -dy : dy;
+    // Cheap L∞/L1 mix; we just need a conservative search radius
+    const approx = adx > ady ? adx + (ady >> 1) : ady + (adx >> 1);
+    return approx >> 1;
+}
+/**
+ * Returns true if point P is within laneR of segment A->B in 2D, and lies between A and B.
+ * Uses only integer math (deterministic).
+ */
+function pointNearSegmentQ(px, py, ax, ay, bx, by, laneR) {
+    const vx = bx - ax;
+    const vy = by - ay;
+    const wx = px - ax;
+    const wy = py - ay;
+    const vv = BigInt(vx) * BigInt(vx) + BigInt(vy) * BigInt(vy);
+    if (vv === 0n)
+        return false;
+    const tNum = BigInt(wx) * BigInt(vx) + BigInt(wy) * BigInt(vy);
+    if (tNum <= 0n || tNum >= vv)
+        return false; // strictly between
+    // distance^2 to line = |w|^2 - (w·v)^2 / |v|^2
+    const ww = BigInt(wx) * BigInt(wx) + BigInt(wy) * BigInt(wy);
+    const proj2 = (tNum * tNum) / vv;
+    const dist2 = ww - proj2;
+    const lane2 = BigInt(laneR) * BigInt(laneR);
+    return dist2 <= lane2;
+}

package/dist/src/sim/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/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/ranged.d.ts

@@ -0,0 +1,44 @@
+import { type Q, type I32 } from "../units.js";
+import type { RangedWeapon } from "../equipment.js";
+export declare const TICK_HZ_RANGED = 20;
+/**
+ * Energy remaining after ballistic drag over a given range.
+ *
+ * Linear approximation: energyFrac = max(0, 1 - range_m × dragCoeff_perM)
+ * dragCoeff_perM is a Q value: q(0.007) means 0.7% loss per metre.
+ */
+export declare function energyAtRange_J(launchEnergy_J: I32, dragCoeff_perM: Q, range_m: I32): I32;
+/**
+ * Adjusted dispersion (angular error in Q) accounting for shooter skill, fatigue, and
+ * aiming intensity.
+ *
+ * controlMod: [1.0, 1.5] — poor aim widens spread
+ * fatigueMod: [1.0, 1.5] — fatigue widens spread
+ * intensityMod: [1.0, 1.9] — low intensity (snap shot) widens spread
+ */
+export declare function adjustedDispersionQ(baseDispQ: Q, controlQuality: Q, fineControl: Q, fatigue: Q, intensity: Q): Q;
+/**
+ * Grouping radius (m in SCALE.m) at given range.
+ * groupingRadius_m = dispersionQ × range_m / SCALE.Q
+ */
+export declare function groupingRadius_m(dispersionQ: Q, range_m: I32): I32;
+/**
+ * Launch energy (J) for thrown weapons derived from thrower's peak power.
+ * Models a ~100ms burst at 10% peak power.
+ * Calibration: 1200 W × 0.10 = 120 J for average human.
+ */
+export declare function thrownLaunchEnergy_J(peakPower_W: I32): I32;
+/**
+ * Number of simulation ticks before the next shot can be fired.
+ * recycleTime_s is in SCALE.s units.
+ */
+export declare function recycleTicks(wpn: RangedWeapon, tickHz: number): number;
+/**
+ * Energy cost (J) of firing a shot at the given intensity.
+ * Modelled as ~50 ms draw/snap at 8% peak power for bows/throws;
+ * negligible for firearms but still costs something (aim/recoil recovery).
+ *
+ * For weapons where launchEnergy derives from the shooter (thrown),
+ * we use a larger fraction (10%) since the throw itself burns energy.
+ */
+export declare function shootCost_J(wpn: RangedWeapon, intensity: Q, peakPower_W: I32): I32;

package/dist/src/sim/ranged.js

@@ -0,0 +1,69 @@
+// src/sim/ranged.ts — Phase 3: pure ranged-combat physics (no Entity import)
+import { SCALE, q, clampQ, qMul, mulDiv } from "../units.js";
+export const TICK_HZ_RANGED = 20; // must match kernel TICK_HZ
+/**
+ * Energy remaining after ballistic drag over a given range.
+ *
+ * Linear approximation: energyFrac = max(0, 1 - range_m × dragCoeff_perM)
+ * dragCoeff_perM is a Q value: q(0.007) means 0.7% loss per metre.
+ */
+export function energyAtRange_J(launchEnergy_J, dragCoeff_perM, range_m) {
+    if (launchEnergy_J <= 0)
+        return 0;
+    const lossFrac = mulDiv(range_m, dragCoeff_perM, SCALE.m); // Q-scaled fraction lost
+    const energyFrac = Math.max(0, SCALE.Q - lossFrac);
+    return mulDiv(launchEnergy_J, energyFrac, SCALE.Q);
+}
+/**
+ * Adjusted dispersion (angular error in Q) accounting for shooter skill, fatigue, and
+ * aiming intensity.
+ *
+ * controlMod: [1.0, 1.5] — poor aim widens spread
+ * fatigueMod: [1.0, 1.5] — fatigue widens spread
+ * intensityMod: [1.0, 1.9] — low intensity (snap shot) widens spread
+ */
+export function adjustedDispersionQ(baseDispQ, controlQuality, fineControl, fatigue, intensity) {
+    const aimSkill = clampQ(((controlQuality + fineControl) >>> 1), q(0), q(1.0));
+    // controlMod in Q: 2.0 - aimSkill, clamped [1.0, 1.5]
+    const controlMod = clampQ((2 * SCALE.Q - aimSkill), SCALE.Q, Math.round(1.5 * SCALE.Q));
+    // fatigueMod in Q: 1.0 + fatigue × 0.5, clamped [1.0, 1.5]
+    const fatigueMod = clampQ((SCALE.Q + qMul(fatigue, q(0.50))), SCALE.Q, Math.round(1.5 * SCALE.Q));
+    // intensityMod in Q: 2.0 - intensity, clamped [1.0, 1.9]
+    const intensityMod = clampQ((2 * SCALE.Q - clampQ(intensity, q(0.1), SCALE.Q)), SCALE.Q, Math.round(1.9 * SCALE.Q));
+    return qMul(qMul(qMul(baseDispQ, controlMod), fatigueMod), intensityMod);
+}
+/**
+ * Grouping radius (m in SCALE.m) at given range.
+ * groupingRadius_m = dispersionQ × range_m / SCALE.Q
+ */
+export function groupingRadius_m(dispersionQ, range_m) {
+    return mulDiv(dispersionQ, range_m, SCALE.Q);
+}
+/**
+ * Launch energy (J) for thrown weapons derived from thrower's peak power.
+ * Models a ~100ms burst at 10% peak power.
+ * Calibration: 1200 W × 0.10 = 120 J for average human.
+ */
+export function thrownLaunchEnergy_J(peakPower_W) {
+    return Math.max(10, Math.trunc(peakPower_W / 10));
+}
+/**
+ * Number of simulation ticks before the next shot can be fired.
+ * recycleTime_s is in SCALE.s units.
+ */
+export function recycleTicks(wpn, tickHz) {
+    return Math.max(1, Math.trunc((wpn.recycleTime_s * tickHz) / SCALE.s));
+}
+/**
+ * Energy cost (J) of firing a shot at the given intensity.
+ * Modelled as ~50 ms draw/snap at 8% peak power for bows/throws;
+ * negligible for firearms but still costs something (aim/recoil recovery).
+ *
+ * For weapons where launchEnergy derives from the shooter (thrown),
+ * we use a larger fraction (10%) since the throw itself burns energy.
+ */
+export function shootCost_J(wpn, intensity, peakPower_W) {
+    const fracBase = wpn.category === "thrown" ? 10 : wpn.category === "bow" ? 6 : 2;
+    const base = Math.max(5, Math.trunc(peakPower_W * fracBase / 100));
+    return Math.max(2, mulDiv(base, intensity, SCALE.Q));
+}

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

@@ -0,0 +1,3 @@
+export declare function eventSeed(worldSeed: number, tick: number, aId: number, bId: number, salt: number): number;
+/** Deterministic hash of a string to a number (simple sum of char codes). */
+export declare function hashString(s: string): number;

package/dist/src/sim/seeds.js

@@ -0,0 +1,16 @@
+export function eventSeed(worldSeed, tick, aId, bId, salt) {
+    let x = (worldSeed ^ (tick * 0x9E3779B1) ^ (aId * 0x85EBCA77) ^ (bId * 0xC2B2AE3D) ^ salt) >>> 0;
+    x ^= x >>> 16;
+    x = Math.imul(x, 0x7FEB352D) >>> 0;
+    x ^= x >>> 15;
+    x = Math.imul(x, 0x846CA68B) >>> 0;
+    x ^= x >>> 16;
+    return x >>> 0;
+}
+/** Deterministic hash of a string to a number (simple sum of char codes). */
+export function hashString(s) {
+    let h = 0;
+    for (let i = 0; i < s.length; i++)
+        h += s.charCodeAt(i);
+    return h;
+}

package/dist/src/sim/sensory-extended.d.ts

@@ -0,0 +1,103 @@
+import type { Q } from "../units.js";
+import type { Entity } from "./entity.js";
+import type { SensoryEnvironment } from "./sensory.js";
+import type { WindField, PrecipitationType } from "./weather.js";
+/**
+ * Extra sensory capabilities attached to an entity.
+ * All fields are optional — absent = that modality is not present.
+ */
+export interface ExtendedSenses {
+    /**
+     * Echolocation detection range [SCALE.m].
+     * Non-zero = entity can detect physical objects via reflected sound.
+     * Bypasses lightMul and smokeMul; degraded by high ambient noise (noiseMul).
+     */
+    echolocationRange_m?: number;
+    /**
+     * Electroreception detection range [SCALE.m].
+     * Non-zero = entity can detect the bioelectric fields of living creatures.
+     * Short-range (~1–4 m for real-world species); unaffected by light or noise.
+     * Dead entities have no bioelectric field — not detectable.
+     */
+    electroreceptionRange_m?: number;
+    /**
+     * Olfaction (scent) sensitivity (Q 0..SCALE.Q).
+     * q(0) = absent; q(1.0) = wolf-level (detects prey at 50 m downwind).
+     * Wind direction enhances (downwind) or suppresses (upwind) detection.
+     * Precipitation disperses scent.
+     */
+    olfactionSensitivity_Q?: Q;
+}
+/** Detected via echolocation — returned by canDetectExtended. */
+export declare const DETECT_ECHOLOCATION: Q;
+/** Detected via electroreception — returned by canDetectExtended. */
+export declare const DETECT_ELECTRORECEPTION: Q;
+/**
+ * Compute ambient light multiplier from time of day.
+ *
+ * Uses cosine interpolation: noon (12 h) → q(1.0); midnight (0/24 h) → q(0.10).
+ * 6 h / 18 h (dawn/dusk) → q(0.55).
+ *
+ * Intended for use as a multiplier on SensoryEnvironment.lightMul:
+ *   `env.lightMul = Math.trunc(env.lightMul * computeDaylightMul(hour) / SCALE.Q)`
+ *
+ * @param hourOfDay  Real-valued hour, 0–24 (0 and 24 are both midnight).
+ * @returns Q multiplier in [q(0.10), q(1.0)].
+ */
+export declare function computeDaylightMul(hourOfDay: number): Q;
+/**
+ * Whether observer can detect subject via echolocation.
+ *
+ * - Requires `observer.extendedSenses.echolocationRange_m > 0`.
+ * - Unaffected by light or smoke — works in total darkness.
+ * - Effective range degraded by high ambient noise: `effectiveRange = range / noiseMul × SCALE.Q`.
+ *   At default (noiseMul = SCALE.Q): full range. At 2× noise: half range.
+ * - Detects physical presence (dead entities still detected).
+ *
+ * @param dist_m  Distance from observer to subject [SCALE.m].
+ * @param noiseMul  Ambient noise multiplier from SensoryEnvironment.
+ */
+export declare function canDetectByEcholocation(observer: Entity, subject: Entity, dist_m: number, noiseMul: Q): boolean;
+/**
+ * Whether observer can detect subject via electroreception.
+ *
+ * - Requires `observer.extendedSenses.electroreceptionRange_m > 0`.
+ * - Detects the bioelectric field of living entities only (dead = no field).
+ * - Unaffected by any environmental modifier.
+ *
+ * @param dist_m  Distance from observer to subject [SCALE.m].
+ */
+export declare function canDetectByElectroreception(observer: Entity, subject: Entity, dist_m: number): boolean;
+/**
+ * Olfactory detection strength (Q 0..SCALE.Q) of subject by observer.
+ *
+ * Returns q(0) if observer has no olfaction or subject is out of scent range.
+ * Returns higher values when:
+ *   - Observer is close to subject.
+ *   - Observer is downwind of subject (wind carries scent toward observer).
+ *   - Precipitation is absent or light.
+ *
+ * @param dist_m        Distance [SCALE.m].
+ * @param wind          Optional wind field from WeatherState.
+ * @param precipitation Optional precipitation type from WeatherState.
+ */
+export declare function deriveScentDetection(observer: Entity, subject: Entity, dist_m: number, wind?: WindField, precipitation?: PrecipitationType): Q;
+/**
+ * Full detection check including Phase 4 vision/hearing and Phase 52 extended modalities.
+ *
+ * Detection quality (Q) returned:
+ *   q(1.0)  — vision (primary)
+ *   q(0.8)  — electroreception (precise position, very short range)
+ *   q(0.7)  — echolocation (good spatial, darkness-independent)
+ *   q(0.4)  — hearing (Phase 4, omnidirectional)
+ *   q(0.20–0.40) — olfaction (approximate, wind/rain dependent)
+ *   q(0)    — undetected
+ *
+ * @param sensorBoost  Phase 11C sensor equipment bonus.
+ * @param wind         Optional wind for olfaction wind-alignment calculation.
+ * @param precipitation Optional precipitation for scent dispersal.
+ */
+export declare function canDetectExtended(observer: Entity, subject: Entity, env: SensoryEnvironment, sensorBoost?: {
+    visionRangeMul: Q;
+    hearingRangeMul: Q;
+}, wind?: WindField, precipitation?: PrecipitationType): Q;

package/dist/src/sim/sensory-extended.js

@@ -0,0 +1,181 @@
+// src/sim/sensory-extended.ts — Phase 52: Extended Sensory Systems
+//
+// Adds three sensory modalities beyond Phase 4 vision/hearing:
+//   - Echolocation: darkness-independent detection (bats, cetaceans, shrews)
+//   - Electroreception: bioelectric-field detection (sharks, eels, platypus)
+//   - Olfaction: wind-aware scent tracking (wolves, dogs, bears)
+//
+// Also provides computeDaylightMul() for time-of-day lighting integration
+// with SensoryEnvironment.lightMul.
+//
+// Data flow:
+//   canDetect (Phase 4) → canDetectExtended → extended modality checks
+//   computeDaylightMul(hourOfDay) → SensoryEnvironment.lightMul multiplier
+import { SCALE, q, clampQ, mulDiv } from "../units.js";
+import { canDetect } from "./sensory.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Reference olfaction range [SCALE.m]: q(1.0) sensitivity detects at 50 m downwind. */
+const OLFACTION_REF_RANGE_m = 50 * SCALE.m; // 50_000
+/** Minimum scent strength (Q) to count as olfactory detection. */
+const OLFACTION_DETECT_THRESHOLD = q(0.20);
+/** Detected via echolocation — returned by canDetectExtended. */
+export const DETECT_ECHOLOCATION = q(0.70);
+/** Detected via electroreception — returned by canDetectExtended. */
+export const DETECT_ELECTRORECEPTION = q(0.80);
+/** Minimum olfaction detection quality — returned by canDetectExtended. */
+const DETECT_OLFACTION_MIN = q(0.20);
+const DETECT_OLFACTION_MAX = q(0.40);
+/** Daylight Q at midnight (minimum). */
+const DAYLIGHT_NIGHT_Q = q(0.10);
+/** Precipitation scent dispersal multiplier (Q). */
+const PRECIP_SCENT_MUL = {
+    none: q(1.00),
+    rain: q(0.70),
+    heavy_rain: q(0.40),
+    snow: q(0.80),
+    blizzard: q(0.20),
+    hail: q(0.60),
+};
+// ── computeDaylightMul ────────────────────────────────────────────────────────
+/**
+ * Compute ambient light multiplier from time of day.
+ *
+ * Uses cosine interpolation: noon (12 h) → q(1.0); midnight (0/24 h) → q(0.10).
+ * 6 h / 18 h (dawn/dusk) → q(0.55).
+ *
+ * Intended for use as a multiplier on SensoryEnvironment.lightMul:
+ *   `env.lightMul = Math.trunc(env.lightMul * computeDaylightMul(hour) / SCALE.Q)`
+ *
+ * @param hourOfDay  Real-valued hour, 0–24 (0 and 24 are both midnight).
+ * @returns Q multiplier in [q(0.10), q(1.0)].
+ */
+export function computeDaylightMul(hourOfDay) {
+    // angle: noon (12h) maps to π → cos(π) = −1 → maximum light
+    //        midnight (0h) maps to 0 → cos(0) = +1 → minimum light
+    const angle = hourOfDay * Math.PI / 12;
+    const cosVal = Math.cos(angle);
+    // Map cos ∈ [+1, −1] → frac ∈ [0, 1] (0 at midnight, 1 at noon)
+    const frac = (1 - cosVal) / 2;
+    const result = Math.round(DAYLIGHT_NIGHT_Q + frac * (SCALE.Q - DAYLIGHT_NIGHT_Q));
+    return clampQ(result, DAYLIGHT_NIGHT_Q, SCALE.Q);
+}
+// ── canDetectByEcholocation ───────────────────────────────────────────────────
+/**
+ * Whether observer can detect subject via echolocation.
+ *
+ * - Requires `observer.extendedSenses.echolocationRange_m > 0`.
+ * - Unaffected by light or smoke — works in total darkness.
+ * - Effective range degraded by high ambient noise: `effectiveRange = range / noiseMul × SCALE.Q`.
+ *   At default (noiseMul = SCALE.Q): full range. At 2× noise: half range.
+ * - Detects physical presence (dead entities still detected).
+ *
+ * @param dist_m  Distance from observer to subject [SCALE.m].
+ * @param noiseMul  Ambient noise multiplier from SensoryEnvironment.
+ */
+export function canDetectByEcholocation(observer, subject, dist_m, noiseMul) {
+    const range = observer.extendedSenses?.echolocationRange_m;
+    if (!range || range <= 0)
+        return false;
+    // Echolocation detects physical mass (sound reflection), not life — dead entities ARE detected.
+    // Effective range: divided by noiseMul (SCALE.Q base)
+    const effectiveRange = mulDiv(range, SCALE.Q, Math.max(noiseMul, 1));
+    return dist_m <= effectiveRange;
+}
+// ── canDetectByElectroreception ───────────────────────────────────────────────
+/**
+ * Whether observer can detect subject via electroreception.
+ *
+ * - Requires `observer.extendedSenses.electroreceptionRange_m > 0`.
+ * - Detects the bioelectric field of living entities only (dead = no field).
+ * - Unaffected by any environmental modifier.
+ *
+ * @param dist_m  Distance from observer to subject [SCALE.m].
+ */
+export function canDetectByElectroreception(observer, subject, dist_m) {
+    const range = observer.extendedSenses?.electroreceptionRange_m;
+    if (!range || range <= 0)
+        return false;
+    if (subject.injury.dead)
+        return false; // no bioelectric field after death
+    return dist_m <= range;
+}
+// ── deriveScentDetection ──────────────────────────────────────────────────────
+/**
+ * Olfactory detection strength (Q 0..SCALE.Q) of subject by observer.
+ *
+ * Returns q(0) if observer has no olfaction or subject is out of scent range.
+ * Returns higher values when:
+ *   - Observer is close to subject.
+ *   - Observer is downwind of subject (wind carries scent toward observer).
+ *   - Precipitation is absent or light.
+ *
+ * @param dist_m        Distance [SCALE.m].
+ * @param wind          Optional wind field from WeatherState.
+ * @param precipitation Optional precipitation type from WeatherState.
+ */
+export function deriveScentDetection(observer, subject, dist_m, wind, precipitation) {
+    const sens = observer.extendedSenses?.olfactionSensitivity_Q;
+    if (!sens || sens <= 0)
+        return q(0);
+    if (dist_m <= 0)
+        return SCALE.Q;
+    // Base scent strength: decays with distance (q(1.0) sensitivity → detection at 50 m downwind).
+    const strength_Q = clampQ(Math.trunc(sens * OLFACTION_REF_RANGE_m / dist_m), q(0), SCALE.Q);
+    // Wind alignment: dot(subject→observer, windDir) / (dist_m × SCALE.m) ∈ [−1, +1].
+    // +1 = observer is directly downwind (scent maximally carried to observer).
+    // −1 = observer is upwind (scent blows away from observer).
+    let windMul_Q = q(0.50); // no wind → neutral (q(0.50))
+    if (wind && wind.speed_mps > 0 && dist_m > 0) {
+        const soX = observer.position_m.x - subject.position_m.x; // subject→observer
+        const soY = observer.position_m.y - subject.position_m.y;
+        const dot = soX * wind.dx_m + soY * wind.dy_m;
+        // windMul_Q ∈ [0, SCALE.Q]: 0 = full upwind, SCALE.Q = full downwind
+        windMul_Q = clampQ((5_000 + Math.trunc(dot * 5_000 / (dist_m * SCALE.m))), q(0), SCALE.Q);
+    }
+    // Precipitation disperses scent.
+    const precipMul_Q = PRECIP_SCENT_MUL[precipitation ?? "none"] ?? SCALE.Q;
+    const combined = Math.trunc(Math.trunc(strength_Q * windMul_Q / SCALE.Q) * precipMul_Q / SCALE.Q);
+    return clampQ(combined, q(0), SCALE.Q);
+}
+// ── canDetectExtended ─────────────────────────────────────────────────────────
+/**
+ * Full detection check including Phase 4 vision/hearing and Phase 52 extended modalities.
+ *
+ * Detection quality (Q) returned:
+ *   q(1.0)  — vision (primary)
+ *   q(0.8)  — electroreception (precise position, very short range)
+ *   q(0.7)  — echolocation (good spatial, darkness-independent)
+ *   q(0.4)  — hearing (Phase 4, omnidirectional)
+ *   q(0.20–0.40) — olfaction (approximate, wind/rain dependent)
+ *   q(0)    — undetected
+ *
+ * @param sensorBoost  Phase 11C sensor equipment bonus.
+ * @param wind         Optional wind for olfaction wind-alignment calculation.
+ * @param precipitation Optional precipitation for scent dispersal.
+ */
+export function canDetectExtended(observer, subject, env, sensorBoost, wind, precipitation) {
+    // Primary senses (vision + hearing, Phase 4).
+    const primary = canDetect(observer, subject, env, sensorBoost);
+    if (primary > q(0))
+        return primary;
+    // Extended senses require knowing distance.
+    const dx = subject.position_m.x - observer.position_m.x;
+    const dy = subject.position_m.y - observer.position_m.y;
+    const dz = subject.position_m.z - observer.position_m.z;
+    const dist_m = Math.trunc(Math.sqrt(dx * dx + dy * dy + dz * dz));
+    // Electroreception (highest quality after vision — very precise, very short range).
+    if (canDetectByElectroreception(observer, subject, dist_m)) {
+        return DETECT_ELECTRORECEPTION;
+    }
+    // Echolocation (good spatial awareness, works in darkness).
+    if (canDetectByEcholocation(observer, subject, dist_m, env.noiseMul)) {
+        return DETECT_ECHOLOCATION;
+    }
+    // Olfaction (approximate, wind-dependent).
+    const scent = deriveScentDetection(observer, subject, dist_m, wind, precipitation);
+    if (scent >= OLFACTION_DETECT_THRESHOLD) {
+        // Map scent strength → detection quality in [DETECT_OLFACTION_MIN, DETECT_OLFACTION_MAX].
+        return clampQ(Math.trunc(scent * (DETECT_OLFACTION_MAX - DETECT_OLFACTION_MIN) / SCALE.Q + DETECT_OLFACTION_MIN), DETECT_OLFACTION_MIN, DETECT_OLFACTION_MAX);
+    }
+    return q(0);
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Phase 4: Sensory environment model.
+ *
+ * Fixed-point only. No Math.random() — all randomness via eventSeed if needed.
+ * Light, smoke, and noise modifiers are Q values (SCALE.Q = full normal conditions).
+ */
+import type { Q } from "../units.js";
+import type { Entity } from "./entity.js";
+import type { Perception } from "../types.js";
+export declare const DEFAULT_PERCEPTION: Perception;
+export interface SensoryEnvironment {
+    /** Multiplier on vision range: q(1.0) = daylight, q(0.1) = near-dark. */
+    lightMul: Q;
+    /** Multiplier on vision range: q(1.0) = clear, q(0.2) = dense smoke. */
+    smokeMul: Q;
+    /** Multiplier on hearing range: q(1.0) = quiet, q(2.0) = loud battle noise. */
+    noiseMul: Q;
+}
+export declare const DEFAULT_SENSORY_ENV: SensoryEnvironment;
+/**
+ * Compute detection quality of `subject` by `observer`.
+ *
+ * Returns a Q value:
+ *   q(1.0) = fully visible (within vision arc and range)
+ *   q(0.4) = heard only (within hearing range but not vision)
+ *   q(0)   = undetected
+ *
+ * Vision check: dot-product of facing direction vs observer→subject vector.
+ * Hearing: omnidirectional.
+ *
+ * Pure function — no side effects.
+ */
+export declare function canDetect(observer: Entity, subject: Entity, env: SensoryEnvironment, 
+/** Phase 11C: optional sensor boost from the observer's loadout. */
+sensorBoost?: {
+    visionRangeMul: Q;
+    hearingRangeMul: Q;
+}): Q;