@its-not-rocket-science/ananke 0.1.0

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

@@ -0,0 +1,135 @@
+import type { Q } from "../units.js";
+import type { Vec3 } from "./vec3.js";
+import { DamageChannel } from "../channels.js";
+import type { MedicalTier } from "./medical.js";
+import type { ActiveSubstance } from "./substance.js";
+import type { TechCapability } from "./tech.js";
+import type { WeaponDamageProfile } from "../equipment.js";
+/**
+ * Pluggable energy-replenishment model for a CapabilitySource.
+ * The engine sees only the resulting reserve_J delta — source flavor is in the tags.
+ */
+export type RegenModel = {
+    type: "rest";
+    regenRate_W: number;
+} | {
+    type: "constant";
+    regenRate_W: number;
+} | {
+    type: "ambient";
+    maxRate_W: number;
+} | {
+    type: "event";
+    triggers: RegenTrigger[];
+} | {
+    type: "boundless";
+};
+export type RegenTrigger = {
+    on: "kill";
+    amount_J: number;
+} | {
+    on: "tick";
+    every_n: number;
+    amount_J: number;
+    _nextTick?: number;
+} | {
+    on: "terrain";
+    tag: string;
+    amount_J: number;
+};
+/** Specification for a capability impact — maps to a DamageChannel. */
+export interface ImpactSpec {
+    energy_J: number;
+    channel: DamageChannel;
+}
+/** Field effect placed in the world (suppression zone, environmental modifier). */
+export interface FieldEffectSpec {
+    radius_m: number;
+    suppressesTags: string[];
+    duration_ticks: number;
+    /**
+     * Phase 12B effect chain: payload applied to every living entity inside the
+     * field radius each tick. Fires in the same tick the field is active,
+     * before expiry. The placing entity is the actor for attribution.
+     */
+    chainPayload?: EffectPayload | EffectPayload[];
+}
+/** A FieldEffect living in WorldState.activeFieldEffects. */
+export interface FieldEffect extends FieldEffectSpec {
+    id: string;
+    origin: Vec3;
+    placedByEntityId: number;
+}
+/**
+ * All effect variants. Each maps to an existing engine primitive so the
+ * engine applies the same code path regardless of whether the effect is
+ * "magical" or "technological".
+ */
+export type EffectPayload = {
+    kind: "impact";
+    spec: ImpactSpec;
+} | {
+    kind: "treatment";
+    tier: MedicalTier;
+    rateMul: Q;
+} | {
+    kind: "armourLayer";
+    resist_J: number;
+    channels: DamageChannel[];
+    duration_ticks: number;
+} | {
+    kind: "velocity";
+    delta_mps: Vec3;
+} | {
+    kind: "substance";
+    substance: ActiveSubstance;
+} | {
+    kind: "structuralRepair";
+    region: string;
+    amount: Q;
+} | {
+    kind: "fieldEffect";
+    spec: FieldEffectSpec;
+} | {
+    kind: "weaponImpact";
+    profile: WeaponDamageProfile;
+    energy_J: number;
+};
+export interface CapabilityEffect {
+    id: string;
+    cost_J: number;
+    castTime_ticks: number;
+    cooldown_ticks?: number;
+    requiredCapability?: TechCapability;
+    range_m?: number;
+    aoeRadius_m?: number;
+    coneHalfAngle_rad?: number;
+    coneDir?: "facing" | "fixed";
+    coneDirFixed?: {
+        dx: number;
+        dy: number;
+    };
+    sustainedTicks?: number;
+    payload: EffectPayload | EffectPayload[];
+    tags?: string[];
+}
+export interface CapabilitySource {
+    id: string;
+    label: string;
+    tags: string[];
+    reserve_J: number;
+    maxReserve_J: number;
+    regenModel: RegenModel;
+    effects: CapabilityEffect[];
+    /**
+     * Phase 12B: if primary reserve is exhausted, draw activation cost from this source instead.
+     * Must be the `id` of another CapabilitySource on the same entity.
+     */
+    linkedFallbackId?: string;
+}
+export interface PendingActivation {
+    sourceId: string;
+    effectId: string;
+    targetId?: number;
+    resolveAtTick: number;
+}

