@adatechnology/game-contracts 0.7.0 → 0.9.0

package/README.md

@@ -107,6 +107,15 @@ A module can also declare a bench as data: `controls` (number, boolean, choice,
 `ModuleBench` in `attach` (`host.bench`): `value(id)`, `layer(id)`, `onChange(listener)` (right after `attach` it gets one change per control and
 layer, in order), `patch(id, { hidden, disabled, options, value })` (no echo) and `look(eye, target)`. `checkBench({ controls, layers, metrics })`
 checks the declaration (snake_case ids unique across the three, `min < max`, `step > 0`, defaults in range and among the options, `max > 0`).
+A choice's options may carry a `group` (the host lists them under that heading; the options of a group sit next to each other, and `checkBench` says
+so when they do not). `ModuleBench.sheet(sheet)` puts a card on the host's panel (`BenchSheet`: kicker, title, body, facts, steps, colour swatches, note and a
+timeline of segments whose playhead follows a module metric); a host with no sheet area leaves it out.
+
+### Effects the host lends
+
+`ModuleHost.effects` is an `EffectSink`: `play({ effect, point, direction?, normal?, seed?, param?, scale? })` starts an effect of the host's catalogue by id
+and answers a handle (or `null` when the host does not know it), `stop(handle)` ends a looping one, and `configure`, `stats` and `catalog` are optional. The
+`explosion` host event carries `explosive` (the id of the explosive), `PartSpec.explodes.effect` and the `explode` event name the effect of a part's blast.
 
 ```ts
 controls: () => [

package/dist/index.d.ts

@@ -83,6 +83,8 @@ interface PartSpec {
          * Each part goes off once. Without `chain`, it explodes only when destroyed (or at `atC`).
          */
         chain?: ExplosionChain;
+        /** Id of the effect the host plays for the blast (`explosion_fuel_barrel`); without it the host picks a generic one by `energy` and `radius`. */
+        effect?: string;
     };
     /** 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;
@@ -97,7 +99,54 @@ interface PartSpec {
         role: StructureRole;
         capacity?: number;
     };
+    /**
+     * 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
+     * `material.penetration x thickness` to what a bullet must get through, and a hit spalls the outer coat at the impact (`spall` event) before it
+     * reaches the core.
+     */
+    layers?: readonly SurfaceLayer[];
+    /** Steel inside a concrete part: when the part reaches 0 hp the concrete crumbles but the cage stays (`expose`, `PartState.stripped`). */
+    reinforcement?: Reinforcement;
+    /** Masonry made of units (bricks, blocks, panels): fragments of a breach or a fracture are the size of one unit, laid in `bond`. */
+    units?: PartUnits;
+    /**
+     * Opts the part into damage stages (`PartState.stage`, `stage` events). Through damage (through holes, blunt and explosive damage) within
+     * `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;
+}
+/** 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 {
+    material: MaterialId;
+    /** Metres. */
+    thickness: number;
+    faces: 'both' | '+' | '-';
+}
+/** Rebar of a concrete part. Plates get two perpendicular grids at mid thickness, long members (columns, beams) bars along their length. */
+interface Reinforcement {
+    material: MaterialId;
+    /** Metres between bars (0.18). */
+    spacing: number;
+    /** Bar diameter in metres (0.007 to 0.010). */
+    diameter: number;
+    /** Fraction of the part's structural capacity the bare cage keeps (default 0.15). */
+    residualCapacity?: 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;
+    bond: 'running' | 'stack';
+    mortar: MaterialId;
+}
+interface PartBreach {
+    /** Square metres of through damage inside the breach radius that open the part (default 0.25). */
+    area?: number;
 }
+/**
+ * Damage stage of a part with `breach`/`layers`/`units`/`reinforcement`: 0 intact, 1 marked (first hole or crack), 2 breached (an opening you can
+ * pass through), 3 gone (fractured or collapsed).
+ */
+type DamageStage = 0 | 1 | 2 | 3;
 /**
  * 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.
@@ -174,6 +223,12 @@ interface Hit {
     space?: 'world' | 'local';
     /** 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. */
+    mass?: number;
+    /** 0..1, how much of the blow is an edge that cuts through (slash 0.85, blunt 0, explosive 1; a bullet carries its own). */
+    cut?: number;
+    /** A part the caller already resolved, by id (a crowd raycast against capsules); the impl then skips its own part search. */
+    part?: string;
 }
 type PartStatus = 'intact' | 'damaged'
 /** the part lost its support path to the ground and fell with its group (reported by a `collapse` event); it still exists as a piece */
