@adatechnology/game-contracts 0.16.0 → 0.18.0

package/dist/index.d.ts

@@ -107,6 +107,12 @@ interface PartSpec {
         capacity?: number;
         rebar?: TensionRebar;
         pile?: PileSpec;
+        /**
+         * Longest free span, in metres, the part holds on the parts it stands on: a shelf on the sides of a bookcase, a plank across two trestles. When
+         * a support goes and the ones left give it a longer span (one end hangs: the span of a cantilever is twice its overhang), the part falls with
+         * what rests on it. Without it the part stays as long as any support is left.
+         */
+        maxSpan?: 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
@@ -506,6 +512,11 @@ interface PartState {
         center: Vec3;
         radius: number;
     };
+    /** Units (`PartSpec.units`) knocked out one by one by shots and blows, in the part's own axes (`chip` events). Raycasts and shots pass through them. */
+    chipped?: Array<{
+        center: Vec3;
+        size: Vec3;
+    }>;
     /** Index into `ObjectState.groups` of the piece this part belongs to (-1 when the part is broken, melted or ash). */
     group: number;
 }
@@ -773,7 +784,7 @@ type DestructionEvent = (EventBase & {
     parts: string[];
     mass: number;
 })
-/** The outer coat of a layered part came off at `point` (`layer` indexes `PartSpec.layers`; `area` in m²). */
+/** The outer coat of a layered part came off at `point` (`layer` indexes `PartSpec.layers`; `area` in m²); `layer` -1 is a crater in the bare core (`MaterialHit.crater`). */
  | (EventBase & {
     type: 'spall';
     part: string;
@@ -795,6 +806,18 @@ type DestructionEvent = (EventBase & {
     };
     fragments?: readonly Fragment[];
 })
+/**
+ * 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.
+ */
+ | (EventBase & {
+    type: 'chip';
+    part: string;
+    center: Vec3;
+    size: Vec3;
+    rotation: Quat;
+    fragments: readonly Fragment[];
+})
 /** Rebar of a reinforced part is bare: segments in world space. Empty `bars` means the cage is gone. */
  | (EventBase & {
     type: 'expose';
@@ -1723,6 +1746,17 @@ interface AreaPlacement {
     /** Starts still: no physics until it is grabbed, hit or pushed. For props laid side by side that would otherwise nudge each other off. */
     asleep?: boolean;
 }
+/** A rectangle of the floor made of something else: `rect` is `[x0, z0, x1, z1]` in world metres, `surface` a ground profile id of the host. */
+interface GroundZone {
+    readonly rect: readonly [number, number, number, number];
+    readonly surface: string;
+}
+/** What the floor is made of. `surface` is a ground profile id (`lawn`, `road`, `concrete_slab`, `tile_floor`...); a host that does not know it uses its default. */
+interface GroundLayout {
+    readonly surface: string;
+    /** Later zones over earlier ones. */
+    readonly zones?: readonly GroundZone[];
+}
 /** How the host sets the module's area up: what goes where, and where the camera starts. */
 interface ModuleArea {
     placements: AreaPlacement[];
@@ -1979,6 +2013,19 @@ interface ModuleHost {
      * player stops at them; the function is asked on every step, so it may follow a door that opens. Returns the function that takes it away. A host without a walking player leaves it out.
      */
     addBlocker?(blocked: (x: number, z: number, radius: number) => boolean): () => void;
+    /**
+     * Puts an item of the host's catalogue (from any loaded module, by its id) in the world as part of the scenery: it stays through the clears and the openings of areas, and shots, blows, blasts
+     * and fire hit it like any item (a module's lamp rig standing on a real car of the fleet). Scenarios that start from a seeded world run without it, and it comes back after them. `rotationY` turns it about the vertical axis. Returns null while no loaded module has the item; `remove`
+     * takes it away. A host without a catalogue leaves it out.
+     */
+    addObject?(itemId: string, place: {
+        readonly position: Vec3;
+        readonly rotationY?: number;
+    }): {
+        readonly objectId: string;
+        readonly root: unknown;
+        remove(): void;
+    } | null;
     /**
      * Lends the host the place of the hands for the tool in the module's hands (a weapon's grip and handguard): the host that draws the player's arms reads `source` every frame, after the
      * 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.
@@ -2017,6 +2064,8 @@ interface TestableModule<Context = unknown> {
     controls?(locale: string): ModuleControl[];
     layers?(locale: string): ModuleLayer[];
     metrics?(locale: string): ModuleMetric[];
+    /** The floor of the module's area, laid when the host opens it. Without it the host keeps its default floor. */
+    ground?: GroundLayout;
     /** Called once when the module is loaded, with what the host lends. Returns the function that undoes it. */
     attach?(host: ModuleHost): () => void;
 }
@@ -2221,4 +2270,25 @@ interface UnmarkedDrawing {
 /** Every visible mesh, line, point cloud or sprite under `root` with no marked ancestor (`root` itself not counted as one). */
 declare function unmarkedDrawings(root: unknown): UnmarkedDrawing[];
 
-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 FractureStyle, type Fragment, type FragmentHitOptions, type FragmentMark, 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, ignitionChance, kitOriginOf, markKitOrigin, mergeById, removeIds, resolveEntry, resolveIgnitionRules, sampleClip, scaleClip, shotExtras, shotToHit, sparkTargetFactor, toolAnimationStep, unmarkedDrawings, useToHit };
+/** A floor rectangle in an object's own space, metres (x across, z along). */
+interface Footprint {
+    readonly minX: number;
+    readonly maxX: number;
+    readonly minZ: number;
+    readonly maxZ: number;
+}
+/** What `footprintBlocker` reads of an object: its world matrix (three.js `Object3D`, duck-typed so the contracts stay free of three.js). */
+interface FootprintObject {
+    readonly matrixWorld: {
+        readonly elements: ArrayLike<number>;
+    };
+    readonly parent?: unknown;
+    updateWorldMatrix?(updateParents: boolean, updateChildren: boolean): void;
+}
+/**
+ * The `ModuleHost.addBlocker` function of a solid object standing on the floor: the walking player stays out of `footprint`, a rectangle in the object's own space,
+ * so the object blocks turned with it and follows it when it moves. An object out of the scene (no parent) blocks nothing.
+ */
+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 };

package/dist/index.global.js

@@ -43,6 +43,7 @@ var GameContracts = (() => {
     deepMerge: () => deepMerge,
     defineCategories: () => defineCategories,
     fillFactor: () => fillFactor,
+    footprintBlocker: () => footprintBlocker,
     ignitionChance: () => ignitionChance,
     kitOriginOf: () => kitOriginOf,
     markKitOrigin: () => markKitOrigin,
@@ -873,6 +874,24 @@ var GameContracts = (() => {
     walk(root, false);
     return out;
   }
+
+  // src/footprint.ts
+  function footprintBlocker(object, footprint) {
+    return (x, z, radius) => {
+      const o = typeof object === "function" ? object() : object;
+      const fp = typeof footprint === "function" ? footprint() : footprint;
+      if (!o || !fp || !o.parent) return false;
+      o.updateWorldMatrix?.(true, false);
+      const e = o.matrixWorld.elements;
+      const dx = x - e[12];
+      const dz = z - e[14];
+      const ax = e[0] ** 2 + e[1] ** 2 + e[2] ** 2;
+      const az = e[8] ** 2 + e[9] ** 2 + e[10] ** 2;
+      const lx = (dx * e[0] + dz * e[2]) / (ax || 1);
+      const lz = (dx * e[8] + dz * e[10]) / (az || 1);
+      return lx > fp.minX - radius && lx < fp.maxX + radius && lz > fp.minZ - radius && lz < fp.maxZ + radius;
+    };
+  }
   return __toCommonJS(index_exports);
 })();
 //# sourceMappingURL=index.global.js.map