@adatechnology/game-contracts 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -71,11 +71,18 @@ interface PartSpec {
         fluid: FluidKind;
         liters: number;
         pressurized?: boolean;
+        /**
+         * Object-local direction the fluid leaves through a hole (the `leak` event's `direction`), for a fluid that does not spray back out of the hole
+         * but runs down through it: the water on a roof membrane goes `[0, -1, 0]` into the floor below. Default: out of the hole (its normal).
+         */
+        outflow?: Vec3;
     };
     /** The part explodes when destroyed, or when its temperature passes `atC` (gas bottle, fuel tank, aerosol). */
     explodes?: {
         energy: number;
         radius: number;
+        /** Inside this radius (metres) the blast is lethal to a body; from here to `radius` it only hurts, less with distance. Without it a body takes the energy falling off over `radius`. */
+        lethalRadius?: number;
         atC?: number;
         /**
          * Chain reaction: what sets the part off before it is destroyed and the seconds from that to the blast (a number, or `[min, max]` drawn
@@ -98,6 +105,8 @@ interface PartSpec {
     structure?: {
         role: StructureRole;
         capacity?: number;
+        rebar?: TensionRebar;
+        pile?: PileSpec;
     };
     /**
      * Coats over the core, outermost first (plaster, tile, the paper of a drywall board). `thickness` of the part is the core only; each coat adds
@@ -114,6 +123,18 @@ interface PartSpec {
      * `radius` metres of a point that adds up to `area` square metres opens the part: stage 2, the part stays with an opening.
      */
     breach?: PartBreach;
+    /**
+     * The part is a tuned mass damper: a mass on springs and dashpots near the top of a building that moves against its sway (`wind`). Its `mass` is the
+     * damper's mass and enters the load like any other part. Without `frequency` and `damping` the world tunes it to the building (Den Hartog).
+     */
+    damper?: TunedMassDamper;
+}
+/** A tuned mass damper (`PartSpec.damper`). */
+interface TunedMassDamper {
+    /** Natural frequency of the damper on its springs, in Hz (default: tuned to the first mode of the building by `wind.tuning`). */
+    frequency?: number;
+    /** Damping ratio of the damper (default: the optimum for its mass ratio). */
+    damping?: number;
 }
 /** A coat over a part's core. `faces` says on which side(s) of the part's thinnest axis it lies (`'+'` and `'-'` are the local +/- directions). */
 interface SurfaceLayer {
@@ -132,6 +153,48 @@ interface Reinforcement {
     /** Fraction of the part's structural capacity the bare cage keeps (default 0.15). */
     residualCapacity?: number;
 }
+/**
+ * Tension steel of a concrete beam, slab, roof or stair for the bending model (`DestructionOptions.structure.flexure`), when it is not taken from the
+ * `reinforcement` cage. `ratio` is the steel area over the effective section of the tension face, `As / (b * d)` (NBR 6118: at least 0.15% for
+ * C25-C30; beams 0.5-1.5%, slabs 0.2-0.6%). Unlike `reinforcement` it draws no bars and does not stage the part.
+ */
+interface TensionRebar {
+    /** `As / (b * d)` of the tension face, 0..0.04. */
+    ratio: number;
+    /** Yield strength of the steel in MPa (default `flexure.rebarYieldMPa`, 500 = CA-50). */
+    yieldMPa?: number;
+    /** Concrete cover to the bar in metres (default `flexure.cover`). */
+    cover?: number;
+}
+/**
+ * Deep foundation under a `foundation` part (its pile cap): `count` concrete piles of `diameter` going `length` metres down from the bottom of the
+ * part, laid out in a grid under it. They carry the load by end bearing at the tip and skin friction along the shaft, from the soil layers they go
+ * through (`DestructibleSpec.soil`). Without it a foundation part is a shallow footing (pad, strip or raft) that bears on the soil under it.
+ */
+interface PileSpec {
+    /** Metres below the bottom of the part. */
+    length: number;
+    /** Metres. */
+    diameter: number;
+    /** Piles under the part (default 1). */
+    count?: number;
+    /** `bored` (cast in place, the default) or `driven` (precast): how much of the soil's resistance the pile mobilises. */
+    method?: 'bored' | 'driven';
+}
+/** One layer of soil, from the top down. `soil` is a soil class id (`clay_soft`, `sand_dense`, `rock`...); the last layer goes on forever. */
+interface SoilLayer {
+    soil: string;
+    /** Metres (ignored on the last layer). */
+    thickness?: number;
+}
+/** The ground under an object. Settlement, tilt and bearing failure are computed only for objects that have one. */
+interface SoilProfile {
+    layers: readonly SoilLayer[];
+    /** Object-local height of the ground surface (default: the top of the highest foundation part). */
+    surface?: number;
+    /** Width a footing has at least where a part rests on a foundation tagged `terrain` (default 0.6 m, the NBR 6122 minimum). */
+    footingWidth?: number;
+}
 /** Size of one masonry unit in the part's axes (`size[2]` is along the part's thinnest axis, clamped to it) and how rows are laid. */
 interface PartUnits {
     size: Vec3;
@@ -186,6 +249,31 @@ interface DestructibleSpec {
     joints?: JointSpec[];
     /** Free tags (`furniture`, `vehicle`, `plant`, `structure`, `weapon`, `item`...). */
     tags?: string[];
+    /**
+     * The ground the object stands on: a soil class id (one layer) or a profile. With it the foundations bear on the soil: the object settles, tilts
+     * and, when the soil cannot carry it, sinks and tips over (`ObjectState.soil`, `settle` events). Without it the foundations are fixed as before.
+     */
+    soil?: string | SoilProfile;
+    /**
+     * How this object takes the wind of the world (`DestructionOptions.wind`): where it stands and what shape it has. Each field replaces the world's for
+     * this object. `false` keeps the object out of the wind. Without the world's `wind` it does nothing.
+     */
+    wind?: WindExposure | false;
+}
+/** What belongs to the place and the shape of one building in the wind (`DestructibleSpec.wind`; the world's `wind` has the same fields as defaults). */
+interface WindExposure {
+    /** Roughness category of the terrain around it, `I` (sea, flat water) to `V` (city centre with tall buildings): NBR 6123 table 1. */
+    terrain?: 'I' | 'II' | 'III' | 'IV' | 'V';
+    /** Class by the largest dimension, `A` up to 20 m, `B` to 50 m, `C` above (`auto`: from the building). */
+    class?: 'auto' | 'A' | 'B' | 'C';
+    /** Topographic factor S1 (1: flat ground; a hill top is above 1). */
+    topography?: number;
+    /** Statistical factor S3 (1: homes and offices; 1.1 for essential buildings). */
+    statistical?: number;
+    /** Drag coefficient Ca of the whole building (1.3: windward 0.8 + leeward 0.5). */
+    drag?: number;
+    /** Structural damping ratio of the first mode (0.016: reinforced concrete). */
+    damping?: number;
 }
 type DamageType = 
 /** bullets and pellets: `energy`, `caliber`; makes holes, dents, cracks, ricochets */
@@ -272,6 +360,18 @@ interface BlastReport {
     /** Fragment hits that landed on this target. */
     fragmentHits: number;
 }
+/**
+ * How likely a round is to set flammable vapour or fuel alight when it hits a container of it, as the weapons module resolves them for the round
+ * (core, jacket, incendiary or tracer composition, each with a configured chance). 0..1 each, per hit.
+ */
+interface HitIgnition {
+    /** Sparks from a hard core or jacket striking metal: counts only when the struck part is metal. */
+    spark: number;
+    /** A flame the round carries (incendiary, tracer): counts whatever it hits. */
+    flame: number;
+}
+/** The ballistic fields of a `Hit` that come from the round and not from the shot geometry (see `shotExtras`). */
+type BallisticExtras = Pick<Hit, 'piercing' | 'penetration' | 'incendiary' | 'tracer' | 'ignition'>;
 interface Hit {
     type: DamageType;
     /** Point of the hit (world space unless `space: 'local'`). For `explosive` it is the centre of the blast. */
@@ -284,6 +384,8 @@ interface Hit {
     caliber?: number;
     /** Radius of effect in metres (blast radius, flame radius, blunt contact radius). */
     radius?: number;
+    /** `explosive` only: inside this radius (metres) a body takes the blast as lethal; between it and `radius` it is hurt, less with distance. */
+    lethalRadius?: number;
     /** Source temperature for `fire` and `heat`. */
     temperature?: number;
     /** Seconds the heat is applied for (a flamethrower calls `hit` every frame with `duration: dt`). */
@@ -303,6 +405,19 @@ interface Hit {
      * less steel than its joules say, an armour-piercing core more: the energy that counts against the penetration of a hard material (metal, masonry) is `energy * piercing`; wood, glass and soft materials take the energy as it is.
      */
     piercing?: number;
+    /**
+     * Ballistic: how far the projectile goes through, in millimetres, by material class (`steel`, `concrete`, `brick`, `wood`, or a material id). The world
+     * takes the entry of the struck material (its `penetrationClass`, else its id, scaled by its `penetrationScale`) and the bullet goes through when it is
+     * at least as thick as the part; a material with no entry falls back to the energy rule (`energy` and `piercing`). The engine reads no calibre
+     * names: the weapons put the numbers here (`ammo.penetration` of `@adatechnology/game-weapons`, scaled by the energy left at the hit).
+     */
+    penetration?: Readonly<Record<string, number>>;
+    /** Ballistic: the round carries an incendiary composition (it can light flammable vapour and fuel whatever it hits). */
+    incendiary?: boolean;
+    /** Ballistic: the round is a tracer (a burning pyrotechnic in the base). */
+    tracer?: boolean;
+    /** Ballistic: chances that the round lights flammable vapour or fuel (see `HitIgnition`). Absent: it never does. */
+    ignition?: HitIgnition;
     /** Explosive: pressure multiplier the host knows (a room volume); the energy is then `energy * confinement` and the ray estimate is skipped. */
     confinement?: number;
     /** Explosive: per-call blast options (see `BlastOptions`). */
@@ -332,6 +447,8 @@ interface Hole {
     diameter: number;
     /** The projectile went through. */
     through: boolean;
+    /** An opening made on purpose (`DestructionWorld.vent`: a valve, a tap), not damage: `seal` closes it. */
+    vent?: boolean;
 }
 interface Crack {
     point: Vec3;
@@ -372,6 +489,16 @@ interface PartState {
     stress?: number;
     /** Damage stage; only present on parts that opted in (see `PartSpec.breach`). */
     stage?: DamageStage;
+    /**
+     * Beams, slabs, roofs and stairs of a material with `strength.tensileMPa` only: bending moment at rest over the moment the section holds (the steel's
+     * when it is reinforced and holds more than the concrete's cracking moment, else the cracking moment). `stress` is the largest of this and the
+     * compression ratio.
+     */
+    flexure?: number;
+    /** Axial force the wind adds to a wall or column, in newtons (compression positive, tension negative; `DestructionOptions.wind`). */
+    wind?: number;
+    /** The tension face cracked (a blast, an impact or the load bent it past the cracking moment): the concrete no longer carries tension, the steel does. */
+    cracked?: boolean;
     /** Reinforced part whose concrete is gone: only the rebar cage is left (capacity x `residualCapacity`); it is still part of the structure. */
     stripped?: boolean;
     /** Opening a breach left, in object-local space (stage 2). Raycasts and shots pass through it. */
@@ -382,6 +509,61 @@ interface PartState {
     /** Index into `ObjectState.groups` of the piece this part belongs to (-1 when the part is broken, melted or ash). */
     group: number;
 }
+/** How the ground under an object is holding (`DestructibleSpec.soil`). */
+interface SoilState {
+    /** Metres the foundations went down, at their centre of stiffness. */
+    settlement: number;
+    /** Degrees the object leans from the vertical. */
+    tilt: number;
+    /** Object-local horizontal unit vector the top leans toward (zero when it stands straight). */
+    direction: Vec3;
+    /** Weight of the object over what its foundations can carry before the soil gives way (above 1 it sinks). */
+    bearing: number;
+    /** Largest share of its capacity any foundation (a strip of a footing, a pile) is using, 0..1: at 1 the soil under it is yielding. */
+    edge: number;
+    /** `stable`: at rest; `yielding`: the soil is giving way and the object is still moving; `toppled`: it tipped over. */
+    status: 'stable' | 'yielding' | 'toppled';
+    /**
+     * The settled pose relative to the pose the host gave (`setTransform`), in object-local space: draw the object's parts under a node with this
+     * transform. `ObjectState.position` and `rotation` already include it.
+     */
+    offset: {
+        position: Vec3;
+        rotation: Quat;
+    };
+}
+/** How a building is taking the wind (`DestructionOptions.wind`). */
+interface WindState {
+    /** Basic speed of the wind in m/s. */
+    speed: number;
+    /** Design pressure at the top, N/m². */
+    pressure: number;
+    /** Design shear at the base, N (the sum of the forces on every storey). */
+    shear: number;
+    /** Design overturning moment at the base, N m. */
+    moment: number;
+    /** Top deflection under the design wind, metres. */
+    deflection: number;
+    /** Top deflection over the height (the drift) and its limit (default 1/500). */
+    drift: number;
+    limit: number;
+    /** Overturning moment over what the weight resists (above 1 the building tips over on its foundation). */
+    overturn: number;
+    /** First-mode frequency in Hz. */
+    frequency: number;
+    /** Top deflection under the mean wind, metres: how far the building leans while the wind blows. */
+    lean: number;
+    /** Swing of the top about that lean now and its recent peak, metres, along the wind. */
+    sway: number;
+    peak: number;
+    /** Tuned mass damper: mass over the modal mass and its travel against the top now, metres. */
+    damper?: {
+        ratio: number;
+        travel: number;
+    };
+    /** `ok`; `drift`: the drift is over its limit; `overturn`: the overturning moment passes what the weight resists. */
+    status: 'ok' | 'drift' | 'overturn';
+}
 interface JointState {
     id: string;
     a: string;
@@ -410,6 +592,10 @@ interface ObjectState {
     groups: string[][];
     /** Every part is broken, melted or ash. */
     destroyed: boolean;
+    /** Only objects with `DestructibleSpec.soil`: how the ground under it is holding. */
+    soil?: SoilState;
+    /** Only structures in the wind of the world (`DestructionOptions.wind`): the load, the drift and the sway of the building. */
+    wind?: WindState;
     /** Only objects that are a living body (a character, an animal): the summary the crowd and the HUD read. */
     body?: {
         alive: boolean;
@@ -535,6 +721,7 @@ type DestructionEvent = (EventBase & {
     point: Vec3;
     energy: number;
     radius: number;
+    lethalRadius?: number;
     effect?: string;
 })
 /** An explosive part was set off by a bullet, fire or a nearby blast and will explode `delay` seconds from now (`explodes.chain`). */
@@ -552,6 +739,32 @@ type DestructionEvent = (EventBase & {
     stress: number;
     load: number;
 })
+/**
+ * The ground under an object moved (`DestructibleSpec.soil`): it settled or leans more, the soil started or stopped yielding, or it tipped over
+ * (`status: 'toppled'`, followed by a `collapse` of everything). Throttled to once per 0.5 s while it moves. `direction` is in world space.
+ */
+ | (EventBase & {
+    type: 'settle';
+    settlement: number;
+    tilt: number;
+    direction: Vec3;
+    bearing: number;
+    status: SoilState['status'];
+})
+/**
+ * A building in the wind (`DestructionOptions.wind`) changed how it stands: the drift went over its limit or came back, the overturning moment passed
+ * what the weight resists, or the sway of the top grew. Throttled to once per 0.5 s. `direction` is the wind's, in world space.
+ */
+ | (EventBase & {
+    type: 'sway';
+    sway: number;
+    peak: number;
+    drift: number;
+    overturn: number;
+    frequency: number;
+    direction: Vec3;
+    status: WindState['status'];
+})
 /** A group with structural parts lost every anchored part (an anchored part exists in the object): it falls. Reported once per group. */
  | (EventBase & {
     type: 'collapse';
@@ -653,6 +866,79 @@ interface RayHit {
     distance: number;
 }
 
+/**
+ * What the host lends a module so that a slow job never looks like a frozen page: the host shows its own indicator (a spinner, a bar, a line of text) while the job runs. Nothing here is
+ * specific to a kind of module; a host with no indicator leaves `ModuleHost.loading` out and the module just does the work.
+ */
+interface BusyTask {
+    /** Updates the text and, when the task has a `total`, how many steps are done (the bar). Both optional. */
+    step(text?: string, done?: number): void;
+    /** Resolves after the browser painted what the task shows: await it between the steps of a long job so the indicator moves. */
+    paint(): Promise<void>;
+    /** Takes the indicator down (the last open task of the host hides it). Safe to call twice. */
+    end(): void;
+}
+interface BusyOptions {
+    /** How many steps the job has: the indicator draws a bar. Without it, only a spinner. */
+    readonly total?: number;
+    /** The indicator hides what is behind it (the first load of a page) instead of dimming it. */
+    readonly opaque?: boolean;
+}
+interface BusySink {
+    /** Shows the indicator at once and returns the task to update and end. The work that follows only paints it if the caller awaits `task.paint()` first. */
+    begin(label: string, options?: BusyOptions): BusyTask;
+    /**
+     * Shows the indicator, waits for it to be painted, runs `work` (synchronous work too) and takes the indicator down when it finishes or throws. Resolves with the result of `work`. The way to
+     * run a heavy synchronous job: the page shows what is going on instead of freezing.
+     */
+    busy<T>(label: string, work: (task: BusyTask) => T | Promise<T>, options?: BusyOptions): Promise<T>;
+}
+
+/**
+ * The numbers of the shove a blast gives to a body that moves (a loose item, a piece of furniture, a person): all of them a game value, with a default that reads well in a room,
+ * not a physical table. A host reads them once and lends them to the modules that move their own bodies (`ModuleHost.blastShove`).
+ */
+interface BlastShoveOptions {
+    /**
+     * The share of the blast energy that reaches a body as motion: the speed at the centre is `sqrt(2 * energy * coupling / mass)`, before the falloff (default 0.02).
+     */
+    readonly coupling?: number;
+    /** Fastest a body is thrown, in m/s, at the centre of the blast (default 20). */
+    readonly maxSpeed?: number;
+    /** How much of the push goes up: the direction is `(away, lift)` normalised from the horizontal outward direction (default 0.3). */
+    readonly lift?: number;
+    /** Below this speed (m/s) nothing moves: a heavy thing far from a small blast stays where it is (default 0.3). */
+    readonly minSpeed?: number;
+    /** Exponent of the falloff `(1 - distance / radius) ^ power`, the same as the damage of the destruction world (default 2). */
+    readonly falloffPower?: number;
+}
+/** The defaults of `BlastShoveOptions`. */
+declare const DEFAULT_BLAST_SHOVE: Readonly<Required<BlastShoveOptions>>;
+/** A blast as the shove reads it: where, how much energy (J) and how far it reaches (m). `reach` (0..1) is the share that got through what stood in the way. */
+interface BlastSource {
+    readonly point: Vec3;
+    readonly energy: number;
+    readonly radius: number;
+    readonly reach?: number;
+}
+/** What a blast does to one body: how fast it leaves (m/s), the unit direction it leaves in, and how far from the centre it was. */
+interface BlastShove {
+    readonly speed: number;
+    readonly direction: Vec3;
+    readonly distance: number;
+    /** The falloff applied, 0..1. */
+    readonly falloff: number;
+}
+/**
+ * The shove a blast gives to a body of `mass` kg whose centre is at `position`: away from the centre, lifted a little, with the speed
+ * `min(maxSpeed, sqrt(2 * energy * reach * coupling / mass)) * (1 - distance / radius) ^ 2`. Undefined when the body is outside the radius or the speed is under `minSpeed`.
+ * The same rule moves the loose items and furniture of the test room and the people of the characters module, so a game that tunes the options tunes all of them.
+ */
+declare function blastShove(blast: BlastSource, target: {
+    readonly position: Vec3;
+    readonly mass: number;
+}, options?: BlastShoveOptions): BlastShove | undefined;
+
 /**
  * What a game module implements for an object whose behaviour it owns (a vehicle with its own panel deformation, a creature, a machine). The
  * world (`DestructionWorld.register`) hosts it next to its own objects: raycast, shoot, explode, hit, disassemble, extinguish, update, state,
@@ -770,7 +1056,21 @@ interface Shot {
     /** snake_case weapon id. */
     weapon: string;
     source?: string;
+    /** Kind of the round that was loaded (`fmj`, `hp`, `ap`, `buck`, `slug`, `incendiary`, `tracer`...). */
+    ammo?: string;
+    /** Millimetres of steel, concrete, brick and wood the round goes through at the muzzle (the ammo table of the weapons module). `shotToHit` scales it by the energy left. */
+    penetration?: Readonly<Record<string, number>>;
+    incendiary?: boolean;
+    tracer?: boolean;
+    /** Chances that the round lights flammable vapour or fuel. */
+    ignition?: HitIgnition;
 }
+/**
+ * The fields of the round that a damage model takes besides the geometry: the penetration by material scaled by the energy that is left at `distance`
+ * (linear in the energy: half the energy goes through half as much), the incendiary and tracer flags and the ignition chances. Pass it as the sixth
+ * argument of `DestructionWorld.shoot` or spread it in a `Hit`.
+ */
+declare const shotExtras: (shot: Shot, distance?: number) => BallisticExtras;
 /** One use of a non-firearm (melee swing, flame tick, heat tick, throw, tool tick, extinguisher tick). */
 type Use = {
     kind: 'melee';
@@ -882,6 +1182,75 @@ type Use = {
  * change the hit; it is accepted so that callers can pass what their raycast returned and so that a stricter implementation could use it.
  */
 declare const shotToHit: (shot: Shot, point: Vec3, normal?: Vec3) => Hit;
+/**
+ * The `Hit` a non-firearm `Use` makes at `point` (world space), or `null` for uses that do not damage by themselves.
+ *
+ * - `melee` -> `blunt` / `slash` with the swing's `energy`, contact `radius` and `direction`;
+ * - `flame` -> `fire` and `heat` -> `heat`, with `temperature`, `duration` and a contact radius of at most 0.3 m (one ray of the cone);
+ * - `throw` -> the blast (`explosive`, `energy`, `radius`, centred on `point`, the place it detonates). A thrown item with no blast energy but
+ *   a `fire` patch (a molotov) gives that patch as a `fire` hit (`temperature`, `radius`, `seconds` as `duration`). No energy and no fire -> `null`;
+ * - `tool`, `extinguish` and `hand` -> `null` (tools work on joints, the extinguisher cools, the hand only grabs).
+ *
+ * `normal` does not change the hit (same as `shotToHit`).
+ */
+declare const useToHit: (use: Use, point: Vec3, normal?: Vec3) => Hit | null;
+
+/**
+ * How a container of flammable fluid (a fuel tank, a jerrycan, a gas bottle) is set alight by what hits it. A normal bullet that goes through only
+ * makes a leak; the leak lights when something supplies a flame: a spark of a hard round on metal, an incendiary or tracer round, a fire nearby
+ * or a blast. These are the numbers of the target side; the numbers of the round (core, jacket, incendiary, tracer) are in the weapons module
+ * (`rules.ignition` of `@adatechnology/game-weapons`) and reach the target in `Hit.ignition`. Every number is a default to be changed per game.
+ */
+interface IgnitionRules {
+    /**
+     * How much of the spark and of the flame of a round reaches the vapour, by how full the container is: points `[filled, factor]`, `filled` 0..1
+     * (litres over capacity), `factor` 0..1, linear between points. A full container holds a mixture too rich to burn (the vapour has no air) and
+     * mostly leaks; a nearly empty one holds the vapour/air mixture of a flammable range and lights the easiest; a dry one has little vapour left.
+     * Default: 0.6 empty, 1 at 10 percent, 0.6 at 35, 0.3 at 65, 0.15 at 90 and 0.12 full.
+     */
+    fillCurve: ReadonlyArray<readonly [number, number]>;
+    /** 0..1: how much of the fill factor also weighs on the flame of an incendiary or tracer (1: as much as on a spark; 0: not at all). Default 0.5. */
+    flameFillInfluence: number;
+    /** Chance of the flame of a round that is flagged `incendiary` or `tracer` but carries no `ignition` numbers (a host that passes only the flags). */
+    flameDefaults: {
+        incendiary: number;
+        tracer: number;
+    };
+    /**
+     * What a spark needs to strike: a factor 0..1 by material id of the struck part. A material that is not listed but is metal takes
+     * `sparkMetalDefault`; a part that is not metal never sparks. Default: steel and iron 1, aluminium 0.25.
+     */
+    sparkTarget: Readonly<Record<string, number>>;
+    sparkMetalDefault: number;
+    /**
+     * Factor 0..1 on the spark by fluid (default 1): diesel has a flash point of 52 degrees C and more, so a spark that lights petrol vapour does
+     * not light it (a flame does). Default: diesel 0.15.
+     */
+    sparkFluid: Readonly<Record<string, number>>;
+    /** A leaking container of flammable fluid within `radius` metres of a burning part or a burning fuel stain lights at `chancePerSecond`. */
+    fireNear: {
+        radius: number;
+        chancePerSecond: number;
+    };
+}
+/** Defaults of `IgnitionRules`. */
+declare const DEFAULT_IGNITION_RULES: IgnitionRules;
+/** Merges a partial `IgnitionRules` over the defaults (an object is merged one level deep). */
+declare const resolveIgnitionRules: (rules?: Partial<IgnitionRules>) => IgnitionRules;
+/** Linear interpolation of the fill curve at `fill` (0..1); outside the points it keeps the first or the last. */
+declare const fillFactor: (fill: number, curve?: IgnitionRules["fillCurve"]) => number;
+/** The factor of what a spark strikes: 0 when the struck part is not metal. */
+declare const sparkTargetFactor: (materialId: string, metal: boolean, rules?: IgnitionRules) => number;
+/**
+ * Chance that one round that went through the wall of a container lights the fluid that leaks: the spark (only on metal) and the flame (any
+ * wall), each weighed by the fill of the container; the two are independent. 0 when the round carries nothing (`Hit.ignition` absent and not
+ * flagged `incendiary` or `tracer`): a plain bullet on a plain wall only leaks.
+ */
+declare const ignitionChance: (hit: Pick<Hit, "incendiary" | "tracer" | "ignition">, target: {
+    sparkTarget: number;
+    fill: number;
+    fluid?: string;
+}, rules?: IgnitionRules) => number;
 
 /**
  * Fluid contract: what a module says about the liquid its item holds, and how the item is used. Types only: the liquids themselves, their
@@ -936,6 +1305,37 @@ interface ItemUseDef {
     liquids?: LiquidId[];
 }
 
+/**
+ * Where a hand should be, in world space. `position` is the middle of the palm; the orientation follows one convention for every hand: the hand-local +x runs from the wrist to the
+ * knuckles (the way the fingers point when open), +y is the back of the hand and +z completes the frame (for a right hand the little finger side; the thumb is at -z). A left hand is the
+ * mirror image of a right one, so the same numbers describe the same grip: its thumb is at +z.
+ */
+interface HandPose {
+    position: Vec3;
+    /** Unit quaternion `[x, y, z, w]`, hand-local to world. */
+    quaternion: [number, number, number, number];
+}
+/**
+ * What a tool in the hands asks of the hands that hold it (a weapon asks for a grip on its grip and handguard, a carried item for a hand under it). A side left out or null is not held:
+ * the hand stays in its rest stance. Nothing here knows what the tool is.
+ */
+interface HandTargets {
+    R?: HandPose | null;
+    L?: HandPose | null;
+    /** How closed the fingers are, 0 open to 1 closed on a grip. Default 1. */
+    grip?: number;
+    /** The same for the left hand, when it differs from `grip` (a hand laid on a forend is looser than the one on the trigger). */
+    gripL?: number;
+    /** The size of the hands against life size (a tool drawn smaller than real takes smaller hands). Default 1. */
+    scale?: number;
+    /** Fingers of the right hand that curl by themselves, 0 extended to 1 fully curled (the index finger of a trigger hand); the others follow `grip`. */
+    fingers?: {
+        index?: number;
+    };
+}
+/** Read every frame by whoever draws the arms; answers null while nothing is held. */
+type HandTargetSource = () => HandTargets | null;
+
 /**
  * The bench of a module: controls, layers and counters it declares as data. The host keeps the values, draws them in a generic way and hands
  * every change back through `ModuleHost.bench`. Nothing here is specific to a kind of module.
@@ -954,6 +1354,11 @@ interface ControlBase {
     readonly name: string;
     readonly hint?: string;
     readonly hidden?: boolean;
+    /**
+     * The change (or the press, for an action) takes a noticeable time, a third of a second or more: the host shows its loading indicator while it works, with this text, or the control's name for `true`.
+     * Only the host's own controls panel does it; a change made through `TestRoom.bench().set / act` runs at once.
+     */
+    readonly slow?: boolean | string;
 }
 interface NumberControl extends ControlBase {
     readonly kind: 'number';
@@ -1109,6 +1514,16 @@ interface EffectSink {
     catalog?(): readonly string[];
 }
 
+/**
+ * Throwaway meshes that use every kind of material a renderer makes later on demand (a hole decal, a stream of liquid, a puff of smoke). A host adds `group` to its scene for
+ * ONE render, so that the shader programs are built then and not in the middle of play (the first shot or leak stalls the frame otherwise), and calls `dispose` afterwards.
+ * `group` is the three.js `Object3D`: `unknown` here because the contracts do not depend on three.js.
+ */
+interface WarmUpProbes {
+    readonly group: unknown;
+    dispose(): void;
+}
+
 /** Pose of one part (or of the whole item) at a key: position offset in metres and Euler XYZ rotation in radians, both relative to the rest pose. */
 interface AnimationPose {
     position?: Vec3;
@@ -1274,6 +1689,8 @@ interface TestableItem {
     animations?: AnimationClipSpec[];
     /** Can be grabbed and thrown. */
     movable?: boolean;
+    /** Building it takes a noticeable time (a vehicle, a district): the host's catalogue shows its loading indicator while it spawns one. `true`, or the text to show. */
+    slow?: boolean | string;
     /**
      * A picture of the item for menus, search results and the label of the aimed item: the URL of an image (an SVG silhouette is drawn in the text colour, so give it one colour with
      * the tones as opacity) or the SVG markup itself (starts with `<svg`). Optional: an item without one shows its name only.
@@ -1444,6 +1861,10 @@ type HostEvent =
     radius: number;
     cause: string;
     explosive?: string;
+}
+/** The player crouched or stood up, or the camera mode changed; read the new state with `host.player()`. */
+ | {
+    type: 'player';
 };
 /** The tool in hand as the host sees it. */
 interface HostTool {
@@ -1506,6 +1927,21 @@ interface ToolCommandResult {
     readonly reason?: string;
     readonly seconds?: number;
 }
+/** The player as the host sees it. Generic: any game with someone walking around in a world has these. */
+interface PlayerState {
+    /** World position of the player's feet, metres. */
+    readonly position: Vec3;
+    /** Radians around the vertical axis; 0 looks down -z. */
+    readonly yaw: number;
+    /** Radians up (positive) or down (negative). */
+    readonly pitch: number;
+    readonly crouching: boolean;
+    /** Horizontal speed in metres per second. */
+    readonly speed: number;
+    readonly running: boolean;
+    /** How the camera follows the player (`first`, `shoulder`...); the ids are the host's. */
+    readonly cameraMode: string;
+}
 /**
  * What the host lends a module that brings its own presentation (a weapon in the hands, sounds, ejected casings). `THREE`, `scene` and `camera`
  * are the host's three.js namespace, scene and camera: `unknown` here because the contracts do not depend on three.js.
@@ -1518,6 +1954,8 @@ interface ModuleHost {
     /** Height of whatever things rest on at (x, z): the floor, a table, a counter. */
     groundAt(x: number, z: number): number;
     tool(): HostTool;
+    /** The player now: where, which way, crouching, how fast and how the camera follows. A `player` event tells when crouching or the camera mode changes. */
+    player(): PlayerState;
     /** Follow the player's tool events. Returns the unsubscribe function. */
     on(listener: (event: HostEvent) => void): () => void;
     /** Run every simulated frame with the frame's seconds. Returns the unsubscribe function. */
@@ -1527,8 +1965,8 @@ interface ModuleHost {
      * unsubscribe function. A host that never clears leaves it out.
      */
     onClear?(listener: () => void): () => void;
-    /** Write a line to the host's behaviour log. */
-    log(text: string, data?: Record<string, unknown>): void;
+    /** Write a line to the host's behaviour log; `type` is the kind of entry (default `module_note`), so a module can log what a filter looks for (`sound`). */
+    log(text: string, data?: Record<string, unknown>, type?: string): void;
     /**
      * Sets what the host lets a module tune on its tools, keyed by the id of the module's own control (`ModuleControl.id`) with the id of the option as the value; the tool in hand changes at once and the
      * ones taken later start that way. A host applies the ids it knows and ignores the rest. The test room knows `condition` (how worn the tools are) and `ammo_quality` (how good what they load is).
@@ -1539,6 +1977,11 @@ interface ModuleHost {
      * player stops at them; the function is asked on every step, so it may follow a door that opens. Returns the function that takes it away. A host without a walking player leaves it out.
      */
     addBlocker?(blocked: (x: number, z: number, radius: number) => boolean): () => void;
+    /**
+     * Lends the host the place of the hands for the tool in the module's hands (a weapon's grip and handguard): the host that draws the player's arms reads `source` every frame, after the
+     * frame hooks have run, and puts the hands there. Pass null (or call the returned function) to let go. A host without arms leaves it out.
+     */
+    setHandTargets?(source: HandTargetSource | null): () => void;
     /** Asks the tool in hand to do something (see `ToolCommand`). A host without accessories leaves it out. */
     command?(command: ToolCommand): ToolCommandResult;
     /** Lent only to a module that declares controls, layers or metrics. */
@@ -1549,6 +1992,13 @@ interface ModuleHost {
     environment?: EnvironmentBus;
     /** The host's effects (smoke, sparks, blast, impacts): a module asks for them by id instead of drawing its own. Absent when the host has none. */
     effects?: EffectSink;
+    /**
+     * The numbers of the shove a blast gives to a body. A module that moves bodies of its own (people, vehicles) answers the `explosion` host event with `blastShove(event, body, host.blastShove)`
+     * so that it throws things the way the host throws its loose items. Absent when the host keeps the defaults.
+     */
+    blastShove?: BlastShoveOptions;
+    /** The host's loading indicator: a module with a slow job of its own (building a house, laying a district) shows it through this instead of freezing the page. Absent when the host has none. */
+    loading?: BusySink;
 }
 /** What a module hands the test room: its items and, optionally, scenarios that exercise them, its area and its own presentation. */
 interface TestableModule<Context = unknown> {
@@ -1652,6 +2102,12 @@ interface ToolClipPlayer {
     apply(step: ToolAnimationStep): void;
     update(dt: number): void;
     readonly playing: readonly string[];
+    /** The clips being played with the time each has reached and the clip itself (scaled to the duration the rule gave), for a renderer that has to follow what the clip does now (the hands working a part). */
+    readonly running: ReadonlyArray<{
+        readonly name: string;
+        readonly time: number;
+        readonly clip: AnimationClipSpec;
+    }>;
 }
 declare const createToolClipPlayer: (options: ToolClipPlayerOptions) => ToolClipPlayer;
 
@@ -1670,4 +2126,97 @@ declare const mergeById: <TEntry extends Entry>(shipped: readonly TEntry[], extr
 declare const applyPatches: <TEntry extends Entry>(entries: Map<string, TEntry>, patches: Readonly<Record<string, DeepPartial<TEntry> | Partial<TEntry>>> | undefined) => void;
 declare const removeIds: (entries: Map<string, unknown>, ids: readonly string[] | undefined) => void;
 
-export { type ActionControl, type AnimationClipSpec, type AnimationEventSpec, type AnimationKey, type AnimationPose, type AreaPlacement, type AudioListener, type AudioSink, type BenchChange, type BenchDeclaration, type BenchReport, type BenchSheet, type BlastOptions, type BlastReport, type BodyRegion, type BodySlot, type BooleanControl, type ChainDelay, type CheckOptions, type CheckSpecOptions, type ChoiceControl, type ChoiceOption, type ConfinementOptions, type ContainerSpec, type ControlPatch, type ControlValue, type Crack, DEFAULT_ENVIRONMENT, type DamageStage, type DamageType, type DebrisKind, type DeepPartial, type Dent, type DestructibleImpl, type DestructibleSpec, type DestructionEvent, type DestructionEventType, type EffectHandle, type EffectRequest, type EffectSink, type EnvironmentBus, type EnvironmentKey, type EnvironmentState, type ExplosionChain, type FluidKind, type FractureStyle, type Fragment, type FragmentHitOptions, type FragmentMark, type Hit, type HitResult, type Hole, type HostEvent, type HostTool, type HostToolAttachment, IMPACT_CONTRACT, type ImpactContract, type ItemAnimationContract, type ItemUseDef, type JointKind, type JointSpec, type JointState, type LiquidId, type LoopHandle, MISSING_BITS, type MaterialId, type ModuleArea, type ModuleBench, type ModuleControl, type ModuleHost, type ModuleItemFluid, type ModuleLayer, type ModuleMetric, type ModuleScenario, type NumberControl, type ObjectState, type PartBreach, type PartShape, type PartSpec, type PartState, type PartStatus, type PartUnits, type Quat, type RayHit, type Reinforcement, STAGE_EVENT, type SegmentKind, type ShelterOptions, type Shot, type SoundHandle, type SoundRequest, type SpecReport, type StructureRole, type SurfaceLayer, TOOL_CLIP, type TestableItem, type TestableModule, type Thumbnail, type ToolAnimationStep, type ToolAnimator, type ToolClipId, type ToolClipPlayer, type ToolClipPlayerOptions, type ToolClipSet, type ToolCommand, type ToolCommandResult, type ToolKind, type ToolRig, type Use, type Vec3, applyPatches, checkAnimation, checkBench, checkDestructible, checkHit, checkSpec, checkToolClips, createEnvironmentBus, createToolClipPlayer, deepMerge, mergeById, removeIds, sampleClip, scaleClip, shotToHit, toolAnimationStep };
+/** One category (kind) of items. Defaults and required contracts are inherited from the `extends` chain. */
+interface CategoryDef<TDefaults extends object = Record<string, unknown>> {
+    readonly id: string;
+    /** Parent category id; the child inherits its defaults and its required contracts. */
+    readonly extends?: string;
+    /** Field values every entry of this kind starts with; objects merge down the chain, arrays replace. */
+    readonly defaults?: DeepPartial<TDefaults>;
+    /** Contract ids (`ContractChecker.id`) every entry of this kind, or of a descendant, must satisfy. */
+    readonly requires?: readonly string[];
+    /** An abstract category only groups: entries cannot declare it directly, only its descendants. */
+    readonly abstract?: boolean;
+}
+/** Where a checker is being run: the entry's kind and the chain of categories root first. */
+interface ContractContext {
+    readonly kind: string;
+    readonly chain: readonly string[];
+}
+/** A named contract: returns the problems of an entry, each a short phrase like `missing leftover.despawnSeconds`. Empty means it holds. */
+interface ContractChecker<TEntry> {
+    readonly id: string;
+    check(entry: TEntry, ctx: ContractContext): string[];
+}
+interface CategoryOptions {
+    /** Categories added to the shipped ones; the same id replaces. */
+    readonly extra?: readonly CategoryDef[];
+    /** Partial changes by id, applied after `extra`. */
+    readonly patches?: Readonly<Record<string, DeepPartial<CategoryDef> | Partial<CategoryDef>>>;
+    /** Ids taken out of the tree (their children are then reported by `check()`). */
+    readonly remove?: readonly string[];
+}
+interface CategoryRegistry {
+    get(id: string): CategoryDef | undefined;
+    has(id: string): boolean;
+    ids(): string[];
+    /** Root first, ending at `id`. Throws on an unknown id, an unknown parent or a cycle. */
+    chain(id: string): string[];
+    /** `defaults` merged along the chain, root first, so the closest category wins. */
+    defaults(id: string): Record<string, unknown>;
+    /** Union of `requires` along the chain, order kept, without duplicates. */
+    requires(id: string): string[];
+    /** True when `id` is `ancestorId` or descends from it. */
+    isA(id: string, ancestorId: string): boolean;
+    /** Problems in the tree itself: duplicate ids, unknown `extends`, cycles. */
+    check(): string[];
+}
+interface CategorizedOptions {
+    /** Field of the entry that names its category. Default `kind`. */
+    readonly kindField?: string;
+    /** Known gaps by entry id: problems starting with one of these texts go to `allowed`, so the list can shrink over time. */
+    readonly allow?: Readonly<Record<string, readonly string[]>>;
+}
+interface CategorizedReport {
+    readonly ok: boolean;
+    readonly problems: string[];
+    readonly allowed: string[];
+}
+declare const defineCategories: (defs: readonly CategoryDef[], options?: CategoryOptions) => CategoryRegistry;
+/** The entry with the defaults of its category underneath: the entry wins, objects merge, arrays replace. */
+declare const resolveEntry: <TEntry extends object>(registry: CategoryRegistry, entry: TEntry, kindField?: string) => TEntry;
+/** Checks that each entry has a known, concrete kind and satisfies every contract its chain requires. */
+declare const checkCategorized: <TEntry extends {
+    readonly id: string;
+}>(entries: readonly TEntry[], registry: CategoryRegistry, checkers: readonly ContractChecker<TEntry>[], options?: CategorizedOptions) => CategorizedReport;
+
+/**
+ * Where a drawn object comes from. Every builder of the kit that draws a piece (a car of the fleet, a house or a wall, a piece of furniture, a person, an
+ * animal, a plant, an item, a weapon) marks the root it returns, and every renderer that draws for the room (effects, debris, liquids, the room itself)
+ * marks its own roots, so a host can tell a piece of the kit from something drawn on the spot. Duck-typed on three.js objects (`userData`, `parent`,
+ * `children`), so the contracts stay free of three.js.
+ */
+declare const KIT_ORIGIN_KEY = "kitOrigin";
+/** What drew an object: the package and the kind of piece (`vehicle`, `structure`, `furniture`, `person`... or `effect`, `room` for what is not a piece). */
+interface KitOrigin {
+    readonly owner: string;
+    readonly kind: string;
+    /** The catalogue id of the piece, when it has one. */
+    readonly id?: string;
+    /** Drawn as a simple stand-in shape because the kit has no model of the piece yet (an item with no team model): a model still to make. */
+    readonly standIn?: boolean;
+}
+/** Marks `object` as drawn by `origin.owner` and returns it. */
+declare function markKitOrigin<T>(object: T, origin: KitOrigin): T;
+/** The origin of the object or of its nearest marked ancestor; null when nothing up the tree is marked. */
+declare function kitOriginOf(object: unknown): KitOrigin | null;
+/** A drawn thing that no builder of the kit marked: what was drawn on the spot. */
+interface UnmarkedDrawing {
+    /** The names of the object and its named ancestors, outermost first. */
+    readonly path: string;
+    readonly object: unknown;
+}
+/** Every visible mesh, line, point cloud or sprite under `root` with no marked ancestor (`root` itself not counted as one). */
+declare function unmarkedDrawings(root: unknown): UnmarkedDrawing[];
+
+export { type ActionControl, type AnimationClipSpec, type AnimationEventSpec, type AnimationKey, type AnimationPose, type AreaPlacement, type AudioListener, type AudioSink, type BallisticExtras, type BenchChange, type BenchDeclaration, type BenchReport, type BenchSheet, type BlastOptions, type BlastReport, type BlastShove, type BlastShoveOptions, type BlastSource, type BodyRegion, type BodySlot, type BooleanControl, type BusyOptions, type BusySink, type BusyTask, type CategorizedOptions, type CategorizedReport, type CategoryDef, type CategoryOptions, type CategoryRegistry, type ChainDelay, type CheckOptions, type CheckSpecOptions, type ChoiceControl, type ChoiceOption, type ConfinementOptions, type ContainerSpec, type ContractChecker, type ContractContext, type ControlPatch, type ControlValue, type Crack, DEFAULT_BLAST_SHOVE, DEFAULT_ENVIRONMENT, DEFAULT_IGNITION_RULES, type DamageStage, type DamageType, type DebrisKind, type DeepPartial, type Dent, type DestructibleImpl, type DestructibleSpec, type DestructionEvent, type DestructionEventType, type EffectHandle, type EffectRequest, type EffectSink, type EnvironmentBus, type EnvironmentKey, type EnvironmentState, type ExplosionChain, type FluidKind, type FractureStyle, type Fragment, type FragmentHitOptions, type FragmentMark, type HandPose, type HandTargetSource, type HandTargets, type Hit, type HitIgnition, type HitResult, type Hole, type HostEvent, type HostTool, type HostToolAttachment, IMPACT_CONTRACT, type IgnitionRules, type ImpactContract, type ItemAnimationContract, type ItemUseDef, type JointKind, type JointSpec, type JointState, KIT_ORIGIN_KEY, type KitOrigin, type LiquidId, type LoopHandle, MISSING_BITS, type MaterialId, type ModuleArea, type ModuleBench, type ModuleControl, type ModuleHost, type ModuleItemFluid, type ModuleLayer, type ModuleMetric, type ModuleScenario, type NumberControl, type ObjectState, type PartBreach, type PartShape, type PartSpec, type PartState, type PartStatus, type PartUnits, type PileSpec, type PlayerState, type Quat, type RayHit, type Reinforcement, STAGE_EVENT, type SegmentKind, type ShelterOptions, type Shot, type SoilLayer, type SoilProfile, type SoilState, type SoundHandle, type SoundRequest, type SpecReport, type StructureRole, type SurfaceLayer, TOOL_CLIP, type TensionRebar, type TestableItem, type TestableModule, type Thumbnail, type ToolAnimationStep, type ToolAnimator, type ToolClipId, type ToolClipPlayer, type ToolClipPlayerOptions, type ToolClipSet, type ToolCommand, type ToolCommandResult, type ToolKind, type ToolRig, type TunedMassDamper, type UnmarkedDrawing, type Use, type Vec3, type WarmUpProbes, type WindExposure, type WindState, applyPatches, blastShove, checkAnimation, checkBench, checkCategorized, checkDestructible, checkHit, checkSpec, checkToolClips, createEnvironmentBus, createToolClipPlayer, deepMerge, defineCategories, fillFactor, ignitionChance, kitOriginOf, markKitOrigin, mergeById, removeIds, resolveEntry, resolveIgnitionRules, sampleClip, scaleClip, shotExtras, shotToHit, sparkTargetFactor, toolAnimationStep, unmarkedDrawings, useToHit };