@its-not-rocket-science/ananke 0.1.3 → 0.1.5

package/dist/src/catalog.js

@@ -0,0 +1,393 @@
+/**
+ * CE-12 — Data-Driven Entity Catalog
+ *
+ * Allows archetypes, weapons, and armour to be defined in JSON (e.g. loaded from a file
+ * or authored by non-TypeScript content creators) and registered at runtime.
+ *
+ * All numeric values in JSON are **real-world SI units**:
+ *   mass_kg   → real kilograms (e.g. 110)
+ *   stature_m → real metres   (e.g. 1.9)
+ *   force_N   → real Newtons  (e.g. 3200)
+ *   power_W   → real Watts    (e.g. 1400)
+ *   energy_J  → real Joules   (e.g. 25000)
+ *   time_s    → real seconds  (e.g. 0.22)
+ *   Q-fields  → ratio [0..1]  (e.g. 0.65)
+ *
+ * The catalog converts these to internal fixed-point SCALE units on registration.
+ * getCatalogEntry(id) returns the already-converted typed object.
+ */
+import { q, to } from "./units.js";
+import { HUMAN_BASE, AMATEUR_BOXER, PRO_BOXER, GRECO_WRESTLER, KNIGHT_INFANTRY, LARGE_PACIFIC_OCTOPUS, SERVICE_ROBOT, } from "./archetypes.js";
+import { DamageChannel, channelMask } from "./channels.js";
+const _store = new Map();
+// ── Built-in archetype bases ──────────────────────────────────────────────────
+const ARCHETYPE_BASES = {
+    HUMAN_BASE,
+    AMATEUR_BOXER,
+    PRO_BOXER,
+    GRECO_WRESTLER,
+    KNIGHT_INFANTRY,
+    LARGE_PACIFIC_OCTOPUS,
+    SERVICE_ROBOT,
+};
+// ── JSON parsing helpers ──────────────────────────────────────────────────────
+function assertObj(v, ctx) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        throw new Error(`${ctx}: expected object, got ${Array.isArray(v) ? "array" : typeof v}`);
+    return v;
+}
+function requireStr(obj, field, ctx) {
+    const v = obj[field];
+    if (typeof v !== "string")
+        throw new Error(`${ctx}: "${field}" must be a string`);
+    return v;
+}
+function requireNum(obj, field, ctx) {
+    const v = obj[field];
+    if (typeof v !== "number" || !Number.isFinite(v))
+        throw new Error(`${ctx}: "${field}" must be a finite number`);
+    return v;
+}
+function optNum(obj, field) {
+    const v = obj[field];
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+function optStr(obj, field) {
+    const v = obj[field];
+    return typeof v === "string" ? v : undefined;
+}
+function optBool(obj, field) {
+    const v = obj[field];
+    return typeof v === "boolean" ? v : undefined;
+}
+/** Convert a JSON [0..N] float to internal Q integer. Allows values slightly above 1.0 (e.g. q(1.2) for service-robot integrity). */
+function parseQ(v, field, ctx) {
+    if (v < 0)
+        throw new Error(`${ctx}: Q field "${field}" must be ≥ 0, got ${v}`);
+    if (v > 5)
+        throw new Error(`${ctx}: Q field "${field}" must be ≤ 5, got ${v}`);
+    return q(v);
+}
+function parseQField(obj, field, ctx) {
+    return parseQ(requireNum(obj, field, ctx), field, ctx);
+}
+function optQField(obj, field, ctx) {
+    const v = optNum(obj, field);
+    return v !== undefined ? parseQ(v, field, ctx) : undefined;
+}
+const ARCHETYPE_FIELD_SPEC = {
+    stature_m: "m",
+    mass_kg: "kg",
+    visionRange_m: "m",
+    visionArcDeg: "plain",
+    hearingRange_m: "m",
+    decisionLatency_s: "s",
+    attentionDepth: "plain",
+    threatHorizon_m: "m",
+    statureVar: "Q",
+    massVar: "Q",
+    reachVar: "Q",
+    actuatorScaleVar: "Q",
+    structureScaleVar: "Q",
+    actuatorMassFrac: "Q",
+    actuatorMassVar: "Q",
+    peakForce_N: "N",
+    peakForceVar: "Q",
+    peakPower_W: "W",
+    peakPowerVar: "Q",
+    continuousPower_W: "W",
+    continuousPowerVar: "Q",
+    reserveEnergy_J: "J",
+    reserveEnergyVar: "Q",
+    conversionEfficiency: "Q",
+    efficiencyVar: "Q",
+    reactionTime_s: "s",
+    reactionTimeVar: "Q",
+    controlQuality: "Q",
+    controlVar: "Q",
+    stability: "Q",
+    stabilityVar: "Q",
+    fineControl: "Q",
+    fineControlVar: "Q",
+    surfaceIntegrity: "Q",
+    surfaceVar: "Q",
+    bulkIntegrity: "Q",
+    bulkVar: "Q",
+    structureIntegrity: "Q",
+    structVar: "Q",
+    distressTolerance: "Q",
+    distressVar: "Q",
+    shockTolerance: "Q",
+    shockVar: "Q",
+    concussionTolerance: "Q",
+    concVar: "Q",
+    heatTolerance: "Q",
+    heatVar: "Q",
+    coldTolerance: "Q",
+    coldVar: "Q",
+    fatigueRate: "Q",
+    fatigueVar: "Q",
+    recoveryRate: "Q",
+    recoveryVar: "Q",
+};
+/** Convert a raw JSON number using the spec for that field. */
+function convertArchField(value, spec, field, ctx) {
+    switch (spec) {
+        case "m": return to.m(value);
+        case "kg": return to.kg(value);
+        case "N": return to.N(value);
+        case "W": return to.W(value);
+        case "J": return to.J(value);
+        case "s": return to.s(value);
+        case "Q": return parseQ(value, field, ctx);
+        case "plain": return Math.round(value);
+    }
+}
+/** Parse a JSON CognitiveProfile object (all fields Q). */
+function parseCognition(raw, ctx) {
+    const obj = assertObj(raw, `${ctx}.cognition`);
+    const fields = [
+        "linguistic", "logicalMathematical", "spatial", "bodilyKinesthetic",
+        "musical", "interpersonal", "intrapersonal", "naturalist", "interSpecies",
+    ];
+    const result = {};
+    for (const f of fields) {
+        result[f] = parseQField(obj, f, `${ctx}.cognition`);
+    }
+    return result;
+}
+// ── registerArchetype ─────────────────────────────────────────────────────────
+/**
+ * Parse a JSON archetype definition and register it in the catalog.
+ *
+ * @param json - Raw JSON value (e.g. from JSON.parse).  Must have:
+ *   - `id` (string): unique catalog identifier
+ *   - `base` (string, optional): name of a built-in archetype to inherit from
+ *   - `overrides` (object, optional): field values to override in real SI units
+ * @returns The converted Archetype object.
+ * @throws If required fields are missing, values are out of range, or `id` already registered.
+ */
+export function registerArchetype(json) {
+    const ctx = "registerArchetype";
+    const obj = assertObj(json, ctx);
+    const id = requireStr(obj, "id", ctx);
+    if (_store.has(id))
+        throw new Error(`${ctx}: id "${id}" is already registered`);
+    // Start from base archetype (all fields present)
+    const baseName = optStr(obj, "base");
+    const base = baseName
+        ? (ARCHETYPE_BASES[baseName] ?? (() => { throw new Error(`${ctx}: unknown base "${baseName}"`); })())
+        : HUMAN_BASE;
+    const result = { ...base };
+    // Apply overrides
+    const rawOverrides = obj["overrides"];
+    if (rawOverrides !== undefined) {
+        const overrides = assertObj(rawOverrides, `${ctx}.overrides`);
+        for (const [field, rawVal] of Object.entries(overrides)) {
+            if (field === "cognition")
+                continue; // handled separately below
+            const spec = ARCHETYPE_FIELD_SPEC[field];
+            if (spec === undefined)
+                throw new Error(`${ctx}: unknown archetype field "${field}"`);
+            if (typeof rawVal !== "number")
+                throw new Error(`${ctx}: override field "${field}" must be a number`);
+            result[field] = convertArchField(rawVal, spec, field, ctx);
+        }
+        // Cognition override
+        if (overrides["cognition"] !== undefined) {
+            result.cognition = parseCognition(overrides["cognition"], ctx);
+        }
+    }
+    _store.set(id, { kind: "archetype", id, archetype: result });
+    return result;
+}
+// ── registerWeapon ────────────────────────────────────────────────────────────
+/** Valid handedness strings. */
+const VALID_HANDEDNESS = new Set(["oneHand", "twoHand", "mounted", "natural"]);
+/**
+ * Parse a JSON weapon definition and register it in the catalog.
+ *
+ * @param json - Raw JSON value. Required fields:
+ *   - `id`, `name` (string)
+ *   - `mass_kg` (real kg), `bulk` (Q 0..1)
+ *   - `damage` (object with surfaceFrac, internalFrac, structuralFrac, bleedFactor, penetrationBias)
+ * @returns The converted Weapon object.
+ * @throws If required fields are missing or `id` already registered.
+ */
+export function registerWeapon(json) {
+    const ctx = "registerWeapon";
+    const obj = assertObj(json, ctx);
+    const id = requireStr(obj, "id", ctx);
+    const name = requireStr(obj, "name", ctx);
+    if (_store.has(id))
+        throw new Error(`${ctx}: id "${id}" is already registered`);
+    const mass_kg = to.kg(requireNum(obj, "mass_kg", ctx));
+    const bulk = parseQField(obj, "bulk", ctx);
+    // Optional movement/handling fields
+    const reach_m_raw = optNum(obj, "reach_m");
+    const readyTime_s_raw = optNum(obj, "readyTime_s");
+    const handlingMul_raw = optNum(obj, "handlingMul");
+    // Damage profile
+    const dmgRaw = assertObj(obj["damage"], `${ctx}.damage`);
+    const damage = {
+        surfaceFrac: parseQField(dmgRaw, "surfaceFrac", `${ctx}.damage`),
+        internalFrac: parseQField(dmgRaw, "internalFrac", `${ctx}.damage`),
+        structuralFrac: parseQField(dmgRaw, "structuralFrac", `${ctx}.damage`),
+        bleedFactor: parseQField(dmgRaw, "bleedFactor", `${ctx}.damage`),
+        penetrationBias: parseQField(dmgRaw, "penetrationBias", `${ctx}.damage`),
+    };
+    const weapon = {
+        kind: "weapon",
+        id,
+        name,
+        mass_kg,
+        bulk,
+        damage,
+        ...(reach_m_raw !== undefined ? { reach_m: to.m(reach_m_raw) } : {}),
+        ...(readyTime_s_raw !== undefined ? { readyTime_s: to.s(readyTime_s_raw) } : {}),
+        ...(handlingMul_raw !== undefined ? { handlingMul: parseQ(handlingMul_raw, "handlingMul", ctx) } : {}),
+    };
+    // Optional extra fields
+    const strikeEffMassFrac = optNum(obj, "strikeEffectiveMassFrac");
+    const strikeSpeedMul = optNum(obj, "strikeSpeedMul");
+    const momentArm_m = optNum(obj, "momentArm_m");
+    const handlingLoadMul = optNum(obj, "handlingLoadMul");
+    const shieldBypassQ = optNum(obj, "shieldBypassQ");
+    const handedness = optStr(obj, "handedness");
+    if (strikeEffMassFrac !== undefined)
+        weapon.strikeEffectiveMassFrac = parseQ(strikeEffMassFrac, "strikeEffectiveMassFrac", ctx);
+    if (strikeSpeedMul !== undefined)
+        weapon.strikeSpeedMul = parseQ(strikeSpeedMul, "strikeSpeedMul", ctx);
+    if (momentArm_m !== undefined)
+        weapon.momentArm_m = momentArm_m;
+    if (handlingLoadMul !== undefined)
+        weapon.handlingLoadMul = parseQ(handlingLoadMul, "handlingLoadMul", ctx);
+    if (shieldBypassQ !== undefined)
+        weapon.shieldBypassQ = parseQ(shieldBypassQ, "shieldBypassQ", ctx);
+    if (handedness !== undefined) {
+        if (!VALID_HANDEDNESS.has(handedness))
+            throw new Error(`${ctx}: "handedness" must be one of ${[...VALID_HANDEDNESS].join("|")}, got "${handedness}"`);
+        weapon.handedness = handedness;
+    }
+    _store.set(id, { kind: "weapon", id, weapon });
+    return weapon;
+}
+// ── registerArmour ────────────────────────────────────────────────────────────
+/** Map from JSON channel name strings to DamageChannel enum. */
+const CHANNEL_MAP = {
+    Kinetic: DamageChannel.Kinetic,
+    Thermal: DamageChannel.Thermal,
+    Electrical: DamageChannel.Electrical,
+    Chemical: DamageChannel.Chemical,
+    Radiation: DamageChannel.Radiation,
+    Corrosive: DamageChannel.Corrosive,
+    Suffocation: DamageChannel.Suffocation,
+    ControlDisruption: DamageChannel.ControlDisruption,
+    Energy: DamageChannel.Energy,
+};
+/**
+ * Parse a JSON armour definition and register it in the catalog.
+ *
+ * @param json - Raw JSON value. Required fields:
+ *   - `id`, `name` (string)
+ *   - `mass_kg` (real kg), `bulk` (Q 0..1)
+ *   - `resist_J` (real Joules), `protectedDamageMul` (Q 0..1)
+ *   - `coverageByRegion` (object mapping region name → Q 0..1)
+ * @returns The converted Armour object.
+ * @throws If required fields are missing or `id` already registered.
+ */
+export function registerArmour(json) {
+    const ctx = "registerArmour";
+    const obj = assertObj(json, ctx);
+    const id = requireStr(obj, "id", ctx);
+    const name = requireStr(obj, "name", ctx);
+    if (_store.has(id))
+        throw new Error(`${ctx}: id "${id}" is already registered`);
+    const mass_kg = to.kg(requireNum(obj, "mass_kg", ctx));
+    const bulk = parseQField(obj, "bulk", ctx);
+    const resist_J = to.J(requireNum(obj, "resist_J", ctx));
+    const protectedDamageMul = parseQField(obj, "protectedDamageMul", ctx);
+    // protects: array of channel name strings → ChannelMask
+    let protects = 0;
+    const protectsRaw = obj["protects"];
+    if (Array.isArray(protectsRaw)) {
+        for (const ch of protectsRaw) {
+            if (typeof ch !== "string")
+                throw new Error(`${ctx}: "protects" array must contain strings`);
+            const ch_enum = CHANNEL_MAP[ch];
+            if (ch_enum === undefined)
+                throw new Error(`${ctx}: unknown damage channel "${ch}" in "protects"`);
+            protects = channelMask(ch_enum) | protects;
+        }
+    }
+    else {
+        // Default: Kinetic only
+        protects = channelMask(DamageChannel.Kinetic);
+    }
+    // coverageByRegion: object of region → Q
+    const coverageRaw = assertObj(obj["coverageByRegion"], `${ctx}.coverageByRegion`);
+    const coverageByRegion = {};
+    for (const [region, val] of Object.entries(coverageRaw)) {
+        if (typeof val !== "number")
+            throw new Error(`${ctx}.coverageByRegion: region "${region}" value must be a number`);
+        coverageByRegion[region] = parseQ(val, region, `${ctx}.coverageByRegion`);
+    }
+    const armour = {
+        kind: "armour",
+        id,
+        name,
+        mass_kg,
+        bulk,
+        resist_J,
+        protectedDamageMul,
+        protects,
+        coverageByRegion,
+    };
+    // Optional fields
+    const mobilityMul = optQField(obj, "mobilityMul", ctx);
+    const fatigueMul = optQField(obj, "fatigueMul", ctx);
+    const reflectivity = optQField(obj, "reflectivity", ctx);
+    const ablative = optBool(obj, "ablative");
+    const insulation_m2KW = optNum(obj, "insulation_m2KW");
+    if (mobilityMul !== undefined)
+        armour.mobilityMul = mobilityMul;
+    if (fatigueMul !== undefined)
+        armour.fatigueMul = fatigueMul;
+    if (reflectivity !== undefined)
+        armour.reflectivity = reflectivity;
+    if (ablative !== undefined)
+        armour.ablative = ablative;
+    if (insulation_m2KW !== undefined)
+        armour.insulation_m2KW = insulation_m2KW;
+    _store.set(id, { kind: "armour", id, armour });
+    return armour;
+}
+// ── getCatalogEntry ───────────────────────────────────────────────────────────
+/**
+ * Look up a registered entry by id.
+ * Returns the CatalogEntry or undefined if not found.
+ */
+export function getCatalogEntry(id) {
+    return _store.get(id);
+}
+/**
+ * Return all registered ids of the given kind, or all ids when kind is omitted.
+ */
+export function listCatalog(kind) {
+    if (kind === undefined)
+        return [..._store.keys()];
+    return [..._store.entries()].filter(([, e]) => e.kind === kind).map(([id]) => id);
+}
+/**
+ * Remove a registered entry.  Useful in tests.
+ * Returns true if the entry existed and was removed.
+ */
+export function unregisterCatalogEntry(id) {
+    return _store.delete(id);
+}
+/**
+ * Remove all registered entries.  Useful for resetting state in tests.
+ */
+export function clearCatalog() {
+    _store.clear();
+}

package/dist/src/derive.d.ts

@@ -1,4 +1,4 @@
-import { Q } from "./units.js";
+import { Q, type I32 } from "./units.js";
 import type { IndividualAttributes, EnergyState } from "./types.js";
 import type { Loadout } from "./equipment.js";
 import { type CarryRules } from "./equipment.js";
@@ -10,12 +10,14 @@ export interface MovementCaps {
 export interface DeriveContext {
     tractionCoeff: Q;
     carryRules?: CarryRules;
+    /** Phase 68: override gravitational acceleration (SCALE.mps2 units). Default: G_mps2. */
+    gravity_mps2?: I32;
 }
 /** Fraction of reserve energy that can be spent on a single jump (~0.0283). */
 export declare const JUMP_ENERGY_FRACTION: number;
 export declare function derivePeakForceEff_N(a: IndividualAttributes): number;
-export declare function deriveMaxAcceleration_mps2(a: IndividualAttributes, tractionCoeff: Q): number;
+export declare function deriveMaxAcceleration_mps2(a: IndividualAttributes, tractionCoeff: Q, gravity_mps2?: I32): number;
 export declare function deriveMaxSprintSpeed_mps(a: IndividualAttributes): number;
-export declare function deriveJumpHeight_m(a: IndividualAttributes, reserveSpend_J: number): number;
+export declare function deriveJumpHeight_m(a: IndividualAttributes, reserveSpend_J: number, gravity_mps2?: I32): number;
 export declare function deriveMovementCaps(a: IndividualAttributes, loadout: Loadout, ctx: DeriveContext): MovementCaps;
 export declare function stepEnergyAndFatigue(a: IndividualAttributes, state: EnergyState, loadout: Loadout, demandedPower_W: number, dt_s: number, ctx: DeriveContext): void;

package/dist/src/derive.js

@@ -8,10 +8,10 @@ export function derivePeakForceEff_N(a) {
     const combined = qMul(a.morphology.actuatorScale, controlFactor);
     return mulDiv(F0, combined, SCALE.Q);
 }
-export function deriveMaxAcceleration_mps2(a, tractionCoeff) {
+export function deriveMaxAcceleration_mps2(a, tractionCoeff, gravity_mps2 = G_mps2) {
     const m = Math.max(1, a.morphology.mass_kg);
-    // normalForce ~ m*g. Use g~9.81 and keep deterministic:
-    const normalForce_N_scaled = mulDiv(m, G_mps2 * SCALE.N, SCALE.mps2); // scaled N
+    // normalForce ~ m*g. Use supplied gravity and keep deterministic:
+    const normalForce_N_scaled = mulDiv(m, gravity_mps2 * SCALE.N, SCALE.mps2); // scaled N
     const tractionLimit_N = mulDiv(normalForce_N_scaled, tractionCoeff, SCALE.Q);
     const F_eff = derivePeakForceEff_N(a);
     const usable_N = Math.min(F_eff, tractionLimit_N);
@@ -29,14 +29,16 @@ export function deriveMaxSprintSpeed_mps(a) {
     const mult = qMul(qMul(qMul(qMul(K, c), reachSqrt), controlFactor), a.performance.conversionEfficiency);
     return mulDiv(mult, SCALE.mps, SCALE.Q);
 }
-export function deriveJumpHeight_m(a, reserveSpend_J) {
+export function deriveJumpHeight_m(a, reserveSpend_J, gravity_mps2 = G_mps2) {
     const m = Math.max(1, a.morphology.mass_kg);
     const Euse = Math.min(a.performance.reserveEnergy_J, reserveSpend_J);
     const controlFactor = q(0.7) + qMul(q(0.3), a.control.controlQuality);
     const Eeff = mulDiv(mulDiv(Euse, a.performance.conversionEfficiency, SCALE.Q), controlFactor, SCALE.Q);
     // h = E/(m*g)
-    // force_real = m * g   where m = mass_real (kg), g = G_mps2 / SCALE.mps2
-    const force_real = mulDiv(m, G_mps2, SCALE.mps2 * SCALE.kg); // integer Newtons
+    // force_real = m * g   where m = mass_real (kg), g = gravity_mps2 / SCALE.mps2
+    // When gravity is 0 (microgravity), avoid division by zero — clamp to 1 as a sentinel.
+    const gClamped = Math.max(1, gravity_mps2);
+    const force_real = mulDiv(m, gClamped, SCALE.mps2 * SCALE.kg); // integer Newtons
     return mulDiv(Eeff, SCALE.m, Math.max(1, force_real));
 }
 export function deriveMovementCaps(a, loadout, ctx) {
@@ -47,8 +49,8 @@ export function deriveMovementCaps(a, loadout, ctx) {
     const accelMul = qMul(penalties.accelMul, armour.mobilityMul);
     const jumpMul = qMul(penalties.jumpMul, armour.mobilityMul);
     const baseV = deriveMaxSprintSpeed_mps(a);
-    const baseA = deriveMaxAcceleration_mps2(a, ctx.tractionCoeff);
-    const baseH = deriveJumpHeight_m(a, Math.trunc(a.performance.reserveEnergy_J * JUMP_ENERGY_FRACTION / SCALE.Q));
+    const baseA = deriveMaxAcceleration_mps2(a, ctx.tractionCoeff, ctx.gravity_mps2);
+    const baseH = deriveJumpHeight_m(a, Math.trunc(a.performance.reserveEnergy_J * JUMP_ENERGY_FRACTION / SCALE.Q), ctx.gravity_mps2);
     return {
         maxSprintSpeed_mps: mulDiv(baseV, speedMul, SCALE.Q),
         maxAcceleration_mps2: mulDiv(baseA, accelMul, SCALE.Q),

package/dist/src/index.d.ts

@@ -17,3 +17,4 @@ export * from "./replay.js";
 export * from "./bridge/index.js";
 export * from "./world-factory.js";
 export * from "./scenario.js";
+export * from "./catalog.js";

package/dist/src/index.js

@@ -26,3 +26,4 @@ export * from "./replay.js"; // ReplayRecorder, replayTo(), serializeReplay(), d
 export * from "./bridge/index.js"; // BridgeEngine, InterpolatedState, BridgeConfig
 export * from "./world-factory.js"; // createWorld(), EntitySpec, ARCHETYPE_MAP, ITEM_MAP
 export * from "./scenario.js"; // loadScenario(), validateScenario(), AnankeScenario
+export * from "./catalog.js"; // CE-12: registerArchetype(), registerWeapon(), registerArmour(), getCatalogEntry()

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

@@ -0,0 +1,71 @@
+/**
+ * Phase 68 — Multi-Biome Physics
+ *
+ * Defines BiomeContext: a set of optional physics overrides that alter gravity,
+ * thermal conduction, sound propagation, and drag relative to the standard
+ * Earth-surface defaults.  Pass a BiomeContext via KernelContext.biome to apply
+ * these overrides to every entity in the simulation.
+ *
+ * Three built-in profiles cover the most common non-standard environments:
+ *   BIOME_UNDERWATER — buoyancy-reduced gravity, severe drag, rapid heat exchange
+ *   BIOME_LUNAR      — 1/6 g, vacuum, radiation-only heat transfer
+ *   BIOME_VACUUM     — microgravity, vacuum, extreme thermal isolation
+ */
+import { type Q, type I32 } from "../units.js";
+export interface BiomeContext {
+    /**
+     * Gravitational acceleration in SCALE.mps2 units.
+     * Default (when absent): G_mps2 ≈ 98 067 (9.807 m/s²).
+     * Affects jump height and traction-limited acceleration.
+     */
+    gravity_mps2?: I32;
+    /**
+     * Base skin-layer thermal resistance (°C/W).
+     * Replaces the default 0.09 (still-air skin layer).
+     * Lower values = faster heat exchange (e.g. water ≈ 0.003).
+     * Higher values = slower exchange (e.g. vacuum ≈ 50 — radiation only).
+     */
+    thermalResistanceBase?: number;
+    /**
+     * Sound propagation multiplier stored as a raw Q multiple.
+     * q(1.0) = normal air propagation; q(0.0) = no sound (vacuum);
+     * q(4.0) = four-times-faster (water).
+     * Used to scale auditory sensory range.
+     */
+    soundPropagation?: Q;
+    /**
+     * Velocity drag factor applied to entity velocity each tick (Q, [0..SCALE.Q]).
+     * q(1.0) = no drag (default); q(0.3) = retain 30% velocity each tick (heavy drag).
+     * Applied by the movement step when non-default.
+     */
+    dragMul?: Q;
+    /**
+     * When true, entities without pressurised equipment cannot breathe.
+     * Unequipped entities accumulate fatigue at a fixed rate each tick.
+     */
+    isVacuum?: boolean;
+}
+/**
+ * Deep ocean / underwater environment.
+ * Net downward acceleration ≈ 1 m/s² (buoyancy cancels most gravity).
+ * Water conducts heat ~25× faster than still air.
+ * Sound travels ~4× faster in water than in air.
+ * Severe hydrodynamic drag (30% velocity retention per tick).
+ */
+export declare const BIOME_UNDERWATER: BiomeContext;
+/**
+ * Lunar surface — 1/6 Earth gravity, vacuum atmosphere.
+ * Heat transfer only via radiation → very high thermal resistance.
+ * No air, no sound.  Entities without pressurised suits suffer vacuum fatigue.
+ */
+export declare const BIOME_LUNAR: BiomeContext;
+/**
+ * Microgravity / open space environment.
+ * Near-zero gravity, no atmosphere, extreme thermal isolation.
+ * Entities without pressurised suits suffer vacuum fatigue.
+ */
+export declare const BIOME_VACUUM: BiomeContext;
+/** Effective gravitational acceleration for this biome (falls back to standard G). */
+export declare function biomeGravity(biome?: BiomeContext): I32;
+/** Effective base thermal resistance for this biome (falls back to still-air default 0.09 °C/W). */
+export declare function biomeThermalResistanceBase(biome?: BiomeContext): number;

package/dist/src/sim/biome.js

@@ -0,0 +1,61 @@
+/**
+ * Phase 68 — Multi-Biome Physics
+ *
+ * Defines BiomeContext: a set of optional physics overrides that alter gravity,
+ * thermal conduction, sound propagation, and drag relative to the standard
+ * Earth-surface defaults.  Pass a BiomeContext via KernelContext.biome to apply
+ * these overrides to every entity in the simulation.
+ *
+ * Three built-in profiles cover the most common non-standard environments:
+ *   BIOME_UNDERWATER — buoyancy-reduced gravity, severe drag, rapid heat exchange
+ *   BIOME_LUNAR      — 1/6 g, vacuum, radiation-only heat transfer
+ *   BIOME_VACUUM     — microgravity, vacuum, extreme thermal isolation
+ */
+import { G_mps2, q, SCALE } from "../units.js";
+// ── Built-in profiles ─────────────────────────────────────────────────────────
+/**
+ * Deep ocean / underwater environment.
+ * Net downward acceleration ≈ 1 m/s² (buoyancy cancels most gravity).
+ * Water conducts heat ~25× faster than still air.
+ * Sound travels ~4× faster in water than in air.
+ * Severe hydrodynamic drag (30% velocity retention per tick).
+ */
+export const BIOME_UNDERWATER = {
+    gravity_mps2: Math.round(1.0 * SCALE.mps2),
+    thermalResistanceBase: 0.003,
+    soundPropagation: q(4.0),
+    dragMul: q(0.30),
+};
+/**
+ * Lunar surface — 1/6 Earth gravity, vacuum atmosphere.
+ * Heat transfer only via radiation → very high thermal resistance.
+ * No air, no sound.  Entities without pressurised suits suffer vacuum fatigue.
+ */
+export const BIOME_LUNAR = {
+    gravity_mps2: Math.round(1.62 * SCALE.mps2),
+    thermalResistanceBase: 50.0,
+    soundPropagation: q(0),
+    dragMul: SCALE.Q, // no air resistance
+    isVacuum: true,
+};
+/**
+ * Microgravity / open space environment.
+ * Near-zero gravity, no atmosphere, extreme thermal isolation.
+ * Entities without pressurised suits suffer vacuum fatigue.
+ */
+export const BIOME_VACUUM = {
+    gravity_mps2: 0,
+    thermalResistanceBase: 100.0,
+    soundPropagation: q(0),
+    dragMul: SCALE.Q,
+    isVacuum: true,
+};
+// ── Accessor helpers ──────────────────────────────────────────────────────────
+/** Effective gravitational acceleration for this biome (falls back to standard G). */
+export function biomeGravity(biome) {
+    return (biome?.gravity_mps2 ?? G_mps2);
+}
+/** Effective base thermal resistance for this biome (falls back to still-air default 0.09 °C/W). */
+export function biomeThermalResistanceBase(biome) {
+    return biome?.thermalResistanceBase ?? 0.09;
+}

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

@@ -7,6 +7,7 @@ import type { ObstacleGrid, ElevationGrid, SlopeGrid, HazardGrid } from "./terra
 import type { TechContext } from "./tech.js";
 import type { WeatherState } from "./weather.js";
 import type { Q, I32 } from "../units.js";
+import type { BiomeContext } from "./biome.js";
 export interface KernelContext {
     tractionCoeff: Q;
     tuning?: SimulationTuning;
@@ -65,4 +66,11 @@ export interface KernelContext {
      * When absent, weather has no effect (backward-compatible).
      */
     weather?: WeatherState;
+    /**
+     * Phase 68: biome physics overrides.
+     * When present, adjusts gravity (jump height, traction), thermal resistance,
+     * sound propagation, and velocity drag for all entities this tick.
+     * When absent, standard Earth-surface physics apply.
+     */
+    biome?: BiomeContext;
 }

package/dist/src/sim/kernel.js

@@ -506,8 +506,14 @@ export function stepWorld(world, cmds, ctx) {
         stepSubstances(e, ctx.ambientTemperature_Q);
         stepEnergy(e, ctx);
         // Phase 29: advance core temperature once per tick (Phase 31: skip ectotherms)
+        // Phase 68: pass biome thermal resistance base when a biome is active
         if (ctx.thermalAmbient_Q !== undefined && !e.physiology?.coldBlooded) {
-            stepCoreTemp(e, ctx.thermalAmbient_Q, 1 / TICK_HZ);
+            stepCoreTemp(e, ctx.thermalAmbient_Q, 1 / TICK_HZ, ctx.biome?.thermalResistanceBase);
+        }
+        // Phase 68: vacuum fatigue — entities in a vacuum accumulate fatigue each tick.
+        // Rate: ~3 Q/tick = 60 Q/s = 0.6 %/s → full incapacitation in ~167 s without protection.
+        if (ctx.biome?.isVacuum) {
+            e.energy.fatigue = clampQ((e.energy.fatigue + 3), 0, SCALE.Q);
         }
         stepCapabilitySources(e, world, ctx); // Phase 12
         // Phase 13: emit KO and Death events so metrics/replay consumers can track incapacitation

package/dist/src/sim/step/movement.js

@@ -10,7 +10,10 @@ import { findExoskeleton } from "../../equipment.js";
 export function stepMovement(e, world, ctx, tuning) {
     const cellSize = ctx.cellSize_m ?? Math.trunc(4 * SCALE.m);
     const traction = tractionAtPosition(ctx.terrainGrid, cellSize, e.position_m.x, e.position_m.y, ctx.tractionCoeff);
-    const caps = deriveMovementCaps(e.attributes, e.loadout, { tractionCoeff: traction });
+    const caps = deriveMovementCaps(e.attributes, e.loadout, {
+        tractionCoeff: traction,
+        ...(ctx.biome?.gravity_mps2 !== undefined ? { gravity_mps2: ctx.biome.gravity_mps2 } : {}),
+    });
     const func = deriveFunctionalState(e, tuning);
     // Capability gating
     if (!func.canAct) {
@@ -151,6 +154,15 @@ export function stepMovement(e, world, ctx, tuning) {
     const targetVel = scaleDirToSpeed(dir, vTargetMag);
     e.velocity_mps = accelToward(e.velocity_mps, targetVel, effAmax);
     e.velocity_mps = clampSpeed(e.velocity_mps, effVmax);
+    // Phase 68: biome drag — attenuate velocity when dragMul < SCALE.Q (e.g. underwater).
+    const dragMul = ctx.biome?.dragMul;
+    if (dragMul !== undefined && dragMul < SCALE.Q) {
+        e.velocity_mps = {
+            x: mulDiv(e.velocity_mps.x, dragMul, SCALE.Q),
+            y: mulDiv(e.velocity_mps.y, dragMul, SCALE.Q),
+            z: mulDiv(e.velocity_mps.z, dragMul, SCALE.Q),
+        };
+    }
     // Phase 6: obstacle blocking — impassable cells (coverFraction = q(1.0)) prevent entry.
     const nextPos = integratePos(e.position_m, e.velocity_mps, DT_S);
     if (ctx.obstacleGrid) {