@adatechnology/game-contracts 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -1559,6 +1559,10 @@ interface HandTargets {
     fingers?: {
         index?: number;
     };
+    /** The same for the left hand (its index on the trigger of a tool of its own, with a tool in each hand); absent, the left hand's fingers all follow `gripL`. */
+    fingersL?: {
+        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.
@@ -1575,8 +1579,19 @@ interface MuzzlePose {
     /** The module draws the muzzle flash itself: the host draws none of its own. */
     readonly drawsFlash: boolean;
 }
-/** Read by the host at each shot; null while the tool in the hands has no muzzle (a knife, a bare hand). */
-type MuzzleSource = () => MuzzlePose | null;
+/** A hand of the body: `R` the right, `L` the left. A tool in one hand alone is in the right; the left holds one of its own only with a tool in each hand (`HostTool.offHand`). */
+type ToolHand = 'R' | 'L';
+/**
+ * Read by the host at each shot; null while the tool in the hands has no muzzle (a knife, a bare hand). `hand` is the hand that fired (absent: the right one); a source that draws
+ * one tool only answers the same for both.
+ */
+type MuzzleSource = (hand?: ToolHand) => MuzzlePose | null;
+/**
+ * The layer of what the first-person view draws over the world (three.js `Object3D.layers`): the tool in the hands and the arms that hold it. A host with a first-person view draws
+ * the world without this layer, then this layer alone over it with the depth cleared and its own field of view (`ModuleHost.setViewmodelFov`), as shooters draw the weapon in the hands:
+ * it never goes into a wall, and the gun and the arms are framed by the lens chosen for them. Seen from outside (third person) nothing is on it.
+ */
+declare const FIRST_PERSON_LAYER = 9;
 
 /** 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 {
@@ -1718,6 +1733,13 @@ interface BenchSheet {
         readonly name: string;
     }[];
     readonly note?: string;
+    /** A picture of the real thing the card is about, with its author and licence: the host shows it on the card, linked to `page`. */
+    readonly image?: {
+        readonly url: string;
+        readonly alt: string;
+        readonly credit?: string;
+        readonly page?: string;
+    };
     /** A strip of named segments (seconds), with tick marks and a playhead that follows the module metric `metric`. */
     readonly timeline?: {
         readonly segments: readonly {
@@ -2247,7 +2269,8 @@ interface ModuleArea {
     };
 }
 /**
- * What the player did with the tool in hand, as the host reports it. Hosts emit what they support; modules ignore what they do not need. The
+ * What the player did with the tool in hand, as the host reports it. A tool event names the `hand` whose tool it is when the player holds one in each (`HostTool.offHand`): `L` for the
+ * left; absent is the right, the hand of a tool held alone. A `tool` event with `hand: 'L'` puts the left hand's tool in it, and one with an empty `weapon` lets the left hand go. Hosts emit what they support; modules ignore what they do not need. The
  * names are of a tool's cycle, not of a firearm: a nail gun, a chainsaw or a hose has modes, faults and a safety too.
  */
 type HostEvent = 
@@ -2256,6 +2279,7 @@ type HostEvent =
     type: 'tool';
     weapon: string;
     duration?: number;
+    hand?: ToolHand;
 }
 /** `shots` are projectiles (a shotgun shell is many), `rounds` the cartridges spent (a burst is several). */
  | {
@@ -2272,11 +2296,13 @@ type HostEvent =
      */
     origin?: Vec3;
     direction?: Vec3;
+    hand?: ToolHand;
 }
 /** The trigger was pulled, the round was spent and nothing left the tool (a dud cartridge): no projectile, no recoil. */
  | {
     type: 'misfire';
     weapon: string;
+    hand?: ToolHand;
 }
 /** `kind` is how the rule reloads (`tactical`, `empty`, `one_by_one`); `duration` the seconds of the whole reload, on `start`. */
  | {
@@ -2285,27 +2311,33 @@ type HostEvent =
     phase: 'start' | 'end';
     kind?: string;
     duration?: number;
+    hand?: ToolHand;
 } | {
     type: 'empty';
     weapon: string;
+    hand?: ToolHand;
 } | {
     type: 'mode';
     weapon: string;
     mode: string;
+    hand?: ToolHand;
 } | {
     type: 'fault';
     weapon: string;
     fault: string;
+    hand?: ToolHand;
 } | {
     type: 'clear';
     weapon: string;
     fault: string;
     phase: 'start' | 'end';
     duration?: number;
+    hand?: ToolHand;
 } | {
     type: 'safety';
     weapon: string;
     on: boolean;
+    hand?: ToolHand;
 }
 /** The action works between shots (a pump, a bolt); `duration` is the seconds of the cycle, on `start`. */
  | {
@@ -2313,17 +2345,20 @@ type HostEvent =
     weapon: string;
     phase: 'start' | 'end';
     duration?: number;
+    hand?: ToolHand;
 }
 /** A step of a longer phase (a reload's magazine out, magazine in, charge), at the moment the rule reaches it. */
  | {
     type: 'stage';
     weapon: string;
     stage: string;
+    hand?: ToolHand;
 }
 /** One more round went into the tool while it loads round by round. */
  | {
     type: 'feed';
     weapon: string;
+    hand?: ToolHand;
 }
 /**
  * A throwable with a timer fuse is cooked: the trigger pulls the pin (`start`, `fuse` is the whole fuse), releasing throws it with what is left of
@@ -2334,6 +2369,7 @@ type HostEvent =
     weapon: string;
     phase: 'start' | 'throw' | 'burst';
     fuse: number;
+    hand?: ToolHand;
 }
 /** An accessory went on (`fit`), came off (`remove`) or broke (`break`) at `mount`; `duration` is the seconds the work takes, on `fit` and `remove`. */
  | {
@@ -2343,6 +2379,7 @@ type HostEvent =
     attachment: string;
     mount: string;
     duration?: number;
+    hand?: ToolHand;
 }
 /** A light or a laser was turned on or off. */
  | {
@@ -2350,6 +2387,7 @@ type HostEvent =
     weapon: string;
     attachment: string;
     on: boolean;
+    hand?: ToolHand;
 }
 /** The stock was folded or slid in (`collapsed`) or opened (`extended`); `kind` is how it moves (`fold`, `retract`), `duration` the seconds it takes. */
  | {
@@ -2358,6 +2396,7 @@ type HostEvent =
     state: 'collapsed' | 'extended';
     kind?: string;
     duration?: number;
+    hand?: ToolHand;
 }
 /** The weapon in hand changed between the main weapon and the one under its barrel (`on`: the under-barrel one is in use); `duration` is the seconds of the switch. */
  | {
@@ -2365,6 +2404,7 @@ type HostEvent =
     weapon: string;
     on: boolean;
     duration?: number;
+    hand?: ToolHand;
 }
 /**
  * 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.
@@ -2383,6 +2423,16 @@ type HostEvent =
     /** Inside this radius (metres) the blast is lethal to a body it reaches. */
     lethalRadius?: number;
 }
+/**
+ * With a tool in each hand, the tool of `hand` is put away against the body (`on`) to free that hand for the other tool, or taken back in hand; `duration` is the seconds the move takes.
+ */
+ | {
+    type: 'stow';
+    weapon: string;
+    on: boolean;
+    duration?: number;
+    hand?: ToolHand;
+}
 /** The player crouched or stood up, or the camera mode changed; read the new state with `host.player()`. */
  | {
     type: 'player';
@@ -2420,10 +2470,20 @@ interface HostTool {
     suppressed?: boolean;
     /** True while the trigger and the reload go to the launcher under the barrel. */
     underbarrelActive?: boolean;
+    /**
+     * True while the tool is put away against the body (tucked in the belt, under the arm) to free its hand for the tool in the other hand: a magazine changed with the free hand, with a
+     * tool in each hand. It does not fire then; the host says when it goes and comes back with a `stow` event.
+     */
+    stowed?: boolean;
     /** Kg: the tool with what is on it. */
     mass?: number;
     /** Seconds to bring the tool to the sights, with what is on it. */
     aimSeconds?: number;
+    /**
+     * The tool in the left hand when the player holds one in each (a pistol in each hand): its own rounds, reload and state. Absent with one tool, which is in the right hand. A tool
+     * in each hand is held out, never brought to the eye: the second button pulls the left one's trigger instead.
+     */
+    offHand?: HostTool;
 }
 interface HostToolAttachment {
     readonly id: string;
@@ -2596,12 +2656,17 @@ interface ModuleHost {
      * muzzle of the model and not at a guess in front of the eye. Pass null (or call the returned function) to let go. A host that draws no shot effects leaves it out.
      */
     setMuzzleSource?(source: MuzzleSource | null): () => void;
+    /**
+     * The field of view, degrees vertical, the host draws `FIRST_PERSON_LAYER` with in first person (the lens of the tool in the hands); null goes back to the view's own. A host that draws
+     * no first-person layer leaves it out.
+     */
+    setViewmodelFov?(degrees: number | 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.
+     * a host without a body leaves it out. With `hand: 'L'` it is the pocket of the left shoulder (the same frame mirrored), where a tool in the left hand is held.
      */
-    holdFrame?(): HandPose | null;
+    holdFrame?(hand?: ToolHand): 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`).
@@ -2911,4 +2976,4 @@ declare function footprintBlocker(object: FootprintObject | (() => FootprintObje
 /** @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 BlastImpulseOptions, 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_IMPULSE, 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, FRAGMENT_COVER, 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 MuzzlePose, type MuzzleSource, 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, blastBodySpeed, blastShove, bodyImpulse, bodyMass, checkAnimation, checkBench, checkCategorized, checkDeferredQueue, checkDestructible, checkHit, checkSpec, checkToolClips, createEnvironmentBus, createToolClipPlayer, deepMerge, defineCategories, fillFactor, footprintBlocker, footstepSoundId, hitSoundId, ignitionChance, isSurfaceId, kitOriginOf, knockOf, landSoundId, launchBody, leadClipEvents, markKitOrigin, mergeById, removeIds, resetWarnOnce, resolveEntry, resolveIgnitionRules, sampleClip, scaleClip, sealBlock, sealOpener, shotExtras, shotToHit, sideOnImpulse, sparkTargetFactor, stepKnock, surfaceOfMaterial, swingSoundId, takeLaunch, toolAnimationStep, twistStroke, unmarkedDrawings, useToHit };
+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 BlastImpulseOptions, 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_IMPULSE, 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, FIRST_PERSON_LAYER, FOOTSTEP_SOUND_IDS, FRAGMENT_COVER, 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 MuzzlePose, type MuzzleSource, 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 ToolHand, type ToolKind, type ToolRig, type TunedMassDamper, type TwistOptions, type TwistStroke, type UnmarkedDrawing, type Use, type Vec3, type WarmUpProbes, type WindExposure, type WindState, applyPatches, blastBodySpeed, blastShove, bodyImpulse, bodyMass, checkAnimation, checkBench, checkCategorized, checkDeferredQueue, checkDestructible, checkHit, checkSpec, checkToolClips, createEnvironmentBus, createToolClipPlayer, deepMerge, defineCategories, fillFactor, footprintBlocker, footstepSoundId, hitSoundId, ignitionChance, isSurfaceId, kitOriginOf, knockOf, landSoundId, launchBody, leadClipEvents, markKitOrigin, mergeById, removeIds, resetWarnOnce, resolveEntry, resolveIgnitionRules, sampleClip, scaleClip, sealBlock, sealOpener, shotExtras, shotToHit, sideOnImpulse, sparkTargetFactor, stepKnock, surfaceOfMaterial, swingSoundId, takeLaunch, toolAnimationStep, twistStroke, unmarkedDrawings, useToHit };

package/dist/index.global.js

@@ -31,6 +31,7 @@ var GameContracts = (() => {
     DEFAULT_SURFACE: () => DEFAULT_SURFACE,
     DEFERRED_PRIORITY: () => DEFERRED_PRIORITY,
     DEFERRED_QUEUE_ID: () => DEFERRED_QUEUE_ID,
+    FIRST_PERSON_LAYER: () => FIRST_PERSON_LAYER,
     FOOTSTEP_SOUND_IDS: () => FOOTSTEP_SOUND_IDS,
     FRAGMENT_COVER: () => FRAGMENT_COVER,
     FRAME_PHASES: () => FRAME_PHASES,
@@ -608,6 +609,9 @@ var GameContracts = (() => {
     return void 0;
   };
 
+  // src/hands.ts
+  var FIRST_PERSON_LAYER = 9;
+
   // src/twist.ts
   var TWIST_LIFT = 0.012;
   var TURNING = 0.7;