package/dist/src/sim/capability.js

@@ -0,0 +1,8 @@
+// src/sim/capability.ts
+//
+// Phase 12 — Capability Sources and Effects
+//
+// Implements Clarke's Third Law: "Any sufficiently advanced technology is
+// indistinguishable from magic." Magic and technology are the same abstraction;
+// only the tags differ. The engine cannot tell a fireball from a plasma grenade.
+export {};

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

@@ -0,0 +1,21 @@
+import { type Q } from "../units.js";
+import type { Entity } from "./entity.js";
+import { type Weapon, type Shield } from "../equipment.js";
+import { type HitArea } from "./kinds.js";
+import { BodySegment } from "./bodyplan.js";
+export type { HitArea };
+export interface HitResolution {
+    hit: boolean;
+    area: HitArea;
+    hitQuality: Q;
+    blocked: boolean;
+    parried: boolean;
+    shieldBlocked: boolean;
+}
+export declare function parryLeverageQ(wpn: Weapon, attacker: Entity): Q;
+export declare function chooseArea(r01: Q): HitArea;
+export declare function resolveHit(seedU32: number, attackSkill: Q, defenceSkill: Q, geometryDotQ: Q, defenceMode: "none" | "block" | "parry" | "dodge", defenceIntensity: Q): HitResolution;
+/** Returns true if `shield` covers `area`. Accepts the shield item so that
+ *  future item variants (buckler, kite, tower) can override coverage by
+ *  checking item tags rather than hard-coding areas here. */
+export declare function shieldCovers(shield: Shield, area: HitArea | BodySegment | undefined): boolean;

package/dist/src/sim/combat.js

