@adatechnology/game-contracts 0.19.0 → 0.20.0

package/dist/index.d.ts

@@ -77,6 +77,13 @@ interface PartSpec {
          */
         outflow?: Vec3;
     };
+    /**
+     * Loose dry contents of a hollow part (the flakes of a cereal box, flour, sugar, coffee): a hole through it lets out a puff of them, in `color`
+     * (0xRRGGBB). The renderer draws the puff; nothing is lost from the part's mass.
+     */
+    powder?: {
+        color: number;
+    };
     /** The part explodes when destroyed, or when its temperature passes `atC` (gas bottle, fuel tank, aerosol). */
     explodes?: {
         energy: number;
@@ -658,12 +665,17 @@ type DestructionEvent = (EventBase & {
     part: string;
     dent: Dent;
     worldPoint: Vec3;
-}) | (EventBase & {
+})
+/** `powder`: the part's loose dry contents (`PartSpec.powder`), which puff out of the hole. */
+ | (EventBase & {
     type: 'hole';
     part: string;
     hole: Hole;
     worldPoint: Vec3;
     exitPoint?: Vec3;
+    powder?: {
+        color: number;
+    };
 }) | (EventBase & {
     type: 'crack';
     part: string;
@@ -812,6 +824,7 @@ type DestructionEvent = (EventBase & {
 /**
  * One unit of a wall of units (`PartSpec.units`: a brick, a block) came out under shots or blows: `center` in world space, `size` in the part's own
  * axes and `rotation` the part's world rotation (the box of the unit that left), `fragments` the unit itself. The part stays: draw the gap, do not hide it.
+ * With `torn`, nothing left the part but what a blow tore off its face (splinters of wood, lumps of MDF): the hole and the marks around it stay drawn.
  */
  | (EventBase & {
     type: 'chip';
@@ -820,6 +833,7 @@ type DestructionEvent = (EventBase & {
     size: Vec3;
     rotation: Quat;
     fragments: readonly Fragment[];
+    torn?: true;
 })
 /** Rebar of a reinforced part is bare: segments in world space. Empty `bars` means the cage is gone. */
  | (EventBase & {
@@ -1321,18 +1335,50 @@ interface ItemUseDef {
     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. */
+    /**
+     * Keyframes: time 0..duration, the hand-relative position/rotation (Euler XYZ) of the item and the container action during that key. `eat` takes the contents
+     * out as `drink` does, as food: the liquid packed with it (the brine of a tin, the oil of the sardines) goes with the food, without the effects of drinking it. `turn` is the
+     * time the other hand turns a part of the item round (a screw cap, `twistStroke`); the container itself does nothing then.
+     */
     keys: Array<{
         t: number;
         position: Vec3;
         rotation: Vec3;
-        action?: 'drink' | 'pour' | 'open' | 'close' | 'none';
+        action?: 'drink' | 'eat' | 'pour' | 'open' | 'close' | 'turn' | 'none';
         rate?: number;
     }>;
     /** Only valid when the container holds one of these (empty = any). */
     liquids?: LiquidId[];
 }
 
+/**
+ * The seal of a closed container (a food tin, a drink can, a jar, a bottle with a cap): what opens it and whether a breach spoils what is inside.
+ * Plain data and one pure check, shared by the item rules (`resolveUse` of game-items) and any host that lets the player open and eat (the test room).
+ */
+interface SealSpec {
+    /** Ids of the tools that open it (items or weapons: `can_opener`, `knife`); any one of them is enough. */
+    readonly openWith?: readonly string[];
+    /** It opens by hand (a pull tab, a ring pull, a screw cap): no tool needed. */
+    readonly byHand?: boolean;
+    /** A hole through the container or a leak spoils what is inside: it can no longer be eaten or drunk. */
+    readonly spoilsWhenBreached?: boolean;
+}
+/** The state of one container: opened, holed through (a shot, a blade) or leaking. */
+interface SealState {
+    readonly opened?: boolean;
+    readonly breached?: boolean;
+    readonly leaked?: boolean;
+}
+/** Why a sealed container cannot be eaten or drunk now. */
+type SealBlock = 'sealed' | 'breached' | 'leaked';
+/** Whether it can be opened with the tools at hand, and with which one (undefined when it opens by hand). */
+declare const sealOpener: (seal: SealSpec, tools: Iterable<string>) => {
+    readonly ok: boolean;
+    readonly tool?: string;
+};
+/** What stops eating or drinking it now, or undefined when nothing does. A spoiled container (breached, leaked) is blocked even once open. */
+declare const sealBlock: (seal: SealSpec, state: SealState) => SealBlock | undefined;
+
 /**
  * Where a hand should be, in world space. `position` is the middle of the palm; the orientation follows one convention for every hand: the hand-local +x runs from the wrist to the
  * knuckles (the way the fingers point when open), +y is the back of the hand and +z completes the frame (for a right hand the little finger side; the thumb is at -z). A left hand is the
@@ -1360,10 +1406,40 @@ interface HandTargets {
     fingers?: {
         index?: number;
     };
+    /**
+     * Where the elbows go: `view` puts them on screen beside the hand, out to the side, as a tool held out in front (default); `body` lets them hang down and back by the body, as an item
+     * carried close (a can, a bottle), where an elbow out to the side would lift it above the shoulder.
+     */
+    elbows?: 'view' | 'body';
 }
 /** Read every frame by whoever draws the arms; answers null while nothing is held. */
 type HandTargetSource = () => HandTargets | null;
 
+/** How a hand turns something round in strokes (a screw cap, a tap handle, a knob): what `twistStroke` answers for one moment of the turning. */
+interface TwistStroke {
+    /** Radians the wrist is turned from the middle of its stroke, positive the way the part turns. */
+    readonly angle: number;
+    /** Radians the part has turned in all, from 0 to `strokes * reach`. */
+    readonly turned: number;
+    /** How closed the fingers are, 0 open to 1 closed: closed on the part while it turns, open while the wrist turns back. */
+    readonly grip: number;
+    /** 0..1, how far the hand rises off the part while the wrist turns back (1 is `TWIST_LIFT` metres). */
+    readonly lift: number;
+}
+interface TwistOptions {
+    /** Strokes of the wrist. Default 3. */
+    readonly strokes?: number;
+    /** Radians the part turns in one stroke (a wrist turns about a quarter round with its hold). Default 1.6. */
+    readonly reach?: number;
+}
+/** Metres a hand rises off the part between two strokes. */
+declare const TWIST_LIFT = 0.012;
+/**
+ * The hand turning a part round at `share` (0..1) of the whole turning: in each stroke the wrist turns with the part, then lets go, rises a little and turns back.
+ * Pure and the same for every host, so first and third person turn the same hand the same way.
+ */
+declare const twistStroke: (share: number, options?: TwistOptions) => TwistStroke;
+
 /**
  * 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.
@@ -1685,6 +1761,36 @@ interface ModuleItemFluid {
     uses?: string[];
     offset?: Vec3;
 }
+/** A closed container the player opens before eating or drinking it (a food tin, a drink can): the seal, and how the item looks open. */
+interface ModuleItemSeal extends SealSpec {
+    /** Draws the item opened: gets the root `build` returned (the cut lid of a tin, the mouth of a can). */
+    open?: (root: unknown) => void;
+    /** Shows what is left in it once open: `share` of what it held (0 eaten up), after each bite or sip. */
+    contents?: (root: unknown, share: number) => void;
+    /**
+     * The use (an `ItemUseDef` id, such as `unscrew`) a by-hand seal is opened with: it plays before the first bite or sip, the other hand turning the part
+     * during its `turn` keys, and the item opens at its `open` key. Without it a by-hand seal opens at once on the way to the mouth (a pull tab).
+     */
+    openUse?: string;
+    /** Draws the part being opened mid-way: `turned` radians round its axis, `lift` 0..1 of the way off (a screw cap leaving its thread). */
+    turn?: (root: unknown, state: {
+        readonly turned: number;
+        readonly lift: number;
+    }) => void;
+}
+/** A place on an item where a body sits or lies (a chair, a sofa cushion, a bed), in the item's own frame, the same shape as a `game-interactables` seat. */
+interface ItemSeat {
+    id: string;
+    pose: 'sit' | 'lie';
+    /** Hips (sit) or pelvis (lie). */
+    pos: Vec3;
+    /** Facing of the body, relative to the item. */
+    ry: number;
+    /** Eye height above `pos`. Default 0.62 sitting, 0.18 lying. */
+    eye?: number;
+    /** Where the body stands when it gets up. */
+    exit: 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;
@@ -1711,12 +1817,18 @@ interface TestableItem {
     /** 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 a sealed container: it is opened first (with a tool or by hand), and a breach may spoil it (`SealSpec`). */
+    seal?: ModuleItemSeal;
     /** 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 big piece that stands on the floor (a sofa, a wardrobe, a fridge) and can be pushed by leaning on it. Default false: what goes in the hand is grabbed, never pushed. */
+    pushable?: boolean;
+    /** Where a body sits or lies on it: the host can seat the player there. */
+    seats?: readonly ItemSeat[];
     /** 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;
     /**
@@ -1981,6 +2093,21 @@ interface PlayerState {
     /** How the camera follows the player (`first`, `shoulder`...); the ids are the host's. */
     readonly cameraMode: string;
 }
+/** A leaf a module moves itself, for the host's hand (`ModuleHost.reachFor`). */
+interface HostReach {
+    /** World point of the handle now. */
+    handle(): Vec3;
+    /** World point of the hinge of a turning leaf: the host stands the player beside the free edge, clear of the swing. Left out, the player stands in front of the handle. */
+    hinge?(): Vec3;
+    /** How long the hand stays on the handle after the grip, seconds (the module's swing). */
+    readonly seconds: number;
+    /** The leaf comes toward the body (true) or goes away (false). Default true. */
+    readonly pull?: boolean;
+    /** Locked or barred: the hand only shakes it. */
+    readonly locked?: boolean;
+    /** The hand is on the handle. */
+    onGrip?(): 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.
@@ -2004,6 +2131,11 @@ interface ModuleHost {
      * unsubscribe function. A host that never clears leaves it out.
      */
     onClear?(listener: () => void): () => void;
+    /**
+     * Follow the host going back to its seeded start (before each scenario): the module's own random streams, seed counters and clocks are to go back to where
+     * they began, so a scenario does the same whatever ran before it. Returns the unsubscribe function. A host that never resets leaves it out.
+     */
+    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;
     /**
@@ -2034,6 +2166,18 @@ interface ModuleHost {
      * frame hooks have run, and puts the hands there. Pass null (or call the returned function) to let go. A host without arms leaves it out.
      */
     setHandTargets?(source: HandTargetSource | null): () => void;
+    /**
+     * Where the player's body holds a tool now (world space), in every view (the weapon is the body's own): `position` is the pocket of the right shoulder a stock rests on, `quaternion` turns
+     * to the aim (-z the aim, x right, y up, as a camera). A module draws the tool there at its real size. Null for a host with no body (the module puts the same pocket under the camera's eye);
+     * a host without a body leaves it out.
+     */
+    holdFrame?(): HandPose | null;
+    /**
+     * Puts the player's hand on a leaf the module moves itself (a door of a house): the host plays the reach to `handle()`, calls `onGrip` when the hand is on it (the module then turns
+     * the handle and swings the leaf), keeps the hand on `handle()` for `seconds` as it moves, and takes it back; the body pulls or pushes (`pull`) or shakes a locked one (`locked`).
+     * `handle` answers the world point of the handle every frame. A host without a body leaves it out (the module then moves the leaf at once).
+     */
+    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;
     /** Lent only to a module that declares controls, layers or metrics. */
@@ -2294,4 +2438,4 @@ 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 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 HostTool, type HostToolAttachment, IMPACT_CONTRACT, type IgnitionRules, type ImpactContract, type ItemAnimationContract, type ItemUseDef, type JointKind, type JointSpec, type JointState, KIT_ORIGIN_KEY, type KitOrigin, type LiquidId, type LoopHandle, MISSING_BITS, type MaterialId, type ModuleArea, type ModuleBench, type ModuleControl, type ModuleHost, type ModuleItemFluid, type ModuleLayer, type ModuleMetric, type ModuleScenario, type NumberControl, type ObjectState, type PartBreach, type PartShape, type PartSpec, type PartState, type PartStatus, type PartUnits, type PileSpec, type PlayerState, type Quat, type RayHit, type Reinforcement, STAGE_EVENT, type SegmentKind, type ShelterOptions, type Shot, type SoilLayer, type SoilProfile, type SoilState, type SoundHandle, type SoundRequest, type SpecReport, type StructureRole, type SurfaceLayer, TOOL_CLIP, type TensionRebar, type TestableItem, type TestableModule, type Thumbnail, type ToolAnimationStep, type ToolAnimator, type ToolClipId, type ToolClipPlayer, type ToolClipPlayerOptions, type ToolClipSet, type ToolCommand, type ToolCommandResult, type ToolKind, type ToolRig, type TunedMassDamper, type UnmarkedDrawing, type Use, type Vec3, type WarmUpProbes, type WindExposure, type WindState, applyPatches, blastShove, checkAnimation, checkBench, checkCategorized, checkDestructible, checkHit, checkSpec, checkToolClips, createEnvironmentBus, createToolClipPlayer, deepMerge, defineCategories, fillFactor, footprintBlocker, ignitionChance, kitOriginOf, markKitOrigin, mergeById, removeIds, resolveEntry, resolveIgnitionRules, sampleClip, scaleClip, shotExtras, shotToHit, sparkTargetFactor, toolAnimationStep, unmarkedDrawings, useToHit };
+export { type ActionControl, type AnimationClipSpec, type AnimationEventSpec, type AnimationKey, type AnimationPose, type AreaPlacement, type AudioListener, type AudioSink, type BallisticExtras, type BenchChange, type BenchDeclaration, type BenchReport, type BenchSheet, type BlastOptions, type BlastReport, type BlastShove, type BlastShoveOptions, type BlastSource, type BodyRegion, type BodySlot, type BooleanControl, type BusyOptions, type BusySink, type BusyTask, type CategorizedOptions, type CategorizedReport, type CategoryDef, type CategoryOptions, type CategoryRegistry, type ChainDelay, type CheckOptions, type CheckSpecOptions, type ChoiceControl, type ChoiceOption, type ConfinementOptions, type ContainerSpec, type ContractChecker, type ContractContext, type ControlPatch, type ControlValue, type Crack, DEFAULT_BLAST_SHOVE, DEFAULT_ENVIRONMENT, DEFAULT_IGNITION_RULES, type DamageStage, type DamageType, type DebrisKind, type DeepPartial, type Dent, type DestructibleImpl, type DestructibleSpec, type DestructionEvent, type DestructionEventType, type EffectHandle, type EffectRequest, type EffectSink, type EnvironmentBus, type EnvironmentKey, type EnvironmentState, type ExplosionChain, type FluidKind, type 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 };

package/dist/index.global.js

@@ -29,6 +29,7 @@ var GameContracts = (() => {
     MISSING_BITS: () => MISSING_BITS,
     STAGE_EVENT: () => STAGE_EVENT,
     TOOL_CLIP: () => TOOL_CLIP,
+    TWIST_LIFT: () => TWIST_LIFT,
     applyPatches: () => applyPatches,
     blastShove: () => blastShove,
     checkAnimation: () => checkAnimation,
@@ -53,10 +54,13 @@ var GameContracts = (() => {
     resolveIgnitionRules: () => resolveIgnitionRules,
     sampleClip: () => sampleClip,
     scaleClip: () => scaleClip,
+    sealBlock: () => sealBlock,
+    sealOpener: () => sealOpener,
     shotExtras: () => shotExtras,
     shotToHit: () => shotToHit,
     sparkTargetFactor: () => sparkTargetFactor,
     toolAnimationStep: () => toolAnimationStep,
+    twistStroke: () => twistStroke,
     unmarkedDrawings: () => unmarkedDrawings,
     useToHit: () => useToHit
   });
@@ -407,6 +411,38 @@ var GameContracts = (() => {
     return 1 - (1 - Math.min(1, Math.max(0, spark))) * (1 - Math.min(1, Math.max(0, flame)));
   };
 
+  // src/seal.ts
+  var sealOpener = (seal, tools) => {
+    if (seal.byHand || !seal.openWith || seal.openWith.length === 0) return { ok: true };
+    const have = new Set(tools);
+    const tool = seal.openWith.find((id) => have.has(id));
+    return tool === void 0 ? { ok: false } : { ok: true, tool };
+  };
+  var sealBlock = (seal, state) => {
+    if (seal.spoilsWhenBreached && state.breached) return "breached";
+    if (seal.spoilsWhenBreached && state.leaked) return "leaked";
+    if (!state.opened) return "sealed";
+    return void 0;
+  };
+
+  // src/twist.ts
+  var TWIST_LIFT = 0.012;
+  var TURNING = 0.7;
+  var smooth = (k) => k * k * (3 - 2 * k);
+  var twistStroke = (share, options = {}) => {
+    const strokes = Math.max(1, Math.round(options.strokes ?? 3));
+    const reach = options.reach ?? 1.6;
+    const along = Math.min(1, Math.max(0, share)) * strokes;
+    const index = Math.min(strokes - 1, Math.floor(along));
+    const phase = along - index;
+    if (phase <= TURNING) {
+      const k2 = smooth(phase / TURNING);
+      return { angle: reach * (k2 - 0.5), turned: reach * (index + k2), grip: 1, lift: 0 };
+    }
+    const k = (phase - TURNING) / (1 - TURNING);
+    return { angle: reach * (0.5 - smooth(k)), turned: reach * (index + 1), grip: 0.35, lift: Math.sin(k * Math.PI) };
+  };
+
   // src/animation.ts
   var finite3 = (v) => Array.isArray(v) && v.length === 3 && v.every((n) => typeof n === "number" && Number.isFinite(n));
   var checkAnimation = (clip, partIds) => {