@adatechnology/game-contracts 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,702 @@
+/**
+ * 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.
+ *
+ * Units: metres, kilograms, seconds, joules, degrees Celsius.
+ */
+type Vec3 = [number, number, number];
+/** Quaternion `[x, y, z, w]`. */
+type Quat = [number, number, number, number];
+/** snake_case material id, e.g. `steel`, `wood_soft`, `glass`, `concrete`. Part of the saved data contract. */
+type MaterialId = string;
+/** How a part comes apart when it fails. */
+type FractureStyle = 
+/** glass, ceramic: sharp flat shards radiating from the impact */
+'shatter'
+/** concrete, brick, plaster: many small chunks plus dust */
+ | 'crumble'
+/** wood: long splinters along the grain (`grain` axis of the part) */
+ | 'splinter'
+/** fabric, leather, foliage, paper: torn into flat scraps */
+ | 'tear'
+/** plastic, hard wood boards: a few large pieces */
+ | 'snap'
+/** metal: never fractures; it dents, bends, gets holes and melts */
+ | 'none';
+/** Debris the renderer should emit for an event. */
+type DebrisKind = 'sparks' | 'splinters' | 'dust' | 'shards' | 'fibers' | 'leaves' | 'drips' | 'ash' | 'chips' | 'smoke' | 'steam';
+type PartShape = {
+    kind: 'box';
+    size: Vec3;
+} | {
+    kind: 'cylinder';
+    radius: number;
+    height: number;
+} | {
+    kind: 'sphere';
+    radius: number;
+};
+type FluidKind = 'water' | 'fuel' | 'oil' | 'gas' | 'sap' | 'acid' | 'blood' | string;
+interface PartSpec {
+    /** Unique inside the object. */
+    id: string;
+    material: MaterialId;
+    /** Shape in object-local space, centred on `position`. Cylinders are along local +Y. */
+    shape: PartShape;
+    position: Vec3;
+    /** Euler angles in radians, order XYZ (default none). */
+    rotation?: Vec3;
+    /** Mass in kg (default density × volume × `fill`). */
+    mass?: number;
+    /** Solid fraction of the shape, 0..1 (default 1). A hollow sheet-metal box is ~0.03, a drawer 0.1. */
+    fill?: number;
+    /** Wall thickness in metres for penetration (default: smallest dimension of the shape × `fill`, at most the smallest dimension). */
+    thickness?: number;
+    /** Hit points override (default mass × material.hpPerKg). */
+    hp?: number;
+    /** Axis of the grain for `splinter` materials, in local space (default the longest axis). */
+    grain?: 'x' | 'y' | 'z';
+    /** Fluid inside the part; punctures make it leak (a `leak` event per hole, the level drops in `update`). */
+    contains?: {
+        fluid: FluidKind;
+        liters: number;
+        pressurized?: boolean;
+    };
+    /** The part explodes when destroyed, or when its temperature passes `atC` (gas bottle, fuel tank, aerosol). */
+    explodes?: {
+        energy: number;
+        radius: number;
+        atC?: number;
+    };
+    /** Fixed to the world (a wall-mounted cabinet, a tree trunk in the ground). Groups that keep an anchored part stay in place. */
+    anchored?: boolean;
+    /** Free tags the host can use (`door`, `wheel`, `screen`, `trunk`, `leaf`...). */
+    tags?: string[];
+    /**
+     * Structural role. Structural parts (any role but `none`) carry their own mass plus the load of the parts resting on them down to the anchored
+     * parts, over the joints that `bears`. `foundation` implies `anchored`. `none` (and parts without `structure`) never carry load: a window, a door
+     * or furniture is not part of the structure. Objects without any structural part behave as before.
+     */
+    structure?: {
+        role: StructureRole;
+        capacity?: number;
+    };
+}
+/**
+ * Role of a part in the structure of a building. `partition` is a non-load-bearing wall: it is supported by other parts and carries nothing, so
+ * breaking it never drops anything.
+ */
+type StructureRole = 'foundation' | 'column' | 'beam' | 'slab' | 'wall' | 'partition' | 'roof' | 'stair' | 'none';
+/** How two parts are attached. Decides the default strength and the tool that undoes it. */
+type JointKind = 'screw' | 'bolt' | 'nail' | 'weld' | 'glue' | 'hinge' | 'clip' | 'tie' | 'mortar' | 'fused' | 'stem' | 'rebar' | 'resting';
+/** A tool that can undo joints (`hand` means no tool). */
+type ToolKind = 'hand' | 'screwdriver' | 'wrench' | 'pry_bar' | 'saw' | 'cutting_torch' | 'knife' | 'hammer';
+interface JointSpec {
+    /** Unique inside the object (default `${a}~${b}`). */
+    id?: string;
+    a: string;
+    b: string;
+    kind: JointKind;
+    /** Joint hit points (default from `JOINT_DEFAULTS[kind].strength`). Impulses and hits next to the joint wear it down. */
+    strength?: number;
+    /** Tools that undo it (default from `JOINT_DEFAULTS[kind].tools`). An empty list means it can only be broken. */
+    tools?: ToolKind[];
+    /** Seconds of tool work to undo it (default from `JOINT_DEFAULTS[kind].seconds`). */
+    seconds?: number;
+    /**
+     * The joint transfers load (default true when both parts have a structure role other than `none`, false otherwise). `'a_on_b'` means part `a`
+     * rests on part `b` (load flows from `a` to `b` only), `'b_on_a'` the opposite. With `true` the load is shared with the neighbours closer to an
+     * anchored part. A part that loses every support path to an anchored part collapses, even if it is still connected sideways to other parts.
+     */
+    bears?: boolean | 'a_on_b' | 'b_on_a';
+}
+interface DestructibleSpec {
+    /** Display name (free text; translated by the host). */
+    name?: string;
+    parts: PartSpec[];
+    /**
+     * Joints. When omitted, `inferJoints` is used: touching parts are joined with the kind that fits their materials
+     * (see `JOINT_BY_MATERIALS`).
+     */
+    joints?: JointSpec[];
+    /** Free tags (`furniture`, `vehicle`, `plant`, `structure`, `weapon`, `item`...). */
+    tags?: string[];
+}
+type DamageType = 
+/** bullets and pellets: `energy`, `caliber`; makes holes, dents, cracks, ricochets */
+'ballistic'
+/** hammers, falls, thrown objects, vehicle impacts: `energy`, `radius` of contact */
+ | 'blunt'
+/** axes, knives, machetes: `energy`; cuts and splinters, opens fabric */
+ | 'slash'
+/** blasts: `energy`, `radius`; damage and impulse fall off with distance, joints break, fragments fly */
+ | 'explosive'
+/** open flame (lighter, molotov, flamethrower): `temperature`, `radius`, `duration`; ignites */
+ | 'fire'
+/** heat without flame (cutting torch, hot plate): `temperature`, `radius`, `duration`; heats and melts */
+ | 'heat';
+interface Hit {
+    type: DamageType;
+    /** Point of the hit (world space unless `space: 'local'`). For `explosive` it is the centre of the blast. */
+    point: Vec3;
+    /** Direction the hit travels in (ballistic, blunt, slash). */
+    direction?: Vec3;
+    /** Kinetic or blast energy in joules. */
+    energy?: number;
+    /** Bullet diameter in millimetres (hole size). */
+    caliber?: number;
+    /** Radius of effect in metres (blast radius, flame radius, blunt contact radius). */
+    radius?: number;
+    /** Source temperature for `fire` and `heat`. */
+    temperature?: number;
+    /** Seconds the heat is applied for (a flamethrower calls `hit` every frame with `duration: dt`). */
+    duration?: number;
+    /** `world` (default) or `local` to the object. */
+    space?: 'world' | 'local';
+    /** Who caused it (passed through to events). */
+    source?: string;
+}
+type PartStatus = 'intact' | 'damaged'
+/** hp reached 0; the part fractured into fragments (it no longer exists as one piece) */
+ | 'broken'
+/** melted into a puddle */
+ | 'melted'
+/** burned to ash */
+ | 'ashes';
+/** A dent in local space of the part's object. */
+interface Dent {
+    point: Vec3;
+    normal: Vec3;
+    radius: number;
+    depth: number;
+}
+interface Hole {
+    point: Vec3;
+    normal: Vec3;
+    diameter: number;
+    /** The projectile went through. */
+    through: boolean;
+}
+interface Crack {
+    point: Vec3;
+    normal: Vec3;
+    /** Length of the longest crack line in metres. */
+    length: number;
+    /** Number of radial lines. */
+    rays: number;
+}
+interface PartState {
+    id: string;
+    material: MaterialId;
+    status: PartStatus;
+    hp: number;
+    maxHp: number;
+    /** Current mass (burning and melting reduce it). */
+    mass: number;
+    temperature: number;
+    burning: boolean;
+    /** Burnable mass left, kg. */
+    fuel: number;
+    /** 0..1, how charred the surface is. */
+    char: number;
+    /** 0..1, how much of the part has melted. */
+    melt: number;
+    dents: Dent[];
+    holes: Hole[];
+    cracks: Crack[];
+    /** Fluid left, when the part `contains` one. */
+    liters?: number;
+    /**
+     * Structural parts only. Load in kg: own mass plus what rests on the part. `stress` = `load / capacity`; above 1 the part takes damage every
+     * `update` (`(stress - 1) * maxHp * 0.5` per second), which can cascade. Capacity is `structure.capacity`, else `compressive * section` of the
+     * material, where the section is the product of the two smallest dimensions (columns, beams, roofs, stairs, foundations x10), thickness times longest dimension (slabs) or
+     * thickness times horizontal length (walls). Example: a 0.3 m concrete column carries 40 t, a 0.2 m brick wall 8 t per metre, a 0.1x0.2 m softwood beam 2 t.
+     */
+    load?: number;
+    stress?: number;
+    /** Index into `ObjectState.groups` of the piece this part belongs to (-1 when the part is broken, melted or ash). */
+    group: number;
+}
+interface JointState {
+    id: string;
+    a: string;
+    b: string;
+    kind: JointKind;
+    hp: number;
+    maxHp: number;
+    /** 0..1 of tool work done towards undoing it. */
+    progress: number;
+    /** Broken or undone. */
+    open: boolean;
+    /** How it opened. */
+    openedBy?: 'break' | 'tool' | 'part_lost';
+}
+interface ObjectState {
+    id: string;
+    name?: string;
+    position: Vec3;
+    rotation: Quat;
+    parts: PartState[];
+    joints: JointState[];
+    /**
+     * Pieces: connected components of remaining parts over closed joints. Index 0 is the piece that keeps the object's id (the one with an
+     * anchored part, else the heaviest). The others are loose pieces the renderer should make into separate bodies.
+     */
+    groups: string[][];
+    /** Every part is broken, melted or ash. */
+    destroyed: boolean;
+}
+/** A fragment for the renderer: an oriented box (or shard) with initial motion. Coordinates in world space. */
+interface Fragment {
+    id: string;
+    part: string;
+    material: MaterialId;
+    shape: 'chunk' | 'shard' | 'splinter' | 'scrap' | 'slab';
+    center: Vec3;
+    /** Full size of the fragment box. Shards are thin (`size[2]` is the thickness), splinters long along x. */
+    size: Vec3;
+    rotation: Quat;
+    velocity: Vec3;
+    angularVelocity: Vec3;
+    mass: number;
+}
+interface EventBase {
+    object: string;
+    /** Seconds since the world was created. */
+    time: number;
+    source?: string;
+}
+/** Points in events are in world space. */
+type DestructionEvent = (EventBase & {
+    type: 'damage';
+    part: string;
+    amount: number;
+    hp: number;
+    damageType: DamageType;
+}) | (EventBase & {
+    type: 'dent';
+    part: string;
+    dent: Dent;
+    worldPoint: Vec3;
+}) | (EventBase & {
+    type: 'hole';
+    part: string;
+    hole: Hole;
+    worldPoint: Vec3;
+    exitPoint?: Vec3;
+}) | (EventBase & {
+    type: 'crack';
+    part: string;
+    crack: Crack;
+    worldPoint: Vec3;
+}) | (EventBase & {
+    type: 'ricochet';
+    part: string;
+    point: Vec3;
+    direction: Vec3;
+    energy: number;
+}) | (EventBase & {
+    type: 'debris';
+    part: string;
+    kind: DebrisKind;
+    point: Vec3;
+    normal: Vec3;
+    count: number;
+    speed: number;
+}) | (EventBase & {
+    type: 'fracture';
+    part: string;
+    style: FractureStyle;
+    fragments: Fragment[];
+    point: Vec3;
+}) | (EventBase & {
+    type: 'detach';
+    joint: string;
+    parts: [string, string];
+    by: 'break' | 'tool' | 'part_lost';
+    groups: string[][];
+}) | (EventBase & {
+    type: 'disassemble_progress';
+    joint: string;
+    tool: ToolKind;
+    progress: number;
+}) | (EventBase & {
+    type: 'ignite';
+    part: string;
+    point: Vec3;
+}) | (EventBase & {
+    type: 'extinguish';
+    part: string;
+}) | (EventBase & {
+    type: 'burnout';
+    part: string;
+    point: Vec3;
+}) | (EventBase & {
+    type: 'melt';
+    part: string;
+    melt: number;
+}) | (EventBase & {
+    type: 'drip';
+    part: string;
+    point: Vec3;
+    material: MaterialId;
+}) | (EventBase & {
+    type: 'leak';
+    part: string;
+    fluid: FluidKind;
+    point: Vec3;
+    direction: Vec3;
+    rate: number;
+    pressurized: boolean;
+}) | (EventBase & {
+    type: 'explode';
+    part: string;
+    point: Vec3;
+    energy: number;
+    radius: number;
+})
+/** A structural part is overloaded (`stress` > 1); throttled to once per 0.5 s per part. Brittle parts also `crack` at stress > 0.8. */
+ | (EventBase & {
+    type: 'stress';
+    part: string;
+    stress: number;
+    load: number;
+})
+/** 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';
+    parts: string[];
+    mass: number;
+}) | (EventBase & {
+    type: 'destroyed';
+});
+type DestructionEventType = DestructionEvent['type'];
+/** What a single `hit` did. */
+interface HitResult {
+    object: string;
+    /** First part the hit landed on, if any. */
+    part?: string;
+    /** World point where it landed. */
+    point?: Vec3;
+    /** Damage dealt in total (all parts). */
+    damage: number;
+    /** Ballistic: the projectile came out the other side with `exitEnergy` left. */
+    penetrated: boolean;
+    exitEnergy: number;
+    events: DestructionEvent[];
+}
+interface RayHit {
+    object: string;
+    part: string;
+    point: Vec3;
+    normal: Vec3;
+    distance: 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,
+ * reset and `on` all route to it.
+ *
+ * Space: the impl receives hits in WORLD space and returns events in WORLD space (it owns its transform; the transform given to `register` or
+ * `setTransform` is only used by the world for raycasts and blast range). Every event must carry `object === id` and name parts listed by
+ * `describe()`.
+ */
+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. */
+    describe(): DestructibleSpec;
+    /** Apply one hit (see `IMPACT_CONTRACT` for the fields per type) and return the events it caused. */
+    hit(hit: Hit): DestructionEvent[];
+    /** Advance fire, melting, collapse and other timed behaviour. */
+    update?(dt: number): DestructionEvent[];
+    state(): ObjectState;
+    reset?(): 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;
+    /** Optional: an animation moved a part; `position` / `rotation` (Euler XYZ, radians) are object-local. Keep raycast and hit shapes in sync. */
+    setPartPose?(partId: string, position: Vec3, rotation?: Vec3): void;
+    /** Plain JSON of the impl's own state, stored in `DestructionSnapshot.impls`. */
+    serialize?(): unknown;
+    load?(data: unknown): void;
+}
+/** The fields a weapon or hazard must put in a `Hit`, per damage type. THE impact contract. */
+interface ImpactContract {
+    required: string[];
+    optional: string[];
+    note: string;
+}
+declare const IMPACT_CONTRACT: Record<DamageType, ImpactContract>;
+/** Problems with a hit according to the impact contract (empty when it is valid). */
+declare const checkHit: (hit: Hit) => string[];
+interface CheckOptions {
+    /**
+     * Ids of every material the impl may use (the contracts package does not know the materials of your world: pass the ids of
+     * `world.materials`, or the built-in plus your own). When omitted, the material check is skipped.
+     */
+    materials?: Iterable<string>;
+}
+/**
+ * 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).
+ */
+declare const checkDestructible: (impl: DestructibleImpl, options?: CheckOptions) => {
+    ok: boolean;
+    problems: string[];
+};
+
+interface CheckSpecOptions {
+    /** Known material ids. When given, every part's material must be one of them. */
+    materials?: Iterable<string>;
+}
+interface SpecReport {
+    /** False when there is at least one problem (warnings do not count). */
+    ok: boolean;
+    problems: string[];
+    /** Things that are legal but probably wrong, e.g. structural parts that cannot reach an anchored part. */
+    warnings: string[];
+}
+/**
+ * Static checks on a `DestructibleSpec` (no world needed), for items that give a `spec` instead of an `impl`: unique part ids, known materials
+ * (when `options.materials` is given), joints that reference existing, different parts, finite positive sizes, non-negative mass / hp / capacity,
+ * valid structure roles and `bears` directions. A structural part with no path of joints to an anchored part is a warning, not a problem: it
+ * is allowed, it just falls.
+ */
+declare const checkSpec: (spec: DestructibleSpec, options?: CheckSpecOptions) => SpecReport;
+
+/**
+ * A ballistic shot (one per pellet) as a weapon module produces it. Plain data: any damage model can consume it (`shotToHit` makes the `Hit`).
+ */
+interface Shot {
+    origin: Vec3;
+    /** Unit vector. */
+    direction: Vec3;
+    /** Muzzle energy in joules. */
+    energy: number;
+    /** Bullet diameter in millimetres. */
+    caliber: number;
+    /** snake_case calibre id, e.g. `9x19`. */
+    caliberId: string;
+    /** Muzzle speed in m/s. */
+    speed: number;
+    /** Energy at a distance in metres, with the calibre's drag. */
+    energyAt(distance: number): number;
+    pellet: number;
+    /** snake_case weapon id. */
+    weapon: string;
+    source?: string;
+}
+/** One use of a non-firearm (melee swing, flame tick, heat tick, throw, tool tick, extinguisher tick). */
+type Use = {
+    kind: 'melee';
+    damage: 'blunt' | 'slash';
+    energy: number;
+    radius: number;
+    reach: number;
+    origin: Vec3;
+    direction: Vec3;
+} | {
+    kind: 'flame';
+    temperature: number;
+    radius: number;
+    range: number;
+    cone: boolean;
+    duration: number;
+    origin: Vec3;
+    direction: Vec3;
+} | {
+    kind: 'heat';
+    temperature: number;
+    radius: number;
+    range: number;
+    duration: number;
+    origin: Vec3;
+    direction: Vec3;
+} | {
+    kind: 'throw';
+    energy: number;
+    radius: number;
+    fuse: number;
+    velocity: Vec3;
+    origin: Vec3;
+    fire?: {
+        temperature: number;
+        radius: number;
+        seconds: number;
+    };
+} | {
+    kind: 'tool';
+    tool: string;
+    reach: number;
+    duration: number;
+    origin: Vec3;
+    direction: Vec3;
+} | {
+    kind: 'extinguish';
+    range: number;
+    coolC: number;
+    duration: number;
+    origin: Vec3;
+    direction: Vec3;
+} | {
+    kind: 'hand';
+    reach: number;
+    origin: Vec3;
+    direction: Vec3;
+};
+/**
+ * The `Hit` a ballistic shot makes at `point` (world space): the energy is what is left of the shot at that distance from its origin
+ * (`shot.energyAt`), the direction and calibre come from the shot. `normal` (the surface normal at the point, when the caller knows it) does not
+ * 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;
+
+/**
+ * Fluid contract: what a module says about the liquid its item holds, and how the item is used. Types only: the liquids themselves, their
+ * simulation and their rendering live in `@adatechnology/game-fluids` (optional).
+ */
+/** snake_case liquid id: `water`, `coffee`, `milk`, `soda`, `beer`, `fuel`, `diesel`, `oil`, `blood`, `sap`, `acid`, `paint`... */
+type LiquidId = string;
+interface ContainerSpec {
+    /** Inner capacity in litres. */
+    capacity: number;
+    /** Liquid it starts with (default none). */
+    liquid?: LiquidId;
+    liters?: number;
+    temperature?: number;
+    /**
+     * Inner shape in the container's local space, used for the surface height and the spill point. Origin at the inner bottom centre, +Y up.
+     * `cylinder` (cups, cans, bottles approximated) or `box` (jerrycans, tanks, sinks).
+     */
+    shape: {
+        kind: 'cylinder';
+        radius: number;
+        height: number;
+    } | {
+        kind: 'box';
+        size: [number, number, number];
+    };
+    /** Opening at the top: radius in metres (a bottle neck is 0.012, a cup 0.04). Pour rate grows with it. 0 = closed (needs `open()`). */
+    opening: number;
+    /** Starts closed (bottle cap, jerrycan lid). */
+    closed?: boolean;
+    /** The container is insulated (thermos): cools 10× slower. */
+    insulated?: boolean;
+}
+/**
+ * A scripted use of a held item (drink a coffee, pour water, eat, wipe). Pure data with time-keyed poses so a test room or a game can play it
+ * and check what happened. The host maps poses to its hand/viewmodel animation.
+ */
+interface ItemUseDef {
+    /** snake_case: `drink`, `sip`, `pour`, `fill_from_tap`, `pour_out`, `eat`, `wipe`... */
+    id: string;
+    /** Seconds. */
+    duration: number;
+    /** Keyframes: time 0..duration, the hand-relative position/rotation (Euler XYZ) of the item and the container action during that key. */
+    keys: Array<{
+        t: number;
+        position: Vec3;
+        rotation: Vec3;
+        action?: 'drink' | 'pour' | 'open' | 'close' | 'none';
+        rate?: number;
+    }>;
+    /** Only valid when the container holds one of these (empty = any). */
+    liquids?: LiquidId[];
+}
+
+/** 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;
+    rotation?: Vec3;
+}
+interface AnimationKey {
+    /** Seconds from the start of the clip. */
+    t: number;
+    /** Pose of the item's root. */
+    position?: Vec3;
+    rotation?: Vec3;
+    /** Poses of named parts: the key is a destruction part id (a pistol `reload` moves `mag`; a car door `open` rotates `door_l`). */
+    parts?: Record<string, AnimationPose>;
+}
+interface AnimationEventSpec {
+    /** Seconds from the start of the clip. */
+    t: number;
+    /** snake_case type the host maps (`sound`, `eject_casing`, `door_latch`...). */
+    type: string;
+    data?: Record<string, unknown>;
+}
+/** 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 {
+    /** snake_case: `reload`, `open`, `drink`... Unique within the item. */
+    id: string;
+    /** Seconds. */
+    duration: number;
+    keys: AnimationKey[];
+    events?: AnimationEventSpec[];
+}
+/** What an item exposes when it brings its own animations. */
+interface ItemAnimationContract {
+    animations: AnimationClipSpec[];
+}
+/**
+ * Problems with a clip (empty when it is valid): a snake_case id, a positive finite duration, at least one key, key and event times inside
+ * `[0, duration]` and not going backwards, finite vectors, every named part one of `partIds`, event types that are non-empty strings and
+ * JSON-serializable event data.
+ */
+declare const checkAnimation: (clip: AnimationClipSpec, partIds: Iterable<string>) => {
+    ok: boolean;
+    problems: string[];
+};
+
+/** 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;
+    part?: string;
+    /** Item uses offered while held (`drink`, `pour`...). */
+    uses?: string[];
+    offset?: Vec3;
+}
+/** 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. */
+    id: string;
+    /** Display name, already translated for the locale passed to `TestableModule.items`. */
+    name: string;
+    /**
+     * Builds the 3D object: `THREE` is the host's three.js namespace, the result is its `Object3D` (origin at the centre of the footprint, on the
+     * floor, front facing +z). The contracts package does not depend on three.js, so both are `unknown` here; the host narrows them.
+     */
+    build: (THREE: unknown) => unknown;
+    /** Destruction spec for the default destruction world. A module that owns its destruction gives `impl` instead (or as well). */
+    spec?: DestructibleSpec | ((root: unknown) => DestructibleSpec);
+    /** The module's own destruction: parts, hits and state are its business. The world hosts it next to its own objects. `id` is the object id the host gives it: `DestructibleImpl.id` must be that id. */
+    impl?: (root: unknown, id: string) => DestructibleImpl;
+    fluid?: ModuleItemFluid;
+    /** The item is also a weapon the player can equip: an id of the arsenal in use. */
+    weapon?: string;
+    /** Use animations this item brings (a pistol `reload` moves `mag`; a car door `open` rotates `door_l`). */
+    animations?: AnimationClipSpec[];
+    /** Can be grabbed and thrown. */
+    movable?: boolean;
+}
+/** A scripted check a module brings: the host calls `run` with its own context (the test room passes a `ScenarioContext`). */
+interface ModuleScenario<Context = unknown> {
+    id: string;
+    name: string;
+    run(context: Context): void | Promise<void>;
+}
+/** What a module hands the test room: its items and, optionally, scenarios that exercise them. */
+interface TestableModule<Context = unknown> {
+    /** snake_case id of the module. */
+    id: string;
+    name: string;
+    /** Catalogue tab the items go under. */
+    group: string;
+    items(locale: string): TestableItem[];
+    scenarios?(locale: string): Array<ModuleScenario<Context>>;
+}
+
+export { type AnimationClipSpec, type AnimationEventSpec, type AnimationKey, type AnimationPose, type CheckOptions, type CheckSpecOptions, type ContainerSpec, type Crack, type DamageType, type DebrisKind, type Dent, type DestructibleImpl, type DestructibleSpec, type DestructionEvent, type DestructionEventType, type FluidKind, type FractureStyle, type Fragment, type Hit, type HitResult, type Hole, IMPACT_CONTRACT, type ImpactContract, type ItemAnimationContract, type ItemUseDef, type JointKind, type JointSpec, type JointState, type LiquidId, type MaterialId, type ModuleItemFluid, type ModuleScenario, type ObjectState, type PartShape, type PartSpec, type PartState, type PartStatus, type Quat, type RayHit, type Shot, type SpecReport, type StructureRole, type TestableItem, type TestableModule, type ToolKind, type Use, type Vec3, checkAnimation, checkDestructible, checkHit, checkSpec, shotToHit };