@its-not-rocket-science/ananke 0.1.55 → 0.1.57

package/CHANGELOG.md

@@ -6,6 +6,45 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.57] — 2026-03-30
+
+### Added
+
+- **PA-8 — Host Integration SDKs (complete):**
+  - `src/host-loop.ts` (new): stable, versioned wire-format protocol for the Ananke sidecar ↔ renderer bridge. All values on the wire are real SI units (floats, not fixed-point).
+    - **Wire types**: `BridgeVec3`, `BridgeCondition`, `BridgeAnimation`, `BridgePoseModifier`, `BridgeGrappleConstraint`, `BridgeEntitySnapshot`, `BridgeFrame`, `HostLoopConfig`.
+    - **`serializeBridgeFrame(world, config)`**: canonical serializer — converts `WorldState` to `BridgeFrame`. Replaces per-sidecar serializer duplications in Unity and Godot reference implementations.
+    - **`derivePrimaryState(animation)`**: maps `AnimationHints` to a single state string (`"idle"` | `"attack"` | `"flee"` | `"prone"` | `"unconscious"` | `"dead"`). Suitable for top-level renderer state machines.
+    - **`derivePoseOffset(segmentId, impairmentQ)`**: anatomical local-space bone offset at a given impairment level (real metres), for injury deformation blend shapes.
+    - Constants: `BRIDGE_SCHEMA_VERSION = "ananke.bridge.frame.v1"`, `DEFAULT_TICK_HZ = 20`, `DEFAULT_BRIDGE_PORT = 3001`, `DEFAULT_BRIDGE_HOST`, `DEFAULT_STREAM_PATH`.
+  - `"./host-loop"` subpath export added to `package.json`.
+  - **Reference sidecar updates**: both `ananke-unity-reference` and `ananke-godot-reference` sidecars updated to v0.1.57 dependency and refactored to import `serializeBridgeFrame` from `@its-not-rocket-science/ananke/host-loop` — local serialization code removed.
+  - **Quickstart guides** (new):
+    - `docs/quickstart-unity.md`: 15-minute Unity integration guide (sidecar → WebSocket → `AnankeReceiver` → `AnimationDriver` → your mesh).
+    - `docs/quickstart-godot.md`: 15-minute Godot 4 integration guide (GDScript and C# addon variants).
+    - `docs/quickstart-web.md`: Three.js browser integration guide (zero-build-step HTML example + `serializeBridgeFrame` sidecar recipe).
+- 41 new tests (188 test files, 5,553 tests total). Coverage: 97.10% stmt, 88.05% branch, 95.81% func. Build: clean.
+
+---
+
+## [0.1.56] — 2026-03-30
+
+### Added
+
+- **PA-7 — Advanced Non-Visual Sensory Systems (complete):**
+  - `src/sim/sensory-extended.ts`: added `thermalVisionRange_m?: number` to `ExtendedSenses` interface — fourth modality alongside echolocation, electroreception, and olfaction. Effective range scales with target thermal signature; degraded by precipitation; dead entities have no thermal signature.
+  - `src/extended-senses.ts` (new): unified extended-senses module with `AtmosphericState` integration (PA-6).
+    - Body-plan predicates: `hasEcholocation`, `hasElectroreception`, `hasThermalVision`, `hasOlfaction`, `dominantSense` (priority: electroreception > echolocation > thermal > olfaction > vision).
+    - `thermalSignature(entity)` → Q: dead=q(0); living=base q(0.30) + q(0.10) per bleeding region + q(0.15) if shock≥q(0.40).
+    - `canDetectByThermalVision(observer, subject, dist_m, precipIntensity?)`: effective range = baseRange × signature / SCALE.Q × (1 − precipIntensity × 0.60). Detection quality `DETECT_THERMAL = q(0.35)`.
+    - `canDetectExtendedAtmospheric(observer, subject, env, atmospheric, sensorBoost?)`: drop-in replacement for Phase 52 `canDetectExtended` that uses `AtmosphericState.scentStrength_Q` from `queryAtmosphericModifiers` for olfaction, and `precipIntensity_Q` for thermal attenuation.
+    - `stepExtendedSenses(observer, world, atmospheric, env)` → `ExtendedSensesResult { detections }`: per-tick batch detection accumulator; iterates all world entities, checks all four extended modalities, returns `SensoryDetection[]` with `entityId`, `modality`, `quality_Q`, `dist_Sm`. Multiple detections per target are possible.
+  - Exports: `SenseModality`, `SensoryDetection`, `ExtendedSensesResult`, `THERMAL_BASE_SIGNATURE_Q`, `THERMAL_BLEED_BONUS_Q`, `THERMAL_SHOCK_BONUS_Q`, `THERMAL_SHOCK_THRESHOLD`, `THERMAL_PRECIP_PENALTY`, `DETECT_THERMAL`, `DETECT_OLFACTION_ATMO_MIN`, `DETECT_OLFACTION_ATMO_MAX`.
+  - `"./extended-senses"` subpath export added to `package.json`.
+- 60 new tests (187 test files, 5,512 tests total). Build: clean.
+
+---
+
 ## [0.1.55] — 2026-03-30
 
 ### Added

package/dist/src/extended-senses.d.ts

@@ -0,0 +1,146 @@
+import { type Q } from "./units.js";
+import type { Entity } from "./sim/entity.js";
+import type { WorldState } from "./sim/world.js";
+import type { SensoryEnvironment } from "./sim/sensory.js";
+import { type AtmosphericState } from "./atmosphere.js";
+/** Sensory modality used for a detection. */
+export type SenseModality = "vision" | "echolocation" | "electroreception" | "olfaction" | "thermal";
+/**
+ * A single detected entity and the sense used to detect it.
+ *
+ * Multiple detections for the same `entityId` are possible (e.g. a close
+ * target may be detected by both olfaction and echolocation).  Callers should
+ * take the maximum `quality_Q` per entity for targeting decisions.
+ */
+export interface SensoryDetection {
+    /** Id of the detected entity. */
+    entityId: number;
+    /** Modality that produced this detection. */
+    modality: SenseModality;
+    /**
+     * Detection quality [Q 0..SCALE.Q].
+     * Higher = more precise positional information.
+     * q(0.80) = electroreception; q(0.70) = echolocation; q(0.40) = olfaction/thermal.
+     */
+    quality_Q: Q;
+    /** Distance from observer to detected entity [SCALE.m]. */
+    dist_Sm: number;
+}
+/** Result of a `stepExtendedSenses` call. */
+export interface ExtendedSensesResult {
+    /** All detections produced this tick. May be empty. */
+    detections: SensoryDetection[];
+}
+/** Thermal signature of a living entity at rest [Q]. */
+export declare const THERMAL_BASE_SIGNATURE_Q: Q;
+/**
+ * Additional thermal signature per bleeding body region [Q].
+ * Warm blood on the surface raises infrared contrast.
+ */
+export declare const THERMAL_BLEED_BONUS_Q: Q;
+/**
+ * Additional thermal signature when entity shock exceeds `THERMAL_SHOCK_THRESHOLD`.
+ * Fever and inflammation elevate core temperature.
+ */
+export declare const THERMAL_SHOCK_BONUS_Q: Q;
+/** Shock level [Q] above which a fever/inflammatory bonus applies. */
+export declare const THERMAL_SHOCK_THRESHOLD: Q;
+/**
+ * Precipitation reduces effective thermal range.
+ * At precipIntensity_Q = SCALE.Q: range × (1 - THERMAL_PRECIP_PENALTY).
+ */
+export declare const THERMAL_PRECIP_PENALTY: Q;
+/** Detection quality returned for thermal detections. */
+export declare const DETECT_THERMAL: Q;
+/** Minimum olfaction detection quality when atmospheric scentStrength_Q is q(1.0). */
+export declare const DETECT_OLFACTION_ATMO_MIN: Q;
+/** Maximum olfaction detection quality. */
+export declare const DETECT_OLFACTION_ATMO_MAX: Q;
+/** Returns `true` if the entity has echolocation capability. */
+export declare function hasEcholocation(entity: Entity): boolean;
+/** Returns `true` if the entity has electroreception capability. */
+export declare function hasElectroreception(entity: Entity): boolean;
+/** Returns `true` if the entity has thermal (infrared) vision. */
+export declare function hasThermalVision(entity: Entity): boolean;
+/** Returns `true` if the entity has olfaction (scent) capability. */
+export declare function hasOlfaction(entity: Entity): boolean;
+/**
+ * Returns the entity's dominant non-visual sense.
+ *
+ * Priority: electroreception > echolocation > thermal > olfaction > vision.
+ *
+ * Use this to steer AI targeting logic:
+ * - `"echolocation"` → entity can hunt in total darkness.
+ * - `"electroreception"` → entity detects living creatures at close range
+ *   regardless of light, noise, or scent.
+ * - `"thermal"` → entity detects warm-bodied prey by heat signature.
+ * - `"olfaction"` → entity tracks prey by scent trail (wind-dependent).
+ * - `"vision"` → standard visual detection (default).
+ */
+export declare function dominantSense(entity: Entity): SenseModality;
+/**
+ * Compute the thermal signature of an entity [Q 0..SCALE.Q].
+ *
+ * Dead entities return q(0) — no remaining metabolic heat.
+ * Living entities radiate at least `THERMAL_BASE_SIGNATURE_Q`.
+ * Active bleeding and fever raise the signature further.
+ */
+export declare function thermalSignature(entity: Entity): Q;
+/**
+ * Whether observer can detect subject via thermal (infrared) vision.
+ *
+ * - Requires `observer.extendedSenses.thermalVisionRange_m > 0`.
+ * - Dead entities have no thermal signature and are not detected.
+ * - Effective range: `thermalVisionRange_m × signature_Q / SCALE.Q`,
+ *   further reduced by precipitation (`THERMAL_PRECIP_PENALTY`).
+ * - Unaffected by ambient light or noise.
+ *
+ * @param dist_m          Distance from observer to subject [SCALE.m].
+ * @param precipIntensity Precipitation intensity [Q 0..SCALE.Q] from AtmosphericState.
+ */
+export declare function canDetectByThermalVision(observer: Entity, subject: Entity, dist_m: number, precipIntensity?: Q): boolean;
+/**
+ * Full detection check using all four extended modalities, with `AtmosphericState`
+ * integration for olfaction and thermal.
+ *
+ * Returns best detection quality [Q] across all active senses:
+ * - q(1.0):       vision (Phase 4)
+ * - q(0.80):      electroreception
+ * - q(0.70):      echolocation
+ * - q(0.20–0.40): olfaction (atmospheric, wind/precip dependent)
+ * - q(0.35):      thermal (heat-signature dependent)
+ * - q(0):         undetected
+ *
+ * Use this as a drop-in replacement for `canDetectExtended` when an
+ * `AtmosphericState` is available.
+ */
+export declare function canDetectExtendedAtmospheric(observer: Entity, subject: Entity, env: SensoryEnvironment, atmospheric: AtmosphericState, sensorBoost?: {
+    visionRangeMul: Q;
+    hearingRangeMul: Q;
+}): Q;
+/**
+ * Accumulate all extended-sense detections for one observer entity.
+ *
+ * Iterates all entities in `world`, skips the observer itself, and for each
+ * other entity checks all four extended modalities.  Multiple detections per
+ * target are possible and are all returned (callers take the max quality).
+ *
+ * Visual and hearing detection is **not** included — use `canDetect` (Phase 4)
+ * or `canDetectExtendedAtmospheric` for full detection checks.
+ *
+ * @param observer    The sensing entity.
+ * @param world       Current world state (iterated for targets).
+ * @param atmospheric Atmospheric state from `deriveAtmosphericState` (PA-6).
+ * @param env         Sensory environment for echolocation noise level.
+ * @returns           All detections this tick (may be empty).
+ *
+ * @example
+ * ```ts
+ * const atmo = deriveAtmosphericState(ctx.weather, ctx.biome);
+ * const result = stepExtendedSenses(bat, world, atmo, ctx.sensoryEnv ?? DEFAULT_SENSORY_ENV);
+ * for (const det of result.detections) {
+ *   // det.entityId, det.modality, det.quality_Q, det.dist_Sm
+ * }
+ * ```
+ */
+export declare function stepExtendedSenses(observer: Entity, world: WorldState, atmospheric: AtmosphericState, env: SensoryEnvironment): ExtendedSensesResult;

package/dist/src/extended-senses.js

@@ -0,0 +1,310 @@
+// src/extended-senses.ts — PA-7: Advanced Non-Visual Sensory Systems
+//
+// Extends Phase 52 (sensory-extended.ts) with:
+//   - Thermal (infrared) detection — 4th modality alongside echolocation,
+//     electroreception, and olfaction.
+//   - stepExtendedSenses(entity, world, atmospheric, env) — batch per-tick
+//     detection accumulator returning structured results per modality.
+//   - AtmosphericState integration — olfaction uses scentStrength_Q from
+//     queryAtmosphericModifiers (PA-6) rather than re-computing wind alignment.
+//   - Body-plan predicates: hasEcholocation, hasElectroreception,
+//     hasThermalVision, hasOlfaction, dominantSense.
+//
+// Compatibility: fully additive — does not modify the Phase 52 API.  Hosts
+// can replace calls to canDetectExtended with canDetectExtendedAtmospheric
+// for unified atmospheric integration, or continue using Phase 52 directly.
+import { SCALE, q, clampQ, mulDiv } from "./units.js";
+import { canDetect } from "./sim/sensory.js";
+import { canDetectByEcholocation, canDetectByElectroreception, DETECT_ECHOLOCATION, DETECT_ELECTRORECEPTION, } from "./sim/sensory-extended.js";
+import { queryAtmosphericModifiers, } from "./atmosphere.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Thermal signature of a living entity at rest [Q]. */
+export const THERMAL_BASE_SIGNATURE_Q = q(0.30);
+/**
+ * Additional thermal signature per bleeding body region [Q].
+ * Warm blood on the surface raises infrared contrast.
+ */
+export const THERMAL_BLEED_BONUS_Q = q(0.10);
+/**
+ * Additional thermal signature when entity shock exceeds `THERMAL_SHOCK_THRESHOLD`.
+ * Fever and inflammation elevate core temperature.
+ */
+export const THERMAL_SHOCK_BONUS_Q = q(0.15);
+/** Shock level [Q] above which a fever/inflammatory bonus applies. */
+export const THERMAL_SHOCK_THRESHOLD = q(0.40);
+/**
+ * Precipitation reduces effective thermal range.
+ * At precipIntensity_Q = SCALE.Q: range × (1 - THERMAL_PRECIP_PENALTY).
+ */
+export const THERMAL_PRECIP_PENALTY = q(0.60);
+/** Detection quality returned for thermal detections. */
+export const DETECT_THERMAL = q(0.35);
+/** Minimum olfaction detection quality when atmospheric scentStrength_Q is q(1.0). */
+export const DETECT_OLFACTION_ATMO_MIN = q(0.20);
+/** Maximum olfaction detection quality. */
+export const DETECT_OLFACTION_ATMO_MAX = q(0.40);
+// ── Body-plan predicates ──────────────────────────────────────────────────────
+/** Returns `true` if the entity has echolocation capability. */
+export function hasEcholocation(entity) {
+    return (entity.extendedSenses?.echolocationRange_m ?? 0) > 0;
+}
+/** Returns `true` if the entity has electroreception capability. */
+export function hasElectroreception(entity) {
+    return (entity.extendedSenses?.electroreceptionRange_m ?? 0) > 0;
+}
+/** Returns `true` if the entity has thermal (infrared) vision. */
+export function hasThermalVision(entity) {
+    return (entity.extendedSenses?.thermalVisionRange_m ?? 0) > 0;
+}
+/** Returns `true` if the entity has olfaction (scent) capability. */
+export function hasOlfaction(entity) {
+    return (entity.extendedSenses?.olfactionSensitivity_Q ?? 0) > 0;
+}
+/**
+ * Returns the entity's dominant non-visual sense.
+ *
+ * Priority: electroreception > echolocation > thermal > olfaction > vision.
+ *
+ * Use this to steer AI targeting logic:
+ * - `"echolocation"` → entity can hunt in total darkness.
+ * - `"electroreception"` → entity detects living creatures at close range
+ *   regardless of light, noise, or scent.
+ * - `"thermal"` → entity detects warm-bodied prey by heat signature.
+ * - `"olfaction"` → entity tracks prey by scent trail (wind-dependent).
+ * - `"vision"` → standard visual detection (default).
+ */
+export function dominantSense(entity) {
+    if (hasElectroreception(entity))
+        return "electroreception";
+    if (hasEcholocation(entity))
+        return "echolocation";
+    if (hasThermalVision(entity))
+        return "thermal";
+    if (hasOlfaction(entity))
+        return "olfaction";
+    return "vision";
+}
+// ── Thermal detection ─────────────────────────────────────────────────────────
+/**
+ * Compute the thermal signature of an entity [Q 0..SCALE.Q].
+ *
+ * Dead entities return q(0) — no remaining metabolic heat.
+ * Living entities radiate at least `THERMAL_BASE_SIGNATURE_Q`.
+ * Active bleeding and fever raise the signature further.
+ */
+export function thermalSignature(entity) {
+    if (entity.injury?.dead)
+        return q(0);
+    let sig = THERMAL_BASE_SIGNATURE_Q;
+    // Bleeding: each bleeding region raises infrared contrast (warm blood visible)
+    if (entity.injury !== undefined) {
+        for (const region of Object.values(entity.injury.byRegion)) {
+            if (region.bleedingRate > 0) {
+                sig += THERMAL_BLEED_BONUS_Q;
+            }
+        }
+    }
+    // Fever / high shock: inflammation raises skin temperature
+    if ((entity.injury?.shock ?? 0) >= THERMAL_SHOCK_THRESHOLD) {
+        sig += THERMAL_SHOCK_BONUS_Q;
+    }
+    return clampQ(Math.round(sig), q(0), SCALE.Q);
+}
+/**
+ * Whether observer can detect subject via thermal (infrared) vision.
+ *
+ * - Requires `observer.extendedSenses.thermalVisionRange_m > 0`.
+ * - Dead entities have no thermal signature and are not detected.
+ * - Effective range: `thermalVisionRange_m × signature_Q / SCALE.Q`,
+ *   further reduced by precipitation (`THERMAL_PRECIP_PENALTY`).
+ * - Unaffected by ambient light or noise.
+ *
+ * @param dist_m          Distance from observer to subject [SCALE.m].
+ * @param precipIntensity Precipitation intensity [Q 0..SCALE.Q] from AtmosphericState.
+ */
+export function canDetectByThermalVision(observer, subject, dist_m, precipIntensity) {
+    const baseRange = observer.extendedSenses?.thermalVisionRange_m;
+    if (!baseRange || baseRange <= 0)
+        return false;
+    if (subject.injury?.dead)
+        return false;
+    const sig = thermalSignature(subject);
+    if (sig <= 0)
+        return false;
+    // Signature scales effective range (high-signature targets detectable at greater range)
+    const sigRange = mulDiv(baseRange, sig, SCALE.Q);
+    // Precipitation attenuates thermal radiation
+    const precipPenalty = precipIntensity !== undefined
+        ? mulDiv(THERMAL_PRECIP_PENALTY, precipIntensity, SCALE.Q)
+        : 0;
+    const precipMul = Math.max(0, SCALE.Q - precipPenalty);
+    const effectiveRange = mulDiv(sigRange, precipMul, SCALE.Q);
+    return dist_m <= effectiveRange;
+}
+// ── Atmospheric olfaction ─────────────────────────────────────────────────────
+/**
+ * Compute olfaction detection quality using pre-computed atmospheric context.
+ *
+ * Replaces calling `deriveScentDetection` when an `AtmosphericState` is
+ * available — uses `scentStrength_Q` from `queryAtmosphericModifiers` instead
+ * of independently re-computing wind alignment.
+ *
+ * @returns Q quality ∈ [0, DETECT_OLFACTION_ATMO_MAX].
+ */
+function _olfactionQualityAtmospheric(observer, subject, dist_m, scentStrength_Q, precipIntensity_Q) {
+    const sens = observer.extendedSenses?.olfactionSensitivity_Q;
+    if (!sens || sens <= 0)
+        return q(0);
+    if (dist_m <= 0)
+        return DETECT_OLFACTION_ATMO_MAX;
+    // Reference range: q(1.0) sensitivity detects at 50 m downwind (500 000 Sm)
+    const REF_RANGE_m = 50 * SCALE.m;
+    const distStrength = clampQ(Math.trunc(sens * REF_RANGE_m / dist_m), q(0), SCALE.Q);
+    // Wind alignment from atmospheric (scentStrength_Q from PA-6)
+    // Precipitation dispersal (q(0) intensity = no dispersal; q(1.0) = 60% reduction)
+    const precipDisperse = Math.max(q(0.20), SCALE.Q - Math.round(precipIntensity_Q * 8_000 / SCALE.Q));
+    const combined = Math.trunc(Math.trunc(distStrength * scentStrength_Q / SCALE.Q) * precipDisperse / SCALE.Q);
+    if (combined < DETECT_OLFACTION_ATMO_MIN)
+        return q(0);
+    return clampQ(combined, DETECT_OLFACTION_ATMO_MIN, DETECT_OLFACTION_ATMO_MAX);
+}
+// ── canDetectExtendedAtmospheric ──────────────────────────────────────────────
+/**
+ * Full detection check using all four extended modalities, with `AtmosphericState`
+ * integration for olfaction and thermal.
+ *
+ * Returns best detection quality [Q] across all active senses:
+ * - q(1.0):       vision (Phase 4)
+ * - q(0.80):      electroreception
+ * - q(0.70):      echolocation
+ * - q(0.20–0.40): olfaction (atmospheric, wind/precip dependent)
+ * - q(0.35):      thermal (heat-signature dependent)
+ * - q(0):         undetected
+ *
+ * Use this as a drop-in replacement for `canDetectExtended` when an
+ * `AtmosphericState` is available.
+ */
+export function canDetectExtendedAtmospheric(observer, subject, env, atmospheric, sensorBoost) {
+    // Phase 4 vision + hearing (existing canDetect)
+    const primary = canDetect(observer, subject, env, sensorBoost);
+    if (primary > q(0))
+        return primary;
+    // Distance (integer sqrt over 3D position)
+    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
+    if (canDetectByElectroreception(observer, subject, dist_m)) {
+        return DETECT_ELECTRORECEPTION;
+    }
+    // Echolocation — use atmospheric noiseMul if available
+    // acousticMaskMul_Q → inverse of noiseMul: q(1.0) = normal noise, lower = quieter
+    // Existing canDetectByEcholocation takes noiseMul directly from env
+    if (canDetectByEcholocation(observer, subject, dist_m, env.noiseMul)) {
+        return DETECT_ECHOLOCATION;
+    }
+    // Thermal detection
+    if (canDetectByThermalVision(observer, subject, dist_m, atmospheric.precipIntensity_Q)) {
+        return DETECT_THERMAL;
+    }
+    // Olfaction (atmospheric integration)
+    const from2d = { x_Sm: observer.position_m.x, y_Sm: observer.position_m.y };
+    const to2d = { x_Sm: subject.position_m.x, y_Sm: subject.position_m.y };
+    const mods = queryAtmosphericModifiers(from2d, to2d, atmospheric);
+    const olfactionQ = _olfactionQualityAtmospheric(observer, subject, dist_m, mods.scentStrength_Q, atmospheric.precipIntensity_Q);
+    if (olfactionQ > q(0))
+        return olfactionQ;
+    return q(0);
+}
+// ── stepExtendedSenses ────────────────────────────────────────────────────────
+/**
+ * Accumulate all extended-sense detections for one observer entity.
+ *
+ * Iterates all entities in `world`, skips the observer itself, and for each
+ * other entity checks all four extended modalities.  Multiple detections per
+ * target are possible and are all returned (callers take the max quality).
+ *
+ * Visual and hearing detection is **not** included — use `canDetect` (Phase 4)
+ * or `canDetectExtendedAtmospheric` for full detection checks.
+ *
+ * @param observer    The sensing entity.
+ * @param world       Current world state (iterated for targets).
+ * @param atmospheric Atmospheric state from `deriveAtmosphericState` (PA-6).
+ * @param env         Sensory environment for echolocation noise level.
+ * @returns           All detections this tick (may be empty).
+ *
+ * @example
+ * ```ts
+ * const atmo = deriveAtmosphericState(ctx.weather, ctx.biome);
+ * const result = stepExtendedSenses(bat, world, atmo, ctx.sensoryEnv ?? DEFAULT_SENSORY_ENV);
+ * for (const det of result.detections) {
+ *   // det.entityId, det.modality, det.quality_Q, det.dist_Sm
+ * }
+ * ```
+ */
+export function stepExtendedSenses(observer, world, atmospheric, env) {
+    const detections = [];
+    const hasEcho = hasEcholocation(observer);
+    const hasElec = hasElectroreception(observer);
+    const hasThermal = hasThermalVision(observer);
+    const hasOlf = hasOlfaction(observer);
+    // Early-out if observer has no extended senses
+    if (!hasEcho && !hasElec && !hasThermal && !hasOlf) {
+        return { detections };
+    }
+    const obsX = observer.position_m.x;
+    const obsY = observer.position_m.y;
+    const obsZ = observer.position_m.z;
+    for (const subject of world.entities) {
+        if (subject.id === observer.id)
+            continue;
+        const dx = subject.position_m.x - obsX;
+        const dy = subject.position_m.y - obsY;
+        const dz = subject.position_m.z - obsZ;
+        const dist_m = Math.trunc(Math.sqrt(dx * dx + dy * dy + dz * dz));
+        // Electroreception
+        if (hasElec && canDetectByElectroreception(observer, subject, dist_m)) {
+            detections.push({
+                entityId: subject.id,
+                modality: "electroreception",
+                quality_Q: DETECT_ELECTRORECEPTION,
+                dist_Sm: dist_m,
+            });
+        }
+        // Echolocation
+        if (hasEcho && canDetectByEcholocation(observer, subject, dist_m, env.noiseMul)) {
+            detections.push({
+                entityId: subject.id,
+                modality: "echolocation",
+                quality_Q: DETECT_ECHOLOCATION,
+                dist_Sm: dist_m,
+            });
+        }
+        // Thermal
+        if (hasThermal && canDetectByThermalVision(observer, subject, dist_m, atmospheric.precipIntensity_Q)) {
+            detections.push({
+                entityId: subject.id,
+                modality: "thermal",
+                quality_Q: DETECT_THERMAL,
+                dist_Sm: dist_m,
+            });
+        }
+        // Olfaction (atmospheric integration)
+        if (hasOlf) {
+            const from2d = { x_Sm: obsX, y_Sm: obsY };
+            const to2d = { x_Sm: subject.position_m.x, y_Sm: subject.position_m.y };
+            const mods = queryAtmosphericModifiers(from2d, to2d, atmospheric);
+            const q_olf = _olfactionQualityAtmospheric(observer, subject, dist_m, mods.scentStrength_Q, atmospheric.precipIntensity_Q);
+            if (q_olf > q(0)) {
+                detections.push({
+                    entityId: subject.id,
+                    modality: "olfaction",
+                    quality_Q: q_olf,
+                    dist_Sm: dist_m,
+                });
+            }
+        }
+    }
+    return { detections };
+}

package/dist/src/host-loop.d.ts

@@ -0,0 +1,188 @@
+import type { WorldState } from "./sim/world.js";
+import { type AnimationHints } from "./model3d.js";
+/** Wire schema identifier — included in every BridgeFrame. */
+export declare const BRIDGE_SCHEMA_VERSION: "ananke.bridge.frame.v1";
+/** Default sidecar tick rate (Hz). */
+export declare const DEFAULT_TICK_HZ = 20;
+/** Default sidecar WebSocket/HTTP port. */
+export declare const DEFAULT_BRIDGE_PORT = 3001;
+/** Default sidecar host. */
+export declare const DEFAULT_BRIDGE_HOST = "127.0.0.1";
+/** Default WebSocket stream path. */
+export declare const DEFAULT_STREAM_PATH = "/stream";
+/**
+ * 3D vector in real metres (float).
+ * Converts from fixed-point SCALE.m: `x_m = x_Sm / SCALE.m`.
+ */
+export interface BridgeVec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Entity physiological condition (Q-values as [0, 1] floats).
+ * Divide the underlying Q value by SCALE.Q (10 000) to get floats.
+ */
+export interface BridgeCondition {
+    /** Shock intensity. q(0) = no shock; q(1.0) = incapacitating. */
+    shockQ: number;
+    /** Fear intensity. q(0) = calm; q(1.0) = panic. */
+    fearQ: number;
+    /** Consciousness level. q(0) = unconscious; q(1.0) = fully alert. */
+    consciousnessQ: number;
+    /** Cumulative fluid loss. q(0) = none; q(1.0) = lethal. */
+    fluidLossQ: number;
+    /** True if the entity is clinically dead. */
+    dead: boolean;
+}
+/**
+ * Animation blend weights and state flags for a renderer character controller.
+ * All Q-values are [0, 1] floats.
+ *
+ * Locomotive blends are mutually exclusive; typically only one is nonzero.
+ */
+export interface BridgeAnimation {
+    idle: number;
+    walk: number;
+    run: number;
+    sprint: number;
+    crawl: number;
+    guardingQ: number;
+    attackingQ: number;
+    shockQ: number;
+    fearQ: number;
+    prone: boolean;
+    unconscious: boolean;
+    dead: boolean;
+    /** Dominant animation state as a single string (see `derivePrimaryState`). */
+    primaryState: string;
+    /** Max locomotion blend weight — useful for speed-parameterised blend trees. */
+    locomotionBlend: number;
+    /** Worst-case injury deformation weight across all body segments. */
+    injuryWeight: number;
+}
+/**
+ * Per-body-segment pose modifier — drives deformation or damage blend shapes.
+ * Q-values are [0, 1] floats.
+ */
+export interface BridgePoseModifier {
+    segmentId: string;
+    /** Overall deformation blend: max(structuralQ, surfaceQ). */
+    impairmentQ: number;
+    structuralQ: number;
+    surfaceQ: number;
+    /**
+     * Anatomical offset for this segment at full impairment, in real metres.
+     * Apply to the bone's local position to show slumping/collapse.
+     */
+    localOffset_m: BridgeVec3;
+}
+/**
+ * Grapple constraint describing hold/held relationships between entities.
+ */
+export interface BridgeGrappleConstraint {
+    isHolder: boolean;
+    holdingEntityId: number;
+    isHeld: boolean;
+    heldByIds: number[];
+    /** Grapple positional state. */
+    position: "standing" | "prone" | "pinned" | "mounted";
+    /** Grip strength [0, 1]. */
+    gripQ: number;
+}
+/**
+ * Complete per-entity snapshot for one simulation tick.
+ */
+export interface BridgeEntitySnapshot {
+    entityId: number;
+    teamId: number;
+    tick: number;
+    /** World position in real metres. */
+    position_m: BridgeVec3;
+    /** Velocity in real m/s. */
+    velocity_mps: BridgeVec3;
+    /** Normalised facing direction (unit vector). */
+    facing: BridgeVec3;
+    /** Mass in real kg. */
+    massKg: number;
+    /** Centre-of-gravity offset from foot position (real metres). */
+    cogOffset_m: {
+        x: number;
+        y: number;
+    };
+    animation: BridgeAnimation;
+    pose: BridgePoseModifier[];
+    grapple: BridgeGrappleConstraint;
+    condition: BridgeCondition;
+}
+/**
+ * Complete serialized frame for one simulation tick.
+ * JSON-encoded and sent over WebSocket / HTTP.
+ */
+export interface BridgeFrame {
+    /** Fixed schema identifier — check this before deserializing. */
+    schema: typeof BRIDGE_SCHEMA_VERSION;
+    scenarioId: string;
+    tick: number;
+    tickHz: number;
+    /** ISO 8601 generation timestamp — for latency diagnostics only. */
+    generatedAt: string;
+    entities: BridgeEntitySnapshot[];
+}
+/**
+ * Sidecar configuration — passed to `serializeBridgeFrame` and used by
+ * host loop implementations.
+ */
+export interface HostLoopConfig {
+    /** Stable identifier for this scenario (e.g. `"knight-vs-brawler"`). */
+    scenarioId: string;
+    /** Simulation tick rate in Hz. Default: `DEFAULT_TICK_HZ` (20). */
+    tickHz?: number;
+    /** Listening port. Default: `DEFAULT_BRIDGE_PORT` (3001). */
+    port?: number;
+    /** Listening host. Default: `DEFAULT_BRIDGE_HOST`. */
+    host?: string;
+}
+/**
+ * Derive a single animation state string from `AnimationHints`.
+ *
+ * Priority: dead > unconscious > prone/crawl > attack > flee (run/sprint) > idle.
+ * Renderer character controllers use this to drive top-level state machines
+ * when a detailed blend tree is not available.
+ *
+ * @returns One of: `"dead"` | `"unconscious"` | `"prone"` | `"attack"` | `"flee"` | `"idle"`
+ */
+export declare function derivePrimaryState(animation: AnimationHints): string;
+/**
+ * Anatomical local-space offset for a body segment at maximum impairment.
+ *
+ * Applied as: `bone.localPosition += poseOffset * impairmentQ`.
+ * Values are in real metres (float).
+ *
+ * @param segmentId   Canonical segment identifier (e.g. `"head"`, `"leftArm"`).
+ * @param impairmentQ Impairment blend weight [0, 1] float.
+ * @returns Local-space offset in real metres.
+ */
+export declare function derivePoseOffset(segmentId: string, impairmentQ: number): BridgeVec3;
+/**
+ * Serialize a complete simulation tick into the stable bridge wire format.
+ *
+ * This is the canonical sidecar serializer.  Replaces per-project
+ * `serialiseFrame` implementations in Unity and Godot sidecars.
+ *
+ * @param world   Current world state after `stepWorld()`.
+ * @param config  Sidecar configuration.
+ * @returns       A `BridgeFrame` safe to `JSON.stringify` and send over WebSocket.
+ *
+ * @example
+ * ```ts
+ * import { serializeBridgeFrame } from "@its-not-rocket-science/ananke/host-loop";
+ *
+ * function tick() {
+ *   stepWorld(world, commands, ctx);
+ *   const frame = serializeBridgeFrame(world, { scenarioId: "my-duel", tickHz: 20 });
+ *   broadcast(JSON.stringify(frame));
+ * }
+ * ```
+ */
+export declare function serializeBridgeFrame(world: WorldState, config: HostLoopConfig): BridgeFrame;

package/dist/src/host-loop.js

@@ -0,0 +1,185 @@
+// src/host-loop.ts — PA-8: Host Integration Bridge Protocol
+//
+// Stable, versioned wire format for the Ananke sidecar ↔ renderer bridge.
+// All values on the wire are in real SI units (floats).
+//
+// Usage in a sidecar:
+//   import { serializeBridgeFrame, HostLoopConfig } from "@ananke/host-loop";
+//
+// Usage in a renderer client (Unity, Godot, Web):
+//   const frame: BridgeFrame = JSON.parse(rawWebSocketMessage);
+//   // field names and types are stable across minor versions
+//
+// Schema version string: BRIDGE_SCHEMA_VERSION.
+// Increment the version suffix (v1 → v2) only on breaking wire changes.
+import { SCALE, q, clampQ, qMul } from "./units.js";
+import { deriveAnimationHints, derivePoseModifiers, deriveGrappleConstraint, deriveMassDistribution, } from "./model3d.js";
+// ── Protocol constants ─────────────────────────────────────────────────────────
+/** Wire schema identifier — included in every BridgeFrame. */
+export const BRIDGE_SCHEMA_VERSION = "ananke.bridge.frame.v1";
+/** Default sidecar tick rate (Hz). */
+export const DEFAULT_TICK_HZ = 20;
+/** Default sidecar WebSocket/HTTP port. */
+export const DEFAULT_BRIDGE_PORT = 3001;
+/** Default sidecar host. */
+export const DEFAULT_BRIDGE_HOST = "127.0.0.1";
+/** Default WebSocket stream path. */
+export const DEFAULT_STREAM_PATH = "/stream";
+// ── Primary state derivation ──────────────────────────────────────────────────
+/**
+ * Derive a single animation state string from `AnimationHints`.
+ *
+ * Priority: dead > unconscious > prone/crawl > attack > flee (run/sprint) > idle.
+ * Renderer character controllers use this to drive top-level state machines
+ * when a detailed blend tree is not available.
+ *
+ * @returns One of: `"dead"` | `"unconscious"` | `"prone"` | `"attack"` | `"flee"` | `"idle"`
+ */
+export function derivePrimaryState(animation) {
+    if (animation.dead)
+        return "dead";
+    if (animation.unconscious)
+        return "unconscious";
+    if (animation.prone || animation.crawl > 0)
+        return "prone";
+    if (animation.attackingQ > 0)
+        return "attack";
+    if (animation.sprint > 0 || animation.run > 0)
+        return "flee";
+    return "idle";
+}
+// ── Pose offset per segment ───────────────────────────────────────────────────
+/**
+ * Anatomical local-space offset for a body segment at maximum impairment.
+ *
+ * Applied as: `bone.localPosition += poseOffset * impairmentQ`.
+ * Values are in real metres (float).
+ *
+ * @param segmentId   Canonical segment identifier (e.g. `"head"`, `"leftArm"`).
+ * @param impairmentQ Impairment blend weight [0, 1] float.
+ * @returns Local-space offset in real metres.
+ */
+export function derivePoseOffset(segmentId, impairmentQ) {
+    // 6% of stature at full impairment (clamp to [0, SCALE.Q])
+    const weightQ = clampQ(Math.round(impairmentQ * SCALE.Q), q(0), SCALE.Q);
+    const offsetQ = qMul(weightQ, q(0.06));
+    const offset = offsetQ / SCALE.Q;
+    // `+ 0` normalises IEEE-754 negative-zero (−0) to plain 0.
+    switch (segmentId) {
+        case "head": return { x: 0, y: (-offset * 0.35) + 0, z: 0 };
+        case "torso":
+        case "thorax":
+        case "abdomen": return { x: 0, y: (-offset * 0.50) + 0, z: 0 };
+        case "leftArm": return { x: (-offset) + 0, y: 0, z: 0 };
+        case "rightArm": return { x: offset, y: 0, z: 0 };
+        case "leftLeg": return { x: (-offset * 0.45) + 0, y: (-offset) + 0, z: 0 };
+        case "rightLeg": return { x: offset * 0.45, y: (-offset) + 0, z: 0 };
+        default: return { x: 0, y: 0, z: 0 };
+    }
+}
+// ── Internal helpers ──────────────────────────────────────────────────────────
+function scaleVec3(v, divisor) {
+    return { x: v.x / divisor, y: v.y / divisor, z: v.z / divisor };
+}
+function normalizeFacing(v) {
+    const mag = Math.hypot(v.x, v.y, v.z) || 1;
+    return { x: v.x / mag, y: v.y / mag, z: v.z / mag };
+}
+function buildBridgeAnimation(animation, pose) {
+    const locomotionBlend = Math.max(animation.idle, animation.walk, animation.run, animation.sprint, animation.crawl) / SCALE.Q;
+    const injuryWeight = pose.reduce((worst, m) => Math.max(worst, m.impairmentQ), 0) / SCALE.Q;
+    return {
+        idle: animation.idle / SCALE.Q,
+        walk: animation.walk / SCALE.Q,
+        run: animation.run / SCALE.Q,
+        sprint: animation.sprint / SCALE.Q,
+        crawl: animation.crawl / SCALE.Q,
+        guardingQ: animation.guardingQ / SCALE.Q,
+        attackingQ: animation.attackingQ / SCALE.Q,
+        shockQ: animation.shockQ / SCALE.Q,
+        fearQ: animation.fearQ / SCALE.Q,
+        prone: animation.prone,
+        unconscious: animation.unconscious,
+        dead: animation.dead,
+        primaryState: derivePrimaryState(animation),
+        locomotionBlend,
+        injuryWeight,
+    };
+}
+function buildBridgeGrapple(grapple) {
+    return {
+        isHolder: grapple.isHolder,
+        holdingEntityId: grapple.holdingEntityId ?? 0,
+        isHeld: grapple.isHeld,
+        heldByIds: grapple.heldByIds,
+        position: grapple.position,
+        gripQ: grapple.gripQ / SCALE.Q,
+    };
+}
+function buildBridgeCondition(entity) {
+    return {
+        shockQ: entity.injury.shock / SCALE.Q,
+        fearQ: (entity.condition.fearQ ?? 0) / SCALE.Q,
+        consciousnessQ: entity.injury.consciousness / SCALE.Q,
+        fluidLossQ: entity.injury.fluidLoss / SCALE.Q,
+        dead: entity.injury.dead,
+    };
+}
+function buildEntitySnapshot(entity, tick) {
+    const animation = deriveAnimationHints(entity);
+    const pose = derivePoseModifiers(entity);
+    const grapple = deriveGrappleConstraint(entity);
+    const mass = deriveMassDistribution(entity);
+    return {
+        entityId: entity.id,
+        teamId: entity.teamId,
+        tick,
+        position_m: scaleVec3(entity.position_m, SCALE.m),
+        velocity_mps: scaleVec3(entity.velocity_mps, SCALE.m),
+        facing: normalizeFacing(entity.action.facingDirQ),
+        massKg: mass.totalMass_kg / SCALE.kg,
+        cogOffset_m: mass.cogOffset_m,
+        animation: buildBridgeAnimation(animation, pose),
+        pose: pose.map(pm => ({
+            segmentId: pm.segmentId,
+            impairmentQ: pm.impairmentQ / SCALE.Q,
+            structuralQ: pm.structuralQ / SCALE.Q,
+            surfaceQ: pm.surfaceQ / SCALE.Q,
+            localOffset_m: derivePoseOffset(pm.segmentId, pm.impairmentQ / SCALE.Q),
+        })),
+        grapple: buildBridgeGrapple(grapple),
+        condition: buildBridgeCondition(entity),
+    };
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Serialize a complete simulation tick into the stable bridge wire format.
+ *
+ * This is the canonical sidecar serializer.  Replaces per-project
+ * `serialiseFrame` implementations in Unity and Godot sidecars.
+ *
+ * @param world   Current world state after `stepWorld()`.
+ * @param config  Sidecar configuration.
+ * @returns       A `BridgeFrame` safe to `JSON.stringify` and send over WebSocket.
+ *
+ * @example
+ * ```ts
+ * import { serializeBridgeFrame } from "@its-not-rocket-science/ananke/host-loop";
+ *
+ * function tick() {
+ *   stepWorld(world, commands, ctx);
+ *   const frame = serializeBridgeFrame(world, { scenarioId: "my-duel", tickHz: 20 });
+ *   broadcast(JSON.stringify(frame));
+ * }
+ * ```
+ */
+export function serializeBridgeFrame(world, config) {
+    return {
+        schema: BRIDGE_SCHEMA_VERSION,
+        scenarioId: config.scenarioId,
+        tick: world.tick,
+        tickHz: config.tickHz ?? DEFAULT_TICK_HZ,
+        generatedAt: new Date().toISOString(),
+        entities: world.entities.map(e => buildEntitySnapshot(e, world.tick)),
+    };
+}

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

@@ -27,6 +27,17 @@ export interface ExtendedSenses {
      * Precipitation disperses scent.
      */
     olfactionSensitivity_Q?: Q;
+    /**
+     * Thermal (infrared) detection range [SCALE.m].
+     * Non-zero = entity detects warm-bodied targets by heat signature.
+     * Effective range scales with target thermal signature strength.
+     * Degraded by precipitation (water absorbs thermal radiation).
+     * Dead entities have no thermal signature — not detectable.
+     *
+     * Added by PA-7. Typical values: pit-viper ≈ 5 m (50 000 Sm);
+     * evolved predator ≈ 30 m (300 000 Sm).
+     */
+    thermalVisionRange_m?: number;
 }
 /** Detected via echolocation — returned by canDetectExtended. */
 export declare const DETECT_ECHOLOCATION: Q;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.55",
+  "version": "0.1.57",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -189,6 +189,14 @@
     "./atmosphere": {
       "import": "./dist/src/atmosphere.js",
       "types": "./dist/src/atmosphere.d.ts"
+    },
+    "./extended-senses": {
+      "import": "./dist/src/extended-senses.js",
+      "types": "./dist/src/extended-senses.d.ts"
+    },
+    "./host-loop": {
+      "import": "./dist/src/host-loop.js",
+      "types": "./dist/src/host-loop.d.ts"
     }
   },
   "workspaces": [