@@ -235,6 +290,15 @@ interface PartState {
      */
     load?: number;
     stress?: number;
+    /** Damage stage; only present on parts that opted in (see `PartSpec.breach`). */
+    stage?: DamageStage;
+    /** 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. */
+    opening?: {
+        center: Vec3;
+        radius: number;
+    };
     /** Index into `ObjectState.groups` of the piece this part belongs to (-1 when the part is broken, melted or ash). */
     group: number;
 }
@@ -266,6 +330,14 @@ interface ObjectState {
     groups: string[][];
     /** Every part is broken, melted or ash. */
     destroyed: boolean;
+    /** Only objects that are a living body (a character, an animal): the summary the crowd and the HUD read. */
+    body?: {
+        alive: boolean;
+        vitality: number;
+        missing: number;
+        limp: boolean;
+        crawl: boolean;
+    };
 }
 /** A fragment for the renderer: an oriented box (or shard) with initial motion. Coordinates in world space. */
 interface Fragment {
@@ -280,6 +352,14 @@ interface Fragment {
     velocity: Vec3;
     angularVelocity: Vec3;
     mass: number;
+    /** Holes the part had where this fragment came from, in the fragment's own axes: the renderer keeps them on the debris. */
+    marks?: readonly FragmentMark[];
+}
+interface FragmentMark {
+    /** Relative to the fragment's centre, in the fragment's axes. */
+    point: Vec3;
+    normal: Vec3;
+    diameter: number;
 }
 interface EventBase {
     object: string;
@@ -375,6 +455,7 @@ type DestructionEvent = (EventBase & {
     point: Vec3;
     energy: number;
     radius: 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`). */
  | (EventBase & {
@@ -396,6 +477,43 @@ type DestructionEvent = (EventBase & {
     type: 'collapse';
     parts: string[];
     mass: number;
+})
+/** The outer coat of a layered part came off at `point` (`layer` indexes `PartSpec.layers`; `area` in m²). */
+ | (EventBase & {
+    type: 'spall';
+    part: string;
+    layer: number;
+    point: Vec3;
+    area: number;
+})
+/**
+ * A staged part changed stage. At stage 2 `opening` is where the breach is and `fragments` the unit-sized pieces that came out (the part is not
+ * removed: draw the fragments and cut the opening, do not hide the part). Stage 3 follows a `fracture` or a `collapse`.
+ */
+ | (EventBase & {
+    type: 'stage';
+    part: string;
+    stage: DamageStage;
+    opening?: {
+        center: Vec3;
+        radius: number;
+    };
+    fragments?: readonly Fragment[];
+})
+/** Rebar of a reinforced part is bare: segments in world space. Empty `bars` means the cage is gone. */
+ | (EventBase & {
+    type: 'expose';
+    part: string;
+    bars: readonly [Vec3, Vec3][];
+})
+/** A living body changed: a wound, a broken or severed limb, a destroyed segment, a split torso, limp, crawl, stun or death. `below` lists the parts that fall with a severed one. */
+ | (EventBase & {
+    type: 'body';
+    part?: string;
+    change: 'wound' | 'broken' | 'severed' | 'destroyed' | 'split' | 'limp' | 'crawl' | 'stunned' | 'killed';
+    cause?: 'head' | 'vitality' | 'bleed' | 'explosion';
+    below?: string[];
+    exit?: Vec3;
 }) | (EventBase & {
     type: 'destroyed';
 });
@@ -477,6 +595,26 @@ declare const checkDestructible: (impl: DestructibleImpl, options?: CheckOptions
     problems: string[];
 };
 
+/** The slots of a body an item can cover (the item slot vocabulary: game-items imports it from here). */
+type BodySlot = 'head' | 'eyes' | 'torso' | 'arms' | 'hands' | 'legs' | 'feet' | 'over';
+/** The 11 segments of the detailed body model (the Arsenal ids). */
+type SegmentKind = 'head' | 'jaw' | 'neck' | 'torso' | 'pelvis' | 'upperArm' | 'forearm' | 'hand' | 'thigh' | 'shin' | 'foot';
+/** The 6 regions of the crowd model (the game regions 0..5). */
+type BodyRegion = 'head' | 'torso' | 'armL' | 'armR' | 'legL' | 'legR';
+/** Bits of the `missing` mask of a body. The instanced body shader reads them, so the values are part of the contract. */
+declare const MISSING_BITS: {
+    readonly head: 1;
+    readonly armL: 2;
+    readonly armR: 4;
+    readonly legL: 8;
+    readonly legR: 16;
+    readonly armLBroken: 32;
+    readonly armRBroken: 64;
+    readonly legLBroken: 128;
+    readonly legRBroken: 256;
+    readonly jaw: 512;
+};
+
 interface CheckSpecOptions {
     /** Known material ids. When given, every part's material must be one of them. */
     materials?: Iterable<string>;
@@ -511,6 +649,8 @@ interface Shot {
     caliberId: string;
     /** Muzzle speed in m/s. */
     speed: number;
+    /** Projectile mass in grams (one pellet for a shotgun load). */
+    mass?: number;
     /** Energy at a distance in metres, with the calibre's drag. */
     energyAt(distance: number): number;
     pellet: number;
@@ -683,50 +823,6 @@ interface ItemUseDef {
     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[];
-};
-
 /**
  * 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.
@@ -735,6 +831,8 @@ type ControlValue = number | boolean | string;
 interface ChoiceOption {
     readonly id: string;
     readonly name: string;
+    /** Heading the host lists the option under (`optgroup`, a grouped row of buttons). Options of a group must sit next to each other. */
+    readonly group?: string;
 }
 interface ControlBase {
     /** snake_case, unique across the module's controls, layers and metrics. */
@@ -811,6 +909,41 @@ interface ModuleBench {
     patch(id: string, patch: ControlPatch): void;
     /** Move the host camera (a near / middle / far choice). */
     look(eye: Vec3, target: Vec3): void;
+    /** Shows a sheet on the host's panel, or takes it down with `null`. A host without a sheet area ignores it. */
+    sheet?(sheet: BenchSheet | null): void;
+}
+/**
+ * A card of text the module puts on the host's panel (the sheet of an effect, of a weapon): what it is, its numbers, its steps, its colours and,
+ * optionally, a strip of segments over time. Names and texts are already translated for the host's locale.
+ */
+interface BenchSheet {
+    readonly kicker?: string;
+    readonly title: string;
+    readonly body?: string;
+    readonly facts?: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+    readonly steps?: readonly {
+        readonly at: string;
+        readonly text: string;
+    }[];
+    readonly swatches?: readonly {
+        readonly color: string;
+        readonly name: string;
+    }[];
+    readonly note?: string;
+    /** A strip of named segments (seconds), with tick marks and a playhead that follows the module metric `metric`. */
+    readonly timeline?: {
+        readonly segments: readonly {
+            readonly name: string;
+            readonly start: number;
+            readonly end: number;
+            readonly color: string;
+        }[];
+        readonly ticks: readonly number[];
+        readonly metric: string;
+    };
 }
 interface BenchReport {
     readonly ok: boolean;
@@ -821,9 +954,88 @@ interface BenchDeclaration {
     readonly layers?: readonly ModuleLayer[];
     readonly metrics?: readonly ModuleMetric[];
 }
-/** snake_case ids unique across controls, layers and metrics; min < max; step > 0; default in range; options non-empty, unique, default among them; metric max > 0. */
+/** snake_case ids unique across controls, layers and metrics; min < max; step > 0; default in range; options non-empty, unique, default among them, each group in one run; metric max > 0. */
 declare function checkBench(declared: BenchDeclaration): BenchReport;
 
+/** What a module asks the host to show: an effect by id (`explosion_m67`, `impact_concrete`, `muzzle_ak`), where, and how. */
+interface EffectRequest {
+    /** An id of the host's effect catalogue (`EffectSink.catalog`). A host that does not know it plays nothing. */
+    readonly effect: string;
+    readonly point: Vec3;
+    /** Where the effect is aimed (a cone, a jet). */
+    readonly direction?: Vec3;
+    /** The surface normal at `point` (an impact, a decal). */
+    readonly normal?: Vec3;
+    /** Makes the visual repeatable: the same seed draws the same effect, so a network event of a few bytes is enough on every client. */
+    readonly seed?: number;
+    /** The variation of the effect (an age, a material, a condition): an option index or an option id of the effect. */
+    readonly param?: number | string;
+    /** Multiplies the effect's size and amount. */
+    readonly scale?: number;
+}
+/** Identifies a running effect so it can be stopped. */
+type EffectHandle = number;
+/**
+ * What the host lends a module to show effects (smoke, sparks, blast, blood mist) without bringing its own particles. Nothing here is specific
+ * to a kind of effect or to a renderer.
+ */
+interface EffectSink {
+    /** Starts the effect; `null` when the host does not know it, the layer is off or the budget is spent. */
+    play(request: EffectRequest): EffectHandle | null;
+    /** Ends a looping effect now (a fire, a trail). A handle that already ended is ignored. */
+    stop(handle: EffectHandle): void;
+    /** Sets what the host lets a module tune (`quality`, `lod_band`...): the id of the setting and its value. A host applies the ids it knows. */
+    configure?(settings: Readonly<Record<string, ControlValue>>): void;
+    /** Counters of what is alive (`puffs`, `sparks`, `lights`...), for a bench. */
+    stats?(): Readonly<Record<string, number>>;
+    /** The ids `play` accepts. */
+    catalog?(): readonly string[];
+}
+
+/** 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;
@@ -832,6 +1044,16 @@ interface ModuleItemFluid {
     uses?: string[];
     offset?: Vec3;
 }
+/** A picture of an item for catalogues and inventories: a hand-made `svg`, or `render` to have the host draw the 3D model (camera angles in radians, `wear` 0 new, 1 worn, 2 ruined). */
+interface Thumbnail {
+    svg?: string;
+    render?: true | {
+        yaw?: number;
+        pitch?: number;
+        distance?: number;
+        wear?: 0 | 1 | 2;
+    };
+}
 /** 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. */
@@ -912,6 +1134,12 @@ type HostEvent =
     rounds?: number;
     mode?: string;
     suppressed?: boolean;
+    /**
+     * Where the muzzle is in the world and where it points, for a shot the viewer sees from outside (another player, the third-person camera). A module
+     * then shows the shooter's flash and casing through `host.effects`. Absent for the player's own shot, which the weapon in the hands already draws.
+     */
+    origin?: Vec3;
+    direction?: Vec3;
 }
 /** The trigger was pulled, the round was spent and nothing left the tool (a dud cartridge): no projectile, no recoil. */
  | {
@@ -1006,7 +1234,10 @@ type HostEvent =
     on: boolean;
     duration?: number;
 }
-/** Something blew up: a thrown or launched explosive, a charge, or a part of the world (a fuel barrel); `source` is the weapon or the object, `cause` what set it off. */
+/**
+ * Something blew up: a thrown or launched explosive, a charge, or a part of the world (a fuel barrel); `source` is the weapon or the object, `cause` what set it off.
+ * `explosive` is the id of the explosive when there is one (`m67`, `c4`, `fuel_barrel`): the host picks the blast by it.
+ */
  | {
     type: 'explosion';
     source: string;
@@ -1014,6 +1245,7 @@ type HostEvent =
     energy: number;
     radius: number;
     cause: string;
+    explosive?: string;
 };
 /** The tool in hand as the host sees it. */
 interface HostTool {
@@ -1103,6 +1335,8 @@ interface ModuleHost {
     command?(command: ToolCommand): ToolCommandResult;
     /** Lent only to a module that declares controls, layers or metrics. */
     bench?: ModuleBench;
+    /** 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;
 }
 /** 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> {
@@ -1209,4 +1443,19 @@ interface ToolClipPlayer {
 }
 declare const createToolClipPlayer: (options: ToolClipPlayerOptions) => ToolClipPlayer;
 
-export { type ActionControl, type AnimationClipSpec, type AnimationEventSpec, type AnimationKey, type AnimationPose, type AreaPlacement, type BenchChange, type BenchDeclaration, type BenchReport, type BooleanControl, type ChainDelay, type CheckOptions, type CheckSpecOptions, type ChoiceControl, type ChoiceOption, type ContainerSpec, type ControlPatch, type ControlValue, type Crack, type DamageType, type DebrisKind, type Dent, type DestructibleImpl, type DestructibleSpec, type DestructionEvent, type DestructionEventType, type ExplosionChain, type FluidKind, type FractureStyle, type Fragment, 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 MaterialId, type ModuleArea, type ModuleBench, type ModuleControl, type ModuleHost, type ModuleItemFluid, type ModuleLayer, type ModuleMetric, type ModuleScenario, type NumberControl, type ObjectState, type PartShape, type PartSpec, type PartState, type PartStatus, type Quat, type RayHit, STAGE_EVENT, type Shot, type SpecReport, type StructureRole, TOOL_CLIP, type TestableItem, type TestableModule, type ToolAnimationStep, type ToolAnimator, type ToolClipId, type ToolClipPlayer, type ToolClipPlayerOptions, type ToolClipSet, type ToolCommand, type ToolCommandResult, type ToolKind, type ToolRig, type Use, type Vec3, checkAnimation, checkBench, checkDestructible, checkHit, checkSpec, checkToolClips, createToolClipPlayer, sampleClip, scaleClip, shotToHit, toolAnimationStep };
+type Entry = {
+    readonly id: string;
+};
+/** Recursively optional; arrays and functions are replaced as a whole, objects are merged. */
+type DeepPartial<TValue> = TValue extends (...args: never[]) => unknown ? TValue : TValue extends readonly unknown[] ? TValue : TValue extends object ? {
+    [TKey in keyof TValue]?: DeepPartial<TValue[TKey]>;
+} : TValue;
+/** Merges `patch` over `base`: plain objects merge field by field, arrays, functions and primitives replace. `undefined` in the patch is ignored. */
+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. */
+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 BenchChange, type BenchDeclaration, type BenchReport, type BenchSheet, type BodyRegion, type BodySlot, type BooleanControl, type ChainDelay, type CheckOptions, type CheckSpecOptions, type ChoiceControl, type ChoiceOption, type ContainerSpec, type ControlPatch, type ControlValue, type Crack, 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 ExplosionChain, type FluidKind, type FractureStyle, type Fragment, 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, 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 Shot, 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, createToolClipPlayer, deepMerge, mergeById, removeIds, sampleClip, scaleClip, shotToHit, toolAnimationStep };

package/dist/index.global.js

@@ -22,8 +22,10 @@ var GameContracts = (() => {
   var index_exports = {};
   __export(index_exports, {
     IMPACT_CONTRACT: () => IMPACT_CONTRACT,
+    MISSING_BITS: () => MISSING_BITS,
     STAGE_EVENT: () => STAGE_EVENT,
     TOOL_CLIP: () => TOOL_CLIP,
+    applyPatches: () => applyPatches,
     checkAnimation: () => checkAnimation,
     checkBench: () => checkBench,
     checkDestructible: () => checkDestructible,
@@ -31,6 +33,9 @@ var GameContracts = (() => {
     checkSpec: () => checkSpec,
     checkToolClips: () => checkToolClips,
     createToolClipPlayer: () => createToolClipPlayer,
+    deepMerge: () => deepMerge,
+    mergeById: () => mergeById,
+    removeIds: () => removeIds,
     sampleClip: () => sampleClip,
     scaleClip: () => scaleClip,
     shotToHit: () => shotToHit,
@@ -146,6 +151,20 @@ var GameContracts = (() => {
     return { ok: problems.length === 0, problems };
   };
 
+  // src/body.ts
+  var MISSING_BITS = {
+    head: 1,
+    armL: 2,
+    armR: 4,
+    legL: 8,
+    legR: 16,
+    armLBroken: 32,
+    armRBroken: 64,
+    legLBroken: 128,
+    legRBroken: 256,
+    jaw: 512
+  };
+
   // src/spec.ts
   var STRUCTURE_ROLES = ["foundation", "column", "beam", "slab", "wall", "partition", "roof", "stair", "none"];
   var BEARS = [true, false, "a_on_b", "b_on_a"];
@@ -153,6 +172,31 @@ var GameContracts = (() => {
   var positive = (n) => finite(n) && n > 0;
   var vec3 = (v) => Array.isArray(v) && v.length === 3 && v.every(finite);
   var nonNegative = (n) => n === void 0 || finite(n) && n >= 0;
+  var FACES = ["both", "+", "-"];
+  var BONDS = ["running", "stack"];
+  var checkStagedFields = (p, label, materials, problems) => {
+    const known = (m, what) => {
+      if (materials && !materials.has(m)) problems.push(`${label} ${what} has unknown material "${String(m)}"`);
+    };
+    (p?.layers ?? []).forEach((l, i) => {
+      known(l?.material, `layer ${i}`);
+      if (!positive(l?.thickness)) problems.push(`${label} layer ${i} thickness must be finite and positive`);
+      if (!FACES.includes(l?.faces)) problems.push(`${label} layer ${i} has an invalid faces "${String(l?.faces)}"`);
+    });
+    const r = p?.reinforcement;
+    if (r) {
+      known(r.material, "reinforcement");
+      if (!positive(r.spacing) || !positive(r.diameter)) problems.push(`${label} reinforcement spacing and diameter must be finite and positive`);
+      if (r.residualCapacity !== void 0 && !(finite(r.residualCapacity) && r.residualCapacity >= 0 && r.residualCapacity <= 1)) problems.push(`${label} reinforcement residualCapacity must be between 0 and 1`);
+    }
+    const u = p?.units;
+    if (u) {
+      known(u.mortar, "units mortar");
+      if (!vec3(u.size) || !u.size.every(positive)) problems.push(`${label} units size must be three finite positive numbers`);
+      if (!BONDS.includes(u.bond)) problems.push(`${label} units has an invalid bond "${String(u.bond)}"`);
+    }
+    if (p?.breach && p.breach.area !== void 0 && !positive(p.breach.area)) problems.push(`${label} breach area must be finite and positive`);
+  };
   var checkSpec = (spec, options = {}) => {
     const problems = [];
     const warnings = [];
@@ -185,6 +229,7 @@ var GameContracts = (() => {
         if (!nonNegative(p.structure.capacity)) problems.push(`${label} structure capacity must be a finite number >= 0`);
       }
       if (p?.contains && !nonNegative(p.contains.liters)) problems.push(`${label} contains.liters must be a finite number >= 0`);
+      checkStagedFields(p, label, materials, problems);
     }
     const jointIds = /* @__PURE__ */ new Set();
     const edges = [];
@@ -237,6 +282,7 @@ var GameContracts = (() => {
       direction: [shot.direction[0], shot.direction[1], shot.direction[2]],
       energy: shot.energyAt(distance),
       caliber: shot.caliber,
+      ...shot.mass === void 0 ? {} : { mass: shot.mass },
       source: shot.source ?? shot.weapon
     };
   };
@@ -459,6 +505,34 @@ var GameContracts = (() => {
     };
   };
 
+  // src/registry.ts
+  var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+  var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+  var deepMerge = (base, patch) => {
+    if (!patch) return base;
+    const result = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+      if (value === void 0 || UNSAFE_KEYS.has(key)) continue;
+      const current = result[key];
+      result[key] = isPlainObject(current) && isPlainObject(value) ? deepMerge(current, value) : value;
+    }
+    return result;
+  };
+  var mergeById = (shipped, extra) => {
+    const entries = /* @__PURE__ */ new Map();
+    for (const entry of [...shipped, ...extra ?? []]) entries.set(entry.id, entry);
+    return entries;
+  };
+  var applyPatches = (entries, patches) => {
+    for (const [id, patch] of Object.entries(patches ?? {})) {
+      const entry = entries.get(id);
+      if (entry) entries.set(id, deepMerge(entry, patch));
+    }
+  };
+  var removeIds = (entries, ids) => {
+    for (const id of ids ?? []) entries.delete(id);
+  };
+
   // src/bench.ts
   var SNAKE_CASE = /^[a-z][a-z0-9_]*$/;
   var finite2 = (n) => typeof n === "number" && Number.isFinite(n);
@@ -476,9 +550,15 @@ var GameContracts = (() => {
       return;
     }
     const seen = /* @__PURE__ */ new Set();
+    const groups = /* @__PURE__ */ new Set();
+    let previousGroup;
     for (const option of control.options) {
       if (seen.has(option.id)) problems.push(`${label} repeats option "${option.id}"`);
       seen.add(option.id);
+      if (option.group !== void 0 && (typeof option.group !== "string" || option.group === "")) problems.push(`${label} option "${option.id}" has an empty group`);
+      else if (option.group !== void 0 && option.group !== previousGroup && groups.has(option.group)) problems.push(`${label} group "${option.group}" is split: its options must be next to each other`);
+      if (typeof option.group === "string" && option.group !== "") groups.add(option.group);
+      previousGroup = option.group;
     }
     if (!seen.has(control.default)) problems.push(`${label} default "${control.default}" is not among its options`);
   }