@@ -0,0 +1,77 @@
+import { SCALE, q, qMul, clampQ, mulDiv } from "../units.js";
+import { makeRng } from "../rng.js";
+function weaponMomentArm_m(wpn, attacker) {
+    const reach = wpn.reach_m ?? Math.trunc(attacker.attributes.morphology.stature_m * 0.45);
+    return wpn.momentArm_m ?? Math.trunc(reach * 0.55);
+}
+export function parryLeverageQ(wpn, attacker) {
+    const arm = weaponMomentArm_m(wpn, attacker);
+    // reference ~0.6m human sword lever
+    const ref = Math.trunc(0.6 * SCALE.m);
+    // Clamp the raw ratio so extreme weapons stay in a sane band.
+    // ratio ∈ [0.5, 1.8] → formula ∈ [0.85, 1.24] → final clamp ∈ [0.85, 1.20].
+    // Note: the lower bound of q(0.85) is derived from the formula minimum
+    // (q(0.70) + qMul(q(0.5), q(0.30)) = 0.85), so it is intentionally tighter
+    // than the old q(0.80) which was unreachable.
+    const ratio = clampQ(mulDiv(arm * SCALE.Q, 1, ref), q(0.5), q(1.8));
+    // compress into sane band
+    return clampQ(q(0.70) + qMul(ratio, q(0.30)), q(0.85), // minimum reachable value given ratio ≥ 0.5
+    q(1.20));
+}
+export function chooseArea(r01) {
+    if (r01 < q(0.12))
+        return "head";
+    if (r01 < q(0.62))
+        return "torso";
+    if (r01 < q(0.82))
+        return "arm";
+    return "leg";
+}
+export function resolveHit(seedU32, attackSkill, defenceSkill, geometryDotQ, defenceMode, defenceIntensity) {
+    const rng = makeRng(seedU32, SCALE.Q);
+    const geom = clampQ(q(1.05) - mulDiv(geometryDotQ, q(0.10), SCALE.Q), q(0.85), q(1.20));
+    const atk = qMul(attackSkill, geom);
+    const diff = (atk - defenceSkill);
+    const p = clampQ(q(0.55) + mulDiv(diff, q(0.35), SCALE.Q), q(0.10), q(0.95));
+    const roll = rng.q01();
+    const hit = roll < p;
+    const area = chooseArea(rng.q01());
+    // Quality measures how cleanly the attack landed. It is only meaningful
+    // when hit === true; set to 0 on a miss so callers can't accidentally use it.
+    const quality = hit
+        ? clampQ(qMul(atk, q(0.60) + mulDiv((p - roll), q(0.40), SCALE.Q)), q(0.05), q(0.99))
+        : q(0);
+    let blocked = false;
+    let parried = false;
+    if (hit && defenceMode !== "none" && defenceIntensity > 0) {
+        const d = qMul(defenceIntensity, defenceSkill);
+        if (defenceMode === "block") {
+            const pb = clampQ(q(0.10) + qMul(d, q(0.60)), q(0.05), q(0.85));
+            blocked = rng.q01() < pb;
+        }
+        else if (defenceMode === "parry") {
+            const pp = clampQ(q(0.08) + qMul(d, q(0.55)), q(0.03), q(0.75));
+            parried = rng.q01() < pp;
+        }
+        else if (defenceMode === "dodge") {
+            const pd = clampQ(qMul(d, q(0.65)), q(0.05), q(0.80));
+            if (rng.q01() < pd)
+                return { hit: false, area, hitQuality: quality, blocked: false, parried: false, shieldBlocked: false };
+        }
+    }
+    return { hit, area, hitQuality: quality, blocked, parried, shieldBlocked: false };
+}
+// function isShield(item: Item): item is Shield {
+//   // cheap “A” that makes “B” easy later
+//   return (item)?.kind === "shield";
+// }
+/** Returns true if `shield` covers `area`. Accepts the shield item so that
+ *  future item variants (buckler, kite, tower) can override coverage by
+ *  checking item tags rather than hard-coding areas here. */
+export function shieldCovers(shield, area) {
+    if (area === undefined)
+        return false; // no hit area = no shield coverage
+    // Explicit coverage list; extend when adding shield variants.
+    const covered = shield.covers ?? ["torso", "head"];
+    return covered.includes(area);
+}

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

@@ -0,0 +1,11 @@
+import type { AttackCommand, DefendCommand } from "./commands.js";
+import { type Q } from "../units.js";
+export declare function makeAttackCommand(targetId: number, opts?: {
+    weaponId?: string;
+    intensity?: Q;
+    mode?: "strike";
+}): AttackCommand;
+export declare function defendNone(): DefendCommand;
+export declare function defendBlock(intensity?: Q): DefendCommand;
+export declare function defendParry(intensity?: Q): DefendCommand;
+export declare function defendDodge(intensity?: Q): DefendCommand;

package/dist/src/sim/commandBuilders.js

@@ -0,0 +1,39 @@
+import { q } from "../units.js";
+export function makeAttackCommand(targetId, opts = {}) {
+    return {
+        kind: "attack",
+        mode: "strike",
+        targetId,
+        ...(opts.weaponId !== undefined ? { weaponId: opts.weaponId } : {}),
+        ...(opts.intensity !== undefined ? { intensity: opts.intensity } : {}),
+        ...(opts.mode !== undefined ? { mode: opts.mode } : {}),
+    };
+}
+export function defendNone() {
+    return {
+        kind: "defend",
+        mode: "none",
+        intensity: q(0),
+    };
+}
+export function defendBlock(intensity = q(1.0)) {
+    return {
+        kind: "defend",
+        mode: "block",
+        intensity,
+    };
+}
+export function defendParry(intensity = q(1.0)) {
+    return {
+        kind: "defend",
+        mode: "parry",
+        intensity,
+    };
+}
+export function defendDodge(intensity = q(1.0)) {
+    return {
+        kind: "defend",
+        mode: "dodge",
+        intensity,
+    };
+}

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

@@ -0,0 +1,71 @@
+import type { Q } from "../units.js";
+import type { Vec3 } from "./vec3.js";
+import { CommandKinds, DefenceMode, EngageModes, MoveMode } from "./kinds.js";
+import type { MedicalAction, MedicalTier } from "./medical.js";
+export type Command = MoveCommand | SetProneCommand | DefendCommand | AttackCommand | AttackNearestCommand | GrappleCommand | BreakGrappleCommand | BreakBindCommand | ShootCommand | TreatCommand | ActivateCommand;
+export interface MoveCommand {
+    kind: typeof CommandKinds.Move;
+    dir: Vec3;
+    intensity: Q;
+    mode: MoveMode;
+}
+export interface SetProneCommand {
+    kind: typeof CommandKinds.SetProne;
+    prone: boolean;
+}
+export interface DefendCommand {
+    kind: typeof CommandKinds.Defend;
+    mode: DefenceMode;
+    intensity: Q;
+}
+export interface AttackCommand {
+    kind: typeof CommandKinds.Attack;
+    targetId: number;
+    weaponId?: string;
+    intensity?: Q;
+    mode?: typeof EngageModes.Strike;
+}
+export declare const noMove: () => MoveCommand;
+export interface AttackNearestCommand {
+    kind: typeof CommandKinds.AttackNearest;
+    weaponId?: string;
+    intensity?: Q;
+    mode: typeof EngageModes.Strike;
+}
+export type GrappleMode = "grapple" | "throw" | "choke" | "jointLock";
+export interface GrappleCommand {
+    kind: typeof CommandKinds.Grapple;
+    targetId: number;
+    intensity: Q;
+    mode?: GrappleMode;
+}
+export interface BreakGrappleCommand {
+    kind: typeof CommandKinds.BreakGrapple;
+    intensity: Q;
+}
+export interface BreakBindCommand {
+    kind: typeof CommandKinds.BreakBind;
+    intensity: Q;
+}
+export interface ShootCommand {
+    kind: typeof CommandKinds.Shoot;
+    targetId: number;
+    weaponId?: string;
+    intensity?: Q;
+    ammoId?: string;
+}
+export interface TreatCommand {
+    kind: typeof CommandKinds.Treat;
+    targetId: number;
+    action: MedicalAction;
+    tier: MedicalTier;
+    /** Region to treat. Required for tourniquet/bandage/surgery; omit for fluidReplacement. */
+    regionId?: string;
+}
+export interface ActivateCommand {
+    kind: typeof CommandKinds.Activate;
+    sourceId: string;
+    effectId: string;
+    targetId?: number;
+}
+export type CommandMap = Map<number, readonly Command[]>;

package/dist/src/sim/commands.js

@@ -0,0 +1,8 @@
+import { q } from "../units.js";
+import { CommandKinds, MoveModes } from "./kinds.js";
+export const noMove = () => ({
+    kind: CommandKinds.Move,
+    dir: { x: 0, y: 0, z: 0 },
+    intensity: q(0),
+    mode: MoveModes.Walk,
+});

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

@@ -0,0 +1,35 @@
+import { type Q } from "../units.js";
+/** Phase 30: staged hunger/starvation state derived from caloricBalance_J. */
+export type HungerState = "sated" | "hungry" | "starving" | "critical";
+export interface ConditionState {
+    onFire: Q;
+    corrosiveExposure: Q;
+    radiation: Q;
+    electricalOverload: Q;
+    suffocation: Q;
+    stunned: Q;
+    prone: boolean;
+    pinned: boolean;
+    standBlockedTicks: number;
+    unconsciousTicks: number;
+    suppressedTicks: number;
+    blindTicks: number;
+    fearQ?: Q;
+    suppressionFearMul: Q;
+    recentAllyDeaths: number;
+    lastAllyDeathTick: number;
+    surrendered: boolean;
+    rallyCooldownTicks: number;
+    shieldReserve_J?: number;
+    shieldExpiry_tick?: number;
+    coreTemp_Q?: Q;
+    /** Caloric surplus / deficit in joules; starts at 0, goes negative as deficit grows. */
+    caloricBalance_J?: number;
+    /** Hydration surplus / deficit in hydration_J units; negative = dehydrated. */
+    hydrationBalance_J?: number;
+    /** World tick of last food or water consumption. */
+    lastMealTick?: number;
+    /** Derived from caloricBalance_J; updated by stepNutrition / consumeFood. */
+    hungerState?: HungerState;
+}
+export declare const defaultCondition: () => ConditionState;

package/dist/src/sim/condition.js

@@ -0,0 +1,21 @@
+import { q, SCALE } from "../units.js";
+export const defaultCondition = () => ({
+    onFire: q(0),
+    corrosiveExposure: q(0),
+    radiation: q(0),
+    electricalOverload: q(0),
+    suffocation: q(0),
+    stunned: q(0),
+    prone: false,
+    pinned: false,
+    standBlockedTicks: 0,
+    unconsciousTicks: 0,
+    suppressedTicks: 0,
+    blindTicks: 0,
+    fearQ: q(0),
+    suppressionFearMul: SCALE.Q,
+    recentAllyDeaths: 0,
+    lastAllyDeathTick: -1,
+    surrendered: false,
+    rallyCooldownTicks: 0,
+});

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

@@ -0,0 +1,40 @@
+import type { Entity } from "./entity.js";
+/**
+ * A directional cone defined in 2D (x-y plane).
+ *
+ * `dir` is a unit vector with magnitude SCALE.m (= 10000).
+ *   - Facing +x at 0°: { dx: 10000, dy: 0 }
+ *   - Facing +y at 90°: { dx: 0, dy: 10000 }
+ *
+ * `halfAngle_rad` is a config constant (outside fixed-point domain).
+ * `range_m` and `origin` use SCALE.m (fixed-point metres).
+ */
+export interface ConeSpec {
+    origin: {
+        x: number;
+        y: number;
+    };
+    dir: {
+        dx: number;
+        dy: number;
+    };
+    halfAngle_rad: number;
+    range_m: number;
+}
+/**
+ * Returns true if the entity's centre is inside the cone.
+ *
+ * Geometric derivation:
+ *   Let vec = entity.pos - cone.origin (SCALE.m units)
+ *   dot = vec · dir  = |vec| * SCALE.m * cos(θ)
+ *   Entity is in cone iff cos(θ) ≥ cos(halfAngle_rad)
+ *   ↔  dot ≥ cos(halfAngle_rad) * |vec| * SCALE.m
+ *
+ * Integer dot product; float threshold (halfAngle is a config constant).
+ */
+export declare function entityInCone(entity: Entity, cone: ConeSpec): boolean;
+/**
+ * Build a ConeSpec centred on actor using its current facingDirQ.
+ * facingDirQ is SCALE.Q-normalised; we rescale to SCALE.m for geometry.
+ */
+export declare function buildEntityFacingCone(actor: Entity, halfAngle_rad: number, range_m: number): ConeSpec;

package/dist/src/sim/cone.js

@@ -0,0 +1,44 @@
+// src/sim/cone.ts — Phase 28: Cone geometry for directional AoE effects
+//
+// A cone is a directional AoE shape: origin, facing direction, half-angle, and range.
+// Used for breath weapons, flamethrowers, sonic disorientation blasts, gas dispersal.
+import { SCALE } from "../units.js";
+/**
+ * Returns true if the entity's centre is inside the cone.
+ *
+ * Geometric derivation:
+ *   Let vec = entity.pos - cone.origin (SCALE.m units)
+ *   dot = vec · dir  = |vec| * SCALE.m * cos(θ)
+ *   Entity is in cone iff cos(θ) ≥ cos(halfAngle_rad)
+ *   ↔  dot ≥ cos(halfAngle_rad) * |vec| * SCALE.m
+ *
+ * Integer dot product; float threshold (halfAngle is a config constant).
+ */
+export function entityInCone(entity, cone) {
+    const ex = entity.position_m.x - cone.origin.x;
+    const ey = entity.position_m.y - cone.origin.y;
+    const distSq = ex * ex + ey * ey;
+    if (distSq > cone.range_m * cone.range_m)
+        return false;
+    if (distSq === 0)
+        return true; // at origin — inside by convention
+    const dist = Math.sqrt(distSq); // SCALE.m units (float OK — used in threshold comparison)
+    const dot = ex * cone.dir.dx + ey * cone.dir.dy;
+    return dot >= Math.cos(cone.halfAngle_rad) * dist * SCALE.m;
+}
+/**
+ * Build a ConeSpec centred on actor using its current facingDirQ.
+ * facingDirQ is SCALE.Q-normalised; we rescale to SCALE.m for geometry.
+ */
+export function buildEntityFacingCone(actor, halfAngle_rad, range_m) {
+    const fx = actor.action.facingDirQ.x;
+    const fy = actor.action.facingDirQ.y;
+    const mag = Math.sqrt(fx * fx + fy * fy);
+    const scale = mag > 0 ? SCALE.m / mag : 1;
+    return {
+        origin: { x: actor.position_m.x, y: actor.position_m.y },
+        dir: { dx: Math.round(fx * scale), dy: Math.round(fy * scale) },
+        halfAngle_rad,
+        range_m,
+    };
+}

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

@@ -0,0 +1,68 @@
+import { SimulationTuning } from "./tuning.js";
+import type { TraceSink } from "./trace.js";
+import type { TerrainGrid } from "./terrain.js";
+import type { DensityField } from "./density.js";
+import type { SensoryEnvironment } from "./sensory.js";
+import type { ObstacleGrid, ElevationGrid, SlopeGrid, HazardGrid } from "./terrain.js";
+import type { TechContext } from "./tech.js";
+import type { WeatherState } from "./weather.js";
+import type { Q, I32 } from "../units.js";
+export interface KernelContext {
+    tractionCoeff: Q;
+    tuning?: SimulationTuning;
+    cellSize_m?: I32;
+    density?: DensityField;
+    trace?: TraceSink;
+    /** Phase 4: ambient sensory conditions. Defaults to DEFAULT_SENSORY_ENV (full daylight, clear). */
+    sensoryEnv?: SensoryEnvironment;
+    /** Phase 6: per-cell terrain grid. When provided, traction is looked up by entity position. */
+    terrainGrid?: TerrainGrid;
+    /** Phase 6: impassable and partial-cover cells.  q(1.0) = fully impassable; q(0.5) = 50% cover. */
+    obstacleGrid?: ObstacleGrid;
+    /** Phase 6: height above ground level per cell (SCALE.m units). Affects melee reach and projectile range. */
+    elevationGrid?: ElevationGrid;
+    /** Phase 6: per-cell slope direction and grade.  Modifies effective sprint speed. */
+    slopeGrid?: SlopeGrid;
+    /** Phase 6: dynamic hazard cells (fire, radiation, poison_gas). Damage applied per tick. */
+    hazardGrid?: HazardGrid;
+    /**
+     * Phase 10: ambient temperature (Q 0..1).
+     * Comfort range: [q(0.35), q(0.65)].
+     * Above q(0.65) → heat stress (shock + surface damage); below q(0.35) → cold stress (shock + fatigue).
+     * Entity attributes `heatTolerance` and `coldTolerance` scale the dose.
+     */
+    ambientTemperature_Q?: Q;
+    /**
+     * Phase 11: technology context.
+     * When provided, gates which items are available.
+     * Does not directly affect simulation physics — use validateLoadout() before stepWorld
+     * to verify that the entity's loadout is era-appropriate.
+     */
+    techCtx?: TechContext;
+    /**
+     * Phase 12: ambient energy grid.
+     * Maps terrain cell keys to ambient energy fraction (Q, 0..1).
+     * Used by CapabilitySource regenModel "ambient" — regen rate scales with cell value.
+     * Ley lines, geothermal vents, solar collectors, stellar wind.
+     */
+    ambientGrid?: Map<string, Q>;
+    /**
+     * Phase 12B: terrain tag grid.
+     * Maps cell keys to arrays of string tags; used by CapabilitySource "event" regenModel
+     * { on: "terrain"; tag: string } triggers — fires once per cell-boundary crossing.
+     */
+    terrainTagGrid?: Map<string, string[]>;
+    /**
+     * Phase 29: ambient temperature in the Phase 29 Q encoding.
+     * q(0.5) = 37°C (comfortable); cToQ(0) ≈ -1852 (0°C); cToQ(30) ≈ 3704 (30°C).
+     * When absent, stepCoreTemp is not called and core temperature is not updated.
+     */
+    thermalAmbient_Q?: Q;
+    /**
+     * Phase 51: current weather conditions.
+     * When present, deriveWeatherModifiers() applies per-tick modifiers to
+     * tractionCoeff, sensoryEnv, thermalAmbient_Q, and ranged aim error.
+     * When absent, weather has no effect (backward-compatible).
+     */
+    weather?: WeatherState;
+}

package/dist/src/sim/context.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,14 @@
+import type { WorldState } from "./world.js";
+import type { SpatialIndex } from "./spatial.js";
+import type { WorldIndex } from "./indexing.js";
+import type { Q } from "../units.js";
+/** Per-entity crowding metrics (0..1 Q). */
+export interface DensityField {
+    crowdingQ: Map<number, Q>;
+}
+export interface DensityTuning {
+    personalRadius_m: number;
+    maxNeighbours: number;
+    crowdingAt: number;
+}
+export declare function computeDensityField(world: WorldState, index: WorldIndex, spatial: SpatialIndex, t: DensityTuning): DensityField;

package/dist/src/sim/density.js

@@ -0,0 +1,33 @@
+import { queryNearbyIds } from "./spatial.js";
+import { SCALE, clampQ } from "../units.js";
+export function computeDensityField(world, index, spatial, t) {
+    const crowdingQ = new Map();
+    const R = t.personalRadius_m;
+    for (const e of world.entities) {
+        if (e.injury.dead)
+            continue;
+        const ids = queryNearbyIds(spatial, e.position_m, R);
+        ids.sort((a, b) => a - b);
+        let n = 0;
+        for (const id of ids) {
+            if (id === e.id)
+                continue;
+            const o = index.byId.get(id);
+            if (!o || o.injury.dead)
+                continue;
+            // count only within true radius (avoid square query overcount)
+            const dx = o.position_m.x - e.position_m.x;
+            const dy = o.position_m.y - e.position_m.y;
+            const dz = o.position_m.z - e.position_m.z;
+            const d2 = BigInt(dx) * BigInt(dx) + BigInt(dy) * BigInt(dy) + BigInt(dz) * BigInt(dz);
+            if (d2 <= BigInt(R) * BigInt(R))
+                n++;
+            if (n >= t.maxNeighbours)
+                break;
+        }
+        // map neighbour count to 0..1 Q
+        const qv = clampQ(Math.trunc((n * SCALE.Q) / Math.max(1, t.crowdingAt)), 0, SCALE.Q);
+        crowdingQ.set(e.id, qv);
+    }
+    return { crowdingQ };
+}