@adatechnology/game-contracts 0.21.0 → 0.23.0

package/README.md

@@ -58,6 +58,8 @@ Hits arrive in world space and events go out in world space. `checkDestructible`
 well-formed and JSON-serializable. The contracts package does not know your materials: pass their ids (the world's `world.materials.keys()`) or
 leave `materials` out to skip that check.
 
+**Cost contract (D8):** the host reads `describe()` and `state()` per part per frame, so both are O(1), allocation-free and cached between changes (the same object comes back until a hit, tool, fire or pose change). `checkDestructible(impl, { cost: true })` (or `cost: { reads, ceilingMs, allocationBytes }`) reads each 10 000 times and fails on a new object per read, on time over the ceiling (default 50 ms) and, in Node, on heap growth over the ceiling (default 1 MiB).
+
 ### Weapons
 
 ```ts

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { w as warnOnce } from './testing-CJY18EZK.js';
+
 /**
  * Destruction contract: the types a game module and a destruction world share. A module (vehicle, furniture, plant, house, weapon) describes
  * itself with these and never needs the default destruction world; the world, the renderer and the test room consume them.
@@ -405,6 +407,8 @@ interface Hit {
     duration?: number;
     /** `world` (default) or `local` to the object. */
     space?: 'world' | 'local';
+    /** The normal of the surface at `point`, when the ray that found it knows it. */
+    normal?: Vec3;
     /** Who caused it (passed through to events). */
     source?: string;
     /** Projectile mass in grams (ballistic): the penetration of a body needs it, the energy alone does not say how much a bullet pushes. */
@@ -652,6 +656,8 @@ interface EventBase {
     /** Seconds since the world was created. */
     time: number;
     source?: string;
+    /** The kind of hit the event came out of (a shot, a blow, a cut, a blast...), when it came out of a hit; the sound of an impact is chosen by it. */
+    blow?: DamageType;
 }
 /** Points in events are in world space. */
 type DestructionEvent = (EventBase & {
@@ -675,7 +681,8 @@ type DestructionEvent = (EventBase & {
     exitPoint?: Vec3;
     powder?: {
         color: number;
-    };
+    }; /** Joules the round still carries out of the part, when the part knows. */
+    energyLeft?: number;
 }) | (EventBase & {
     type: 'crack';
     part: string;
@@ -981,6 +988,49 @@ declare function blastShove(blast: BlastSource, target: {
     readonly mass: number;
 }, options?: BlastShoveOptions): BlastShove | undefined;
 
+/** From this speed (m/s) a blast takes a standing body off its feet. Below it the body is only pushed. */
+declare const KNOCK_DOWN_SPEED = 2.5;
+/** The angle of a body lying where it fell (the same tilt a dead body takes). */
+declare const KNOCKED_DOWN_ANGLE = 1.35;
+/** Height of the chest above the feet: where the blast takes the body. */
+declare const KNOCK_CHEST = 1.1;
+/** What a blast is doing to one body: its velocity (m/s), whether it is in the air, and how far down it is (0 on its feet, 1 lying). */
+interface Knock {
+    velocity: [number, number, number];
+    airborne: boolean;
+    /** 0..1 */
+    lying: number;
+    /** Seconds left to lie on the ground after it stopped. */
+    lieLeft: number;
+    /** Knocked off its feet by this blast. */
+    down: boolean;
+}
+/** The mass of a body in kg from its height (m) and its build (1 = average): 70 kg at 1.75 m. */
+declare const bodyMass: (height: number, build?: number) => number;
+/**
+ * What a blast does to a body standing at `feet`: the shove of `game-contracts` taken at the chest, a hop when it goes up, and a fall when it is strong enough. Undefined when the blast does not
+ * reach it. The numbers are the host's (`ModuleHost.blastShove`), the same ones that throw its loose items.
+ */
+declare function knockOf(blast: BlastSource, feet: Vec3, mass: number, options?: BlastShoveOptions): Knock | undefined;
+/**
+ * Moves a body one step: it slides on the ground and slows, falls when it was knocked down, lies a while and gets up (a dead body stays down). Moves `position` in place; returns true when the
+ * body is on its feet and still, and the knock can be dropped.
+ */
+declare function stepKnock(knock: Knock, position: {
+    x: number;
+    y: number;
+    z: number;
+}, dt: number, groundAt: (x: number, z: number) => number, alive: boolean): boolean;
+
+interface CostOptions {
+    /** Reads of `state()` and of `describe()` to time. Default 10 000. */
+    reads?: number;
+    /** Ceiling, in milliseconds, for all the reads of one method. Default 50 (5 microseconds per read). */
+    ceilingMs?: number;
+    /** Ceiling of heap growth, in bytes, over all the reads of one method (only where `process.memoryUsage` exists). Default 1 MiB. */
+    allocationBytes?: number;
+}
+
 /**
  * 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,
@@ -990,17 +1040,47 @@ declare function blastShove(blast: BlastSource, target: {
  * `setTransform` is only used by the world for raycasts and blast range). Every event must carry `object === id` and name parts listed by
  * `describe()`.
  */
+/** World-space ray for `DestructibleImpl.surfaceRay`. */
+interface SurfaceRay {
+    readonly origin: Vec3;
+    readonly direction: Vec3;
+    readonly maxDistance: number;
+    ignored?(part: string): boolean;
+}
+interface SurfaceRayHit {
+    readonly part: string;
+    readonly point: Vec3;
+    readonly normal: Vec3;
+    readonly distance: number;
+    /** Thickness the ray crosses in this part, metres. */
+    readonly pathLen: number;
+}
 interface DestructibleImpl {
     readonly id: string;
     readonly name?: string;
-    /** Parts, joints and structure in the impl's local space, for raycast, inspector and log. Called often: keep it cheap. */
+    /**
+     * Parts, joints and structure in the impl's local space, for raycast, inspector and log.
+     * COST CONTRACT (D8): called per frame by the renderer, so it is O(1), allocation-free and cached between changes: the same object comes
+     * back until a hit, tool, fire or pose change alters it. `checkDestructible(impl, { cost: true })` measures it.
+     */
     describe(): DestructibleSpec;
     /** Apply one hit (see `IMPACT_CONTRACT` for the fields per type) and return the events it caused. */
     hit(hit: Hit): DestructionEvent[];
+    /**
+     * The real surface a ray meets, for an impl whose drawn shape is not its boxes (a car body): the boxes of `describe()` only say where to look, and a shot that crosses
+     * them without touching the drawn surface goes on. `ignored` answers for the parts the round already went through. Null when the ray meets nothing.
+     */
+    surfaceRay?(ray: SurfaceRay): SurfaceRayHit | null;
     /** Advance fire, melting, collapse and other timed behaviour. */
     update?(dt: number): DestructionEvent[];
-    state(): ObjectState;
+    /**
+     * COST CONTRACT (D8): the host reads it per part per frame, so it is O(1), allocation-free and cached between changes (see `describe()`).
+     * The cached object is shared with every reader: treat it as read-only, copy before changing it.
+     */
+    state(): Readonly<ObjectState>;
     reset?(): void;
+    /** The world took the object out (`DestructionWorld.remove`): the impl lets go of what it joined (shared queues, listeners). */
+    dispose?(): void;
     /** Same contract as `DestructionWorld.disassemble`: progress 0..1, or -1 when the tool cannot undo the joint. */
     disassemble?(jointId: string, tool: ToolKind, dt: number): number;
     extinguish?(partId?: string): void;
@@ -1025,11 +1105,13 @@ interface CheckOptions {
      * `world.materials`, or the built-in plus your own). When omitted, the material check is skipped.
      */
     materials?: Iterable<string>;
+    /** Opt-in cost measurement (D8): `true` for the defaults, or the limits to use. */
+    cost?: boolean | CostOptions;
 }
 /**
  * Contract checker for the test room (it needs no world): `describe()` is valid, a 500 J ballistic hit at a part centre returns well-formed events of this impl, `state()`
  * matches `describe()`, hit points never go negative, `update(0.016)` returns an array and every event is JSON-serializable. It hits the impl
- * (and calls `reset()` afterwards when there is one).
+ * (and calls `reset()` afterwards when there is one). With `options.cost` it also times `state()` and `describe()` (the cost contract of D8).
  */
 declare const checkDestructible: (impl: DestructibleImpl, options?: CheckOptions) => {
     ok: boolean;
@@ -1680,6 +1762,11 @@ interface AnimationEventSpec {
     /** snake_case type the host maps (`sound`, `eject_casing`, `door_latch`...). */
     type: string;
     data?: Record<string, unknown>;
+    /**
+     * Seconds of real time the event fires before `t`, not stretched with the clip: a recorded sound whose hit comes that long after its start
+     * (the click of a magazine seating) starts early so the hit lands on `t`. The player passes the lead it could apply as `data.lead`.
+     */
+    lead?: number;
 }
 /** A use animation a module brings with its item. Poses between keys are interpolated by the player (the test room does it linearly). */
 interface AnimationClipSpec {
@@ -1715,6 +1802,12 @@ interface SoundRequest {
     readonly params?: Readonly<Record<string, number>>;
     /** Seed for the sound's own random stream: same seed, same sound. */
     readonly seed?: number;
+    /** Seconds from now (the hit of a blow after its swing); the host schedules it on the audio clock, not on a timer. */
+    readonly delay?: number;
+    /** Built now instead of waiting in the engine's deferred start queue: for a sound that has to land on the frame the player sees it (a blow's
+     * contact, a heel strike, a landing). The queue builds a voice on the next frame budget and drops it after its latency, which at a low frame
+     * rate is late or silent. Default false. */
+    readonly urgent?: boolean;
 }
 /** What `AudioSink.play` hands back; opaque to the module, given back to `stop`. */
 interface SoundHandle {
@@ -1785,6 +1878,143 @@ interface EnvironmentBus {
 /** A plain store that implements the bus; the test room and tests use it, a game may bring its own. */
 declare function createEnvironmentBus(initial?: Partial<EnvironmentState>): EnvironmentBus;
 
+/**
+ * The sounds of a body (footsteps, jumps, landings, blows, hurt), as ids every package agrees on: the rule that knows what the body did
+ * (`game-player`, a host's own player) names the sound, and the bank that knows how it sounds (`game-audio`'s `BODY_FOLEY_BANK`) answers it.
+ * A game swaps the sound of an id (a sample instead of the synthesis) without touching the rule.
+ */
+/** What the feet touch, by how it sounds (not by what it is made of: a wooden floor and a plywood board both sound `wood`). */
+declare const SURFACE_IDS: readonly ["concrete", "asphalt", "wood", "tile", "dirt", "grass", "gravel", "sand", "metal", "water", "glass", "carpet"];
+type SurfaceId = (typeof SURFACE_IDS)[number];
+/** The surface a body stands on when nobody says (the test room's floor is a concrete slab). */
+declare const DEFAULT_SURFACE: SurfaceId;
+/** How the feet move: a run hits harder and shorter; a crouched step is the walk, quieter. */
+declare const GAIT_IDS: readonly ["walk", "run"];
+type GaitId = (typeof GAIT_IDS)[number];
+/** How hard a landing is: `light` for a jump on the spot or a step down (up to about 5 m/s), `heavy` for a drop of more than a metre and a half. */
+declare const LANDING_IDS: readonly ["light", "heavy"];
+type LandingId = (typeof LANDING_IDS)[number];
+/** The fall speed (m/s) from which a landing is `heavy`. */
+declare const HEAVY_LANDING_SPEED = 5.5;
+type FootstepSoundId = `footstep_${SurfaceId}_${GaitId}`;
+type LandSoundId = `land_${SurfaceId}_${LandingId}`;
+/**
+ * How a blow is struck, by the body part or the tool that does it. `blade` stabs or slashes, `blunt` is a club, a bat, a pipe or a hammer, `chop` an
+ * axe or a machete driven down.
+ */
+declare const BLOW_IDS: readonly ["punch", "kick", "shove", "blade", "blunt", "chop"];
+type BlowId = (typeof BLOW_IDS)[number];
+/** What the blow meets: a body (flesh and bone, the head apart), something else (the material answers with its own impact), or nothing. */
+type BlowTarget = 'body' | 'head' | 'object' | 'air';
+/** The sounds of the body that are not a footstep or a landing. */
+declare const BODY_SOUND_IDS: readonly ["jump", "cloth_rustle", "body_fall", "fall_damage", "player_hurt", "player_breath_run", "player_death", "bite", "grab", "punch_swing", "punch_hit_body", "punch_hit_face", "punch_hit_object", "kick_swing", "kick_hit", "kick_hit_object", "shove_two_hands", "knife_swing", "knife_stab", "knife_slash", "knife_hit_object", "blunt_swing", "blunt_hit", "blunt_hit_object", "axe_swing", "axe_chop", "axe_hit_object"];
+type BodySoundId = (typeof BODY_SOUND_IDS)[number];
+/** Every sound of a body: what a host plays for the player, a survivor or a zombie. */
+type BodyFoleyId = FootstepSoundId | LandSoundId | BodySoundId;
+declare const footstepSoundId: (surface: SurfaceId, gait: GaitId) => FootstepSoundId;
+declare const landSoundId: (surface: SurfaceId, fallSpeed: number) => LandSoundId;
+/** Every footstep and landing id, in the order of the surfaces. */
+declare const FOOTSTEP_SOUND_IDS: readonly FootstepSoundId[];
+declare const LAND_SOUND_IDS: readonly LandSoundId[];
+declare const BODY_FOLEY_IDS: readonly BodyFoleyId[];
+/**
+ * Seconds from the start of a swing's sound to its loudest point (the limb or the tool at full speed, just before the contact). A host that knows when the
+ * blow lands starts the swing this long before; one that does not plays the swing now and the hit this long after.
+ */
+declare const SWING_LEAD_SECONDS: Readonly<Record<BlowId, number>>;
+/** The swing through the air, played as the blow starts (`null`: the blow has none). */
+declare const swingSoundId: (blow: BlowId) => BodySoundId | null;
+/**
+ * The body's side of a blow that lands: the knuckles, the shoe, the blade or the club meeting what it hit. On an object the material's own impact
+ * plays too (the wood, the metal); this is the part that says it was a punch and not a shot.
+ */
+declare const hitSoundId: (blow: BlowId, target: Exclude<BlowTarget, "air">) => BodySoundId;
+/**
+ * The surface a material sounds like underfoot, by the material ids of `game-destruction` and `game-terrain` (unknown ids: `fallback`). Data, so
+ * a game with its own materials passes its own table to `surfaceOfMaterial`.
+ */
+declare const MATERIAL_SURFACES: Readonly<Record<string, SurfaceId>>;
+declare const isSurfaceId: (value: unknown) => value is SurfaceId;
+/** The surface of a material id; a surface id passes through. */
+declare function surfaceOfMaterial(material: string | undefined, table?: Readonly<Record<string, SurfaceId>>, fallback?: SurfaceId): SurfaceId;
+
+declare const FRAME_PHASES: readonly ["input", "fixedSimulate", "lateSimulate", "present", "render", "idle"];
+type FramePhase = (typeof FRAME_PHASES)[number];
+/**
+ * Presentation work a system leaves for later frames, run in small units within a shared time budget.
+ * Never simulation: nothing that consumes a seeded generator or decides an outcome may wait in a queue.
+ */
+interface DeferredQueue {
+    /** Stable name for stats and logs (see `DEFERRED_QUEUE_ID`). */
+    readonly id: string;
+    /**
+     * Units waiting. 0 means idle; the budget skips the queue without calling `run`. `frame` is the budget's frame counter: a queue may
+     * report 0 for the rest of a frame (the crease queue does in the frame a panel was torn). Same value for repeated calls in one frame.
+     */
+    pending(frame?: number): number;
+    /**
+     * Runs units in order until `clock() >= deadline`. Contract: when `pending() > 0` it runs **at least one** unit, even with a deadline
+     * already past; it never runs a unit after it saw the deadline pass. Returns how many units it ran.
+     */
+    run(deadline: number, clock: () => number): number;
+    /** Runs everything now (synchronous step, clear, dispose). */
+    flush(): void;
+    /**
+     * Called by `budget.register`: from now on the owner stops draining on its own (no MessageChannel, no drain inside `update`).
+     * Never called by a getter; a queue nobody registered keeps today's internal draining.
+     */
+    attach?(): void;
+    /** Called by the unregister function and by `budget.dispose`: the owner goes back to its internal draining. */
+    detach?(): void;
+}
+/** Where a module registers a deferred queue with the host's budget. */
+interface DeferredQueueOptions {
+    /** Higher runs first. See DEFERRED_PRIORITY. */
+    readonly priority: number;
+    /** `present` runs before the render (the work must show this frame); `idle` runs after it. Default `idle`. */
+    readonly phase?: 'present' | 'idle';
+    /** Starvation guard: the queue runs at least one unit every this many frames, even with the budget spent. Default 4. */
+    readonly minEveryFrames?: number;
+    /** Milliseconds of every frame kept for this queue before the others share the rest (when it has work). Default 0. */
+    readonly reserveMs?: number;
+}
+/** The ids of the kit's queues: what `DeferredQueue.id` says and what `DEFERRED_PRIORITY` is keyed by. */
+declare const DEFERRED_QUEUE_ID: {
+    readonly DESTRUCTION_EVENTS: "destruction.events";
+    readonly BREACH_PAINT: "floorplan.breach-paint";
+    readonly AUDIO_VOICES: "audio.voices";
+    readonly VEHICLE_CREASE: "vehicles.crease";
+};
+/** Default priorities and reserves of the kit's queues; a host may override any of them. */
+declare const DEFERRED_PRIORITY: {
+    readonly "destruction.events": {
+        readonly priority: 300;
+        readonly phase: "present";
+    };
+    readonly "floorplan.breach-paint": {
+        readonly priority: 250;
+        readonly phase: "present";
+    };
+    readonly "audio.voices": {
+        readonly priority: 200;
+        readonly phase: "idle";
+        readonly reserveMs: 1;
+    };
+    readonly "vehicles.crease": {
+        readonly priority: 100;
+        readonly phase: "idle";
+    };
+};
+interface DeferredQueueReport {
+    readonly ok: boolean;
+    readonly problems: readonly string[];
+}
+/**
+ * Checks the `DeferredQueue` contract. `fill` leaves the queue with at least two units waiting (the same call is made on a fresh queue).
+ * It cannot prove the queue only carries presentation work: that is a rule of review.
+ */
+declare function checkDeferredQueue(queue: DeferredQueue, fill: () => void): DeferredQueueReport;
+
 /** An item that holds a liquid (a cup, a bottle, a fuel tank). `part` is the destruction part that is the container; a hole in it makes it leak. */
 interface ModuleItemFluid {
     container: ContainerSpec;
@@ -1833,6 +2063,20 @@ interface Thumbnail {
         wear?: 0 | 1 | 2;
     };
 }
+/**
+ * What an item sounds like when the hand works it, as names of sound sets the host knows (the kit's are `LEAF_FOLEY_SETS` and `PICKUP_CLASSES` of game-audio).
+ * Everything is optional: without it the host picks by the material of the part.
+ */
+interface ItemSounds {
+    /** How it sounds picked up: `metal`, `plastic`, `glass`, `paper`, `fabric`, `wood`, `food`. Default: by its heaviest material. */
+    handling?: string;
+    /** The sound set of each leaf worked by hand, by part id, `*` for every other leaf: `car_door`, `car_trunk`, `fridge`, `microwave`, `drawer`, `wood_door`, `metal_door`. */
+    leaves?: Readonly<Record<string, string>>;
+    /** The sound id of opening its seal (`can_open`, `bottle_open`). Default: a metal seal is a can, any other a screw cap. */
+    open?: string;
+    /** The sound id of each use while it is held (`drink`: `drink_gulp`, `eat`: `eat_chew`), played over and over while the use lasts. */
+    uses?: Readonly<Record<string, string>>;
+}
 /** One thing a module can put in the test room (or any viewer): a toy car, a chair, a pistol on a table. */
 interface TestableItem {
     /** snake_case id, unique inside the module. */
@@ -1861,6 +2105,8 @@ interface TestableItem {
     pushable?: boolean;
     /** Where a body sits or lies on it: the host can seat the player there. */
     seats?: readonly ItemSeat[];
+    /** What it sounds like in the hand (picked up, opened, used) and the sound set of its doors and lids. */
+    sounds?: ItemSounds;
     /** 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;
     /**
@@ -2048,6 +2294,17 @@ type HostEvent =
 /** The player crouched or stood up, or the camera mode changed; read the new state with `host.player()`. */
  | {
     type: 'player';
+}
+/**
+ * A foot of the player's body touched the ground, at the frame the body's walk puts it down (the host's avatar, or the host's own stride without one):
+ * `surface` is what is under it. A module that owns the footsteps (their sound and their noise) steps on this instead of its own timer.
+ */
+ | {
+    type: 'footfall';
+    foot: 'left' | 'right';
+    surface: SurfaceId;
+    gait: GaitId;
+    position: Vec3;
 };
 /** The tool in hand as the host sees it. */
 interface HostTool {
@@ -2140,6 +2397,40 @@ interface HostReach {
     /** The hand is on the handle. */
     onGrip?(): void;
 }
+interface FrameOptions {
+    /** Default `lateSimulate`, which is where every `onFrame` runs without options. */
+    readonly phase?: Exclude<FramePhase, 'render'>;
+    /** Lower runs first inside the phase; ties keep the order of registration. Default 0. */
+    readonly order?: number;
+}
+/**
+ * An extra view the host draws over its own, for a module that needs to see from somewhere else at the same time: a rear-view mirror, a side mirror, a reversing camera, a security
+ * monitor. The host renders the scene from `camera` into `rect` after the main view, every frame, until the returned function is called.
+ */
+interface ModuleView {
+    /** A three.js camera the module moves itself every frame. Its aspect is set by the host to the rect's. */
+    camera: unknown;
+    /** Where on the screen, as fractions of the canvas from its top-left corner (0..1). */
+    rect: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Draws it left-right flipped, as a mirror shows the world. */
+    mirror?: boolean;
+    /** Rounds the corners of the frame (a fraction of the shorter side, 0..0.5); 0 or absent is a plain rectangle. */
+    rounded?: number;
+    /** Short label the host may print on the frame. */
+    label?: string;
+    /** Renders it at this fraction of the canvas resolution (default 0.5): a mirror does not need full detail. */
+    resolution?: number;
+}
+interface HostGraphics {
+    hordeDetail(): 'auto' | number;
+    onChange(listener: () => void): () => void;
+    report(key: string, value: number): void;
+}
 /**
  * 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.
@@ -2151,13 +2442,17 @@ interface ModuleHost {
     locale: string;
     /** Height of whatever things rest on at (x, z): the floor, a table, a counter. */
     groundAt(x: number, z: number): number;
+    /** Material id of the floor at (x, z) (`concrete`, `soil`, `wood_hard`...): what a dropped case or a footstep lands on. Optional; undefined where the host does not know. */
+    surfaceAt?(x: number, z: number): string | undefined;
     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. */
-    onFrame(update: (dt: number) => void): () => void;
+    /** Run every simulated frame with the frame's seconds (in the given phase, `lateSimulate` by default). Returns the unsubscribe function. */
+    onFrame(update: (dt: number) => void, options?: FrameOptions): () => void;
+    /** Registers a deferred queue with the host's frame budget. Returns the function that takes it out. A host without a budget leaves it out. */
+    defer?(queue: DeferredQueue, options: DeferredQueueOptions): () => void;
     /**
      * Follow the host clearing its area (`clear()`, opening an area, running scenarios): everything the module put in the world on its own (not as items) is to be taken away or put back. Returns the
      * unsubscribe function. A host that never clears leaves it out.
@@ -2170,6 +2465,12 @@ interface ModuleHost {
     onReset?(listener: () => void): () => 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;
+    /**
+     * The player's graphics settings, for what a module draws on its own (a horde): `hordeDetail` is `auto` (the module's renderer adapts by itself) or the share of
+     * its level-of-detail budget the player fixed, 0.1 to 1. `onChange` tells when it changes; `report` says what an adapting renderer draws now, so the settings
+     * screen can show it (`hordeDetail`: the share in use). A host without graphics settings leaves it out.
+     */
+    graphics?: HostGraphics;
     /**
      * 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).
@@ -2212,6 +2513,15 @@ interface ModuleHost {
     reachFor?(reach: HostReach): void;
     /** Asks the tool in hand to do something (see `ToolCommand`). A host without accessories leaves it out. */
     command?(command: ToolCommand): ToolCommandResult;
+    /**
+     * Draws an extra view over the host's own (mirrors, a reversing camera). Returns the function that takes it away. A host that cannot draw more than one view leaves it out.
+     */
+    addView?(view: ModuleView): () => void;
+    /**
+     * Takes over the main view with the module's camera (a vehicle's chase, cockpit or hood camera) until it is called again with null. The player's own camera comes back then. A host
+     * that keeps its camera to itself leaves it out.
+     */
+    setViewCamera?(camera: unknown | null): void;
     /** Lent only to a module that declares controls, layers or metrics. */
     bench?: ModuleBench;
     /** The host's shared sound engine; a module that makes sound uses it when lent and stays silent (or brings its own) when not. */
@@ -2220,11 +2530,23 @@ 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 most loose bodies a module may keep alive at once (ejected casings, dropped magazines), read at each spawn: the host's one budget. Absent when the host keeps no budget of its own. */
+    particleLimit?: () => number | undefined;
+    /** The host's light budget (`LightBudget` of `@adatechnology/game-render-three`; `unknown` here because the contracts do not depend on three.js): the one owner of point and spot lights. Read it with `isLightBudget`. Absent when the host has none. */
+    lights?: unknown;
+    /** The host's pools of geometries and materials (`RenderPools` of `@adatechnology/game-render-three`; `unknown` here because the contracts do not depend on three.js): what an effect asks for instead of making its own, so its shader programs stay linked. Read it with `isRenderPools`. Absent when the host has none. */
+    pools?: unknown;
     /**
      * 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 share (0..1) of a blast at `point` that reaches `target` through the cover between them (walls, cars, furniture of the host's world): what a module passes as
+     * `BlastSource.reach` to `blastShove`, so a body behind a wall is not thrown like one in the open. `ignore` lists world objects that never block (the explosive).
+     * Absent when the host has no world: the whole blast reaches.
+     */
+    blastReach?(point: Vec3, target: Vec3, ignore?: readonly string[]): number;
     /** 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;
 }
@@ -2339,6 +2661,12 @@ interface ToolClipPlayer {
         readonly clip: AnimationClipSpec;
     }>;
 }
+/**
+ * The clip with every event that has a `lead` moved that many seconds earlier, the lead it got in `data.lead`. A led event never goes before 0
+ * nor before the event written ahead of it (a fast clip keeps its order: the lead shrinks). Run after `scaleClip`: the lead is real time, the
+ * clip's stretch does not touch it.
+ */
+declare const leadClipEvents: (clip: AnimationClipSpec) => AnimationClipSpec;
 declare const createToolClipPlayer: (options: ToolClipPlayerOptions) => ToolClipPlayer;
 
 type Entry = {
@@ -2352,8 +2680,9 @@ type DeepPartial<TValue> = TValue extends (...args: never[]) => unknown ? TValue
 declare const deepMerge: <TBase extends object>(base: TBase, patch: object | undefined) => TBase;
 /** The shipped entries with the ones from `extra` added or, when the id exists, replaced. */
 declare const mergeById: <TEntry extends Entry>(shipped: readonly TEntry[], extra: readonly TEntry[] | undefined) => Map<string, TEntry>;
-/** Applies `patch` by id; a patch for an id that does not exist is ignored. */
+/** Applies `patch` by id; a patch for an id that does not exist is ignored (and warned about once, in development). */
 declare const applyPatches: <TEntry extends Entry>(entries: Map<string, TEntry>, patches: Readonly<Record<string, DeepPartial<TEntry> | Partial<TEntry>>> | undefined) => void;
+/** Takes the ids out; an id that does not exist is ignored (and warned about once, in development). */
 declare const removeIds: (entries: Map<string, unknown>, ids: readonly string[] | undefined) => void;
 
 /** One category (kind) of items. Defaults and required contracts are inherited from the `extends` chain. */
@@ -2470,4 +2799,12 @@ interface FootprintObject {
  */
 declare function footprintBlocker(object: FootprintObject | (() => FootprintObject | null | undefined), footprint: Footprint | (() => Footprint | null | undefined)): (x: number, z: number, radius: number) => boolean;
 
-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 Enclosure, type EnclosureBox, type EnvironmentBus, type EnvironmentKey, type EnvironmentState, type ExplosionChain, type FluidKind, type Footprint, type FootprintObject, type FractureStyle, type Fragment, type FragmentHitOptions, type FragmentMark, type GroundLayout, type GroundZone, type HandPose, type HandTargetSource, type HandTargets, type Hit, type HitIgnition, type HitResult, type Hole, type HostEvent, type HostReach, type HostTool, type HostToolAttachment, IMPACT_CONTRACT, type IgnitionRules, type ImpactContract, type ItemAnimationContract, type ItemSeat, 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 ModuleItemSeal, 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 SealBlock, type SealSpec, type SealState, type SegmentKind, type ShelterOptions, type Shot, type SoilLayer, type SoilProfile, type SoilState, type SoundHandle, type SoundRequest, type SpecReport, type StructureRole, type SurfaceLayer, TOOL_CLIP, TWIST_LIFT, 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 TwistOptions, type TwistStroke, 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, footprintBlocker, ignitionChance, kitOriginOf, markKitOrigin, mergeById, removeIds, resolveEntry, resolveIgnitionRules, sampleClip, scaleClip, sealBlock, sealOpener, shotExtras, shotToHit, sparkTargetFactor, toolAnimationStep, twistStroke, unmarkedDrawings, useToHit };
+/**
+ * @adatechnology/game-contracts: the contracts every game module (vehicles, furniture, plants, houses, weapons) depends on, and nothing else.
+ * Types plus tiny pure checkers, no runtime dependencies. The default destruction world, the renderers and the test room are optional.
+ */
+
+/** @deprecated Import it from `@adatechnology/game-contracts/testing`. */
+declare const resetWarnOnce: () => void;
+
+export { type ActionControl, type AnimationClipSpec, type AnimationEventSpec, type AnimationKey, type AnimationPose, type AreaPlacement, type AudioListener, type AudioSink, BLOW_IDS, BODY_FOLEY_IDS, BODY_SOUND_IDS, type BallisticExtras, type BenchChange, type BenchDeclaration, type BenchReport, type BenchSheet, type BlastOptions, type BlastReport, type BlastShove, type BlastShoveOptions, type BlastSource, type BlowId, type BlowTarget, type BodyFoleyId, type BodyRegion, type BodySlot, type BodySoundId, 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 CostOptions, type Crack, DEFAULT_BLAST_SHOVE, DEFAULT_ENVIRONMENT, DEFAULT_IGNITION_RULES, DEFAULT_SURFACE, DEFERRED_PRIORITY, DEFERRED_QUEUE_ID, type DamageStage, type DamageType, type DebrisKind, type DeepPartial, type DeferredQueue, type DeferredQueueOptions, type DeferredQueueReport, type Dent, type DestructibleImpl, type DestructibleSpec, type DestructionEvent, type DestructionEventType, type EffectHandle, type EffectRequest, type EffectSink, type Enclosure, type EnclosureBox, type EnvironmentBus, type EnvironmentKey, type EnvironmentState, type ExplosionChain, FOOTSTEP_SOUND_IDS, FRAME_PHASES, type FluidKind, type Footprint, type FootprintObject, type FootstepSoundId, type FractureStyle, type Fragment, type FragmentHitOptions, type FragmentMark, type FrameOptions, type FramePhase, GAIT_IDS, type GaitId, type GroundLayout, type GroundZone, HEAVY_LANDING_SPEED, type HandPose, type HandTargetSource, type HandTargets, type Hit, type HitIgnition, type HitResult, type Hole, type HostEvent, type HostGraphics, type HostReach, type HostTool, type HostToolAttachment, IMPACT_CONTRACT, type IgnitionRules, type ImpactContract, type ItemAnimationContract, type ItemSeat, type ItemSounds, type ItemUseDef, type JointKind, type JointSpec, type JointState, KIT_ORIGIN_KEY, KNOCKED_DOWN_ANGLE, KNOCK_CHEST, KNOCK_DOWN_SPEED, type KitOrigin, type Knock, LANDING_IDS, LAND_SOUND_IDS, type LandSoundId, type LandingId, type LiquidId, type LoopHandle, MATERIAL_SURFACES, MISSING_BITS, type MaterialId, type ModuleArea, type ModuleBench, type ModuleControl, type ModuleHost, type ModuleItemFluid, type ModuleItemSeal, type ModuleLayer, type ModuleMetric, type ModuleScenario, type ModuleView, 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, SURFACE_IDS, SWING_LEAD_SECONDS, type SealBlock, type SealSpec, type SealState, type SegmentKind, type ShelterOptions, type Shot, type SoilLayer, type SoilProfile, type SoilState, type SoundHandle, type SoundRequest, type SpecReport, type StructureRole, type SurfaceId, type SurfaceLayer, type SurfaceRay, type SurfaceRayHit, TOOL_CLIP, TWIST_LIFT, 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 TwistOptions, type TwistStroke, type UnmarkedDrawing, type Use, type Vec3, type WarmUpProbes, type WindExposure, type WindState, applyPatches, blastShove, bodyMass, checkAnimation, checkBench, checkCategorized, checkDeferredQueue, checkDestructible, checkHit, checkSpec, checkToolClips, createEnvironmentBus, createToolClipPlayer, deepMerge, defineCategories, fillFactor, footprintBlocker, footstepSoundId, hitSoundId, ignitionChance, isSurfaceId, kitOriginOf, knockOf, landSoundId, leadClipEvents, markKitOrigin, mergeById, removeIds, resetWarnOnce, resolveEntry, resolveIgnitionRules, sampleClip, scaleClip, sealBlock, sealOpener, shotExtras, shotToHit, sparkTargetFactor, stepKnock, surfaceOfMaterial, swingSoundId, toolAnimationStep, twistStroke, unmarkedDrawings, useToHit };