@adatechnology/game-test-room 0.13.0 → 0.15.0

package/README.md

@@ -94,6 +94,22 @@ A `SceneryObject` is `{ spec, position?, rotationY?, colors?, build?, label?, to
 
 `tap` is the room's water tap: omitted, the room draws a post with an arm beside the table; `{ build(THREE), spout, position?, rotationY? }` puts the host's model there (the origin where it stands, `spout` where the water leaves it; by default it stands on the table top with the spout over its right half); `null` removes it.
 
+## Test table
+
+`room.testTable` lays the catalogue on a table a page at a time, so every item can be tried one by one with the same hit. The table is a `scenery` piece with a `top` (id `test_table`, or `testTable: { scenery }`); the room never draws one of its own, the host passes its model (the example uses the long dining table of the furniture catalogue, `furnitureSpec` of `game-floorplan-three`). Without that piece the table lays nothing; `testTable: false` also leaves the panel out.
+
+```ts
+createTestRoom({ ..., scenery: { test_table: { spec, build, top, position: [-8, 0, 3] } } })
+room.testTable.open('Items')          // clears the room and lays the first page of the group along the front edge of the table
+room.testTable.next()                 // the next page (a page holds what fits on the table)
+room.testTable.find('item_canned_beans') // the page that holds that item, with it picked
+room.testTable.select(objectId)       // the item the trials hit (the first one until another is picked)
+room.testTable.trial('shot')          // 'shot' | 'punch' | 'stab' | 'fire' | 'blast'
+room.testTable.relay()                // puts the table and the page back as they were
+```
+
+A trial equips its tool, puts the player in front of the item, aims at its centre and uses the tool: a 9 mm pistol from 2.5 m, the fists and a knife up close, a flamethrower burst from 1.6 m, and a fragmentation grenade set off just behind the item (`DEFAULT_TRIALS`; `testTable: { trials: { shot: { weapon: 'rifle_5_56' } } }` changes one). What happens goes to the log like any other hit. With the UI on, the **Test table** panel (between the inspector and the log) has the group, the pages, a search that lays the page of an item, the items on the table (a click picks one) and a button per trial plus **Put back**.
+
 ## Models of thrown and placed explosives
 
 The room knows the arsenal's ids, not the weapons' models. `projectileModel({ weapon, explosive, kind })` (`kind`: `grenade`, `molotov`, `rocket` or `charge`) is the host's hook: it answers `{ model, axis? }` (`axis`: the length of the model, default +y; a rocket points it along its flight) or `null`, and the room draws a plain primitive (a sphere, a cylinder, a box) only where it answers nothing. `@adatechnology/game-weapons-three` has one: `projectileModel(THREE, query)`.

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import * as THREE_NS from 'three';
 import { AudioEngine } from '@adatechnology/game-audio';
-import { Vec3, DestructionWorld, BlastOptions, DestructibleSpec, DestructionOptions, DestructionEvent } from '@adatechnology/game-destruction';
+import { Vec3 as Vec3$1, DestructionWorld, BlastOptions, DestructibleSpec, DestructionOptions, DestructionEvent } from '@adatechnology/game-destruction';
 export { DestructionEvent, Vec3 } from '@adatechnology/game-destruction';
-import { BusySink, HandTargets, ModuleControl, ControlValue, ModuleLayer, EnvironmentBus, BusyTask, BusyOptions, TestableModule, DestructibleImpl, AnimationClipSpec, BlastShoveOptions } from '@adatechnology/game-contracts';
+import { BusySink, Vec3, HandTargets, ModuleControl, ControlValue, ModuleLayer, EnvironmentBus, BusyTask, BusyOptions, TestableModule, DestructibleImpl, AnimationClipSpec, BlastShoveOptions } from '@adatechnology/game-contracts';
 export { AnimationClipSpec, DestructibleImpl, ItemAnimationContract, ModuleScenario, TestableItem, TestableModule } from '@adatechnology/game-contracts';
 import { DestructionRenderer, SpecFromObjectOptions, Quality } from '@adatechnology/game-destruction-three';
 import { Arsenal, WeaponState, WeaponDef } from '@adatechnology/game-weapons';
@@ -63,6 +63,140 @@ interface LogOptions {
 }
 declare function createLog(options?: LogOptions): WritableLog;
 
+/**
+ * What a trial does to one object: a shot, a punch, a knife blow, a flame on it or a blast beside it. The test table runs one on the object it has picked, so every item of the
+ * catalogue can be tried one by one with the same hit.
+ */
+type TrialKind = 'shot' | 'punch' | 'stab' | 'fire' | 'blast';
+declare const TRIAL_KINDS: readonly TrialKind[];
+/**
+ * How the room runs a trial: the tool (an id of the arsenal), where the player stands and how long the trigger is held.
+ * `distance` is metres from the front face of the object (the side the player comes from) to the eye, `lift` metres the eye is above the object's centre, `hold` seconds the
+ * trigger stays down (a flame). For `blast` the explosive of `weapon` goes off `distance` metres behind the object, and the player watches from `watch` metres in front.
+ */
+interface TrialTool {
+    readonly weapon: string;
+    readonly distance: number;
+    readonly lift: number;
+    readonly hold?: number;
+    readonly watch?: number;
+}
+/** The tools of the trials: a 9 mm pistol, the fists, a knife, a flamethrower and a fragmentation grenade, all of the default arsenal. */
+declare const DEFAULT_TRIALS: Readonly<Record<TrialKind, TrialTool>>;
+/** The test table: which piece of the arena it is, the gap between the things laid on it and the trial tools (each one replaces the default's fields it gives). */
+interface TestTableOptions {
+    /** Id of the `scenery` piece with a `top` the items are laid on (default `test_table`). */
+    readonly scenery?: string;
+    /** Metres between two items on the table (default 0.12). */
+    readonly gap?: number;
+    /** Metres kept free at each end of the table (default 0.1). */
+    readonly margin?: number;
+    readonly trials?: Partial<Record<TrialKind, Partial<TrialTool>>>;
+}
+/** One item laid on the table. */
+interface TestTableObject {
+    readonly objectId: string;
+    readonly itemId: string;
+    readonly name: string;
+}
+/** The page of a group that lies on the table now. */
+interface TestTablePage {
+    /** The catalogue group (its translated name, as the catalogue tabs show it). */
+    readonly group: string;
+    /** Index of the page, from 0. */
+    readonly page: number;
+    /** Index in the group of the first item on the table, and how many the group has. */
+    readonly first: number;
+    readonly total: number;
+    readonly objects: readonly TestTableObject[];
+    /** The object the trials hit (the first one until another is picked). */
+    readonly selected: string | null;
+    readonly hasPrev: boolean;
+    readonly hasNext: boolean;
+}
+/** The test table of the room: lays a group of the catalogue on the table a page at a time, picks one object and runs the trials on it. */
+interface TestTable {
+    /** The groups of the catalogue that can be laid (every group with items). */
+    groups(): string[];
+    /** Every item that can be laid, with its group (what a search looks in). */
+    items(): Array<{
+        id: string;
+        name: string;
+        group: string;
+    }>;
+    /** Clears the room and lays page `page` (default 0) of `group`; null when the room has no table or the group no items. */
+    open(group: string, page?: number): TestTablePage | null;
+    next(): TestTablePage | null;
+    prev(): TestTablePage | null;
+    /** Lays the page of the group that holds `itemId` and picks it; null when no group has it (or the room has no table). */
+    find(itemId: string): TestTablePage | null;
+    /** Puts the table and the page back as they were before the trials: everything is restored and laid again. */
+    relay(): TestTablePage | null;
+    state(): TestTablePage | null;
+    /** Picks the object the trials hit; false when it is not on the table. */
+    select(objectId: string): boolean;
+    /** Runs a trial on the picked object (or on `objectId`): the room equips the tool, puts the player in front of it, aims and uses it. False when there is nothing to hit. */
+    trial(kind: TrialKind, objectId?: string): boolean;
+    /** Follow the table: a page laid, an object picked, a trial run. Returns the unsubscribe function. */
+    on(listener: (page: TestTablePage | null) => void): () => void;
+}
+/**
+ * How many items, from `start`, fit side by side along a table of `length` metres with `gap` between them (`width(i)` is the width of item i). At least one, so an item longer
+ * than the table still gets a page of its own. Pure.
+ */
+declare function fitRow(width: (index: number) => number, start: number, total: number, length: number, gap: number): number;
+/** The x of the centre of each item of a row laid side by side, centred on `centreX`, with `gap` between them. Pure. */
+declare function rowCentres(widths: readonly number[], centreX: number, gap: number): number[];
+/**
+ * Where the player's eye goes for a trial on an object whose box is `min`..`max` (world), and where it looks. The player comes from +z (the side of the room the table faces),
+ * so a melee blow lands on the front face. A blast is watched from `watch` metres. Pure.
+ */
+declare function trialView(tool: TrialTool, kind: TrialKind, min: Vec3, max: Vec3): {
+    eye: Vec3;
+    target: Vec3;
+};
+/** What the test table needs of the room. */
+interface TestTableContext {
+    /** The catalogue by group: the ids and names of the items of each one. */
+    readonly groups: () => ReadonlyMap<string, ReadonlyArray<{
+        readonly id: string;
+        readonly name: string;
+    }>>;
+    /** The top of the table in the world (null: the room has no such piece, or its top is broken). */
+    readonly top: () => {
+        readonly minX: number;
+        readonly maxX: number;
+        readonly minZ: number;
+        readonly maxZ: number;
+        readonly top: number;
+    } | null;
+    /** Width (x) and depth (z) of an item's model at rotation 0, metres. */
+    readonly measure: (itemId: string) => {
+        readonly w: number;
+        readonly d: number;
+    };
+    readonly spawn: (itemId: string, position: Vec3) => {
+        readonly objectId: string;
+    };
+    readonly clear: () => void;
+    readonly resetAll: () => void;
+    /** The world box of an object still in the room, else null. */
+    readonly box: (objectId: string) => {
+        readonly min: Vec3;
+        readonly max: Vec3;
+    } | null;
+    /** Puts the tool in hand (added to the hotbar) and waits for its draw. False for an id the arsenal does not have. */
+    readonly equip: (weapon: string) => boolean;
+    readonly look: (eye: Vec3, target: Vec3) => void;
+    readonly use: (hold: number) => void;
+    /** Sets off the explosive of `weapon` at `point`. False when the weapon throws or places no explosive. */
+    readonly blastAt: (weapon: string, point: Vec3) => boolean;
+    readonly log: (type: string, text: string, data: Record<string, unknown>) => void;
+    readonly translate: (key: string, vars?: Record<string, string | number>) => string;
+}
+/** The test table over a room (see `TestTable`). */
+declare function createTestTable(context: TestTableContext, options?: TestTableOptions): TestTable;
+
 /** Locales shipped with the package. Unknown locales fall back to `en`. */
 type TestRoomLocale = 'en' | 'pt-BR';
 interface RoomStrings {
@@ -289,7 +423,7 @@ interface TestRoomItem {
         container: ContainerSpec;
         part?: string;
         uses?: string[];
-        offset?: Vec3;
+        offset?: Vec3$1;
     };
     /** The item is also a weapon the player can equip from the catalogue (e.g. a crowbar, a knife, a pistol on the table). */
     weapon?: string;
@@ -313,7 +447,7 @@ interface SceneryObject {
     /** What the destruction world is given. */
     spec: DestructibleSpec;
     /** World position of the spec's origin. Required for a new id; for a default id it defaults to the object it replaces. */
-    position?: Vec3;
+    position?: Vec3$1;
     /** Turn about the vertical axis, radians (default 0). */
     rotationY?: number;
     /** Colour per part id, then per material id, for the default drawing (`buildFromSpec`). */
@@ -336,7 +470,7 @@ interface SceneryObject {
     /**
      * Where a water tap of the piece pours (a sink, a tub), in the spec's space: the room's tap (its stream and its HUD button) pours there, and the piece's own model is the tap. The first piece with a `spout` wins over the table tap.
      */
-    spout?: Vec3;
+    spout?: Vec3$1;
 }
 /** What the room asks when something thrown or set down needs a model: the tool in the hand, the explosive it carries (an id of the arsenal) and how it is used. */
 interface ProjectileQuery {
@@ -347,16 +481,16 @@ interface ProjectileQuery {
 /** A model for a projectile: the object, and the axis along its length (default +y, what the room's own primitives use; a rocket points that axis along its flight). */
 interface ProjectileModel {
     model: THREE_NS.Object3D;
-    axis?: Vec3;
+    axis?: Vec3$1;
 }
 /** The room's tap (a stream of water): how it is drawn and where the water leaves it. */
 interface SceneryTap {
     /** Draws the tap in its own space (the origin where it stands). */
     build: (THREE: ThreeNamespace) => THREE_NS.Object3D;
     /** Where the water leaves the spout, in the space of the model. */
-    spout: Vec3;
+    spout: Vec3$1;
     /** World position of the model's origin. Default: standing on the `table` top, with the spout over its right half (no table, no tap). */
-    position?: Vec3;
+    position?: Vec3$1;
     /** Turn about the vertical axis, radians (default 0). */
     rotationY?: number;
 }
@@ -416,7 +550,7 @@ interface TestRoomOptions {
     area?: string;
     /** Called for every destruction event (to log, play sounds, sync over LAN). Fluid events reach the log too. */
     onEvent?: (event: DestructionEvent) => void;
-    onSound?: (key: string, point: Vec3, volume: number) => void;
+    onSound?: (key: string, point: Vec3$1, volume: number) => void;
     /**
      * The sound engine of the room (@adatechnology/game-audio): the destruction renderer's sound keys play on it, and modules get it as `host.audio`.
      * Default: a new engine of the room's own (it makes no AudioContext until the first sound); `false` for a silent room.
@@ -459,6 +593,11 @@ interface TestRoomOptions {
         readonly state?: Readonly<Record<string, string>>;
         readonly onChange?: (moduleId: string, encoded: string) => void;
     };
+    /**
+     * The test table (`room.testTable`): a `scenery` piece with a `top` (default id `test_table`) the room lays a group of the catalogue on, a page at a time, to try each item with a
+     * shot, a punch, a knife, a flame or a blast. Without that piece the table lays nothing; `false` leaves the panel out too.
+     */
+    testTable?: TestTableOptions | false;
 }
 /** Counters the room measures itself. `fps` and `frame_ms` use the real frame time, so slow motion does not change them. */
 type RoomMetricId = 'fps' | 'frame_ms' | 'draw_calls' | 'triangles' | 'objects' | 'fragments' | 'particles' | 'decals'
@@ -500,8 +639,10 @@ interface TestRoom {
     readonly renderer: DestructionRenderer;
     readonly scene: THREE_NS.Scene;
     readonly camera: THREE_NS.PerspectiveCamera;
+    /** The test table: lays the catalogue on the `test_table` piece a page at a time and runs the trials (shot, punch, knife, fire, blast) on one item. */
+    readonly testTable: TestTable;
     /** Spawn a catalogue item at a world position (default in front of the player). */
-    spawn(itemId: string, position?: Vec3, rotationY?: number): SpawnedObject;
+    spawn(itemId: string, position?: Vec3$1, rotationY?: number): SpawnedObject;
     /** Remove every spawned object, fragment and particle. */
     clear(): void;
     /** Repair every spawned object in place. */
@@ -517,14 +658,14 @@ interface TestRoom {
     readonly tool: WeaponState;
     /** Play an item use on the held item (`drink`, `pour`...). Returns false when nothing is held or the use does not apply. */
     useItem(useId: string): boolean;
-    /** Use the current tool once from the camera (tests and scripted demos). `hold` seconds for continuous tools. */
+    /** Use the current tool once from the camera (tests and scripted demos), as the click does: bare hands punch (or let go of what they hold). `hold` seconds for continuous tools. */
     use(hold?: number): void;
     /** Grab what the camera looks at (or drop what is held). */
     grab(): boolean;
     /** Throw what is held at `speed` m/s (default 9). */
     throwHeld(speed?: number): boolean;
     /** Point the camera (scripted demos and tests). */
-    look(position: Vec3, target: Vec3): void;
+    look(position: Vec3$1, target: Vec3$1): void;
     /** Object and part the camera looks at, with its state, for the inspector. */
     inspect(): {
         objectId: string;
@@ -551,7 +692,7 @@ interface TestRoom {
     resume(): void;
     readonly paused: boolean;
     /** Walk the player in a straight line to the floor position `to` (x and z; y is ignored) over `seconds` of simulated time, during the next `step()` / frames. Colliders still block. 0 seconds moves at once. */
-    walk(to: Vec3, seconds: number): void;
+    walk(to: Vec3$1, seconds: number): void;
     /** 0.25x simulation speed. */
     setSlowMotion(on: boolean): void;
     /** Run the simulation 10x per frame (fire, melting and drying take a tenth of the time). */
@@ -563,6 +704,13 @@ interface TestRoom {
      * that brings an `area` is laid out by it; any other group is laid in rows (small items in front, fixed big ones behind). Unknown: nothing.
      */
     openArea(group: string): SpawnedObject[];
+    /** The loaded modules (`loadModule`): id, name, catalogue group and whether it lays an area of its own. */
+    modules(): Array<{
+        id: string;
+        name: string;
+        group?: string;
+        hasArea: boolean;
+    }>;
     /**
      * `openArea` with the loading indicator: shows "Opening <area>…", waits for it to be painted and then lays the area (an area with hundreds of items takes a second or more and would
      * otherwise look frozen). Resolves with the spawned objects. Use it where a person waits for the result (a page that opens an area on load); scenarios call `openArea`, which is synchronous.
@@ -623,8 +771,8 @@ interface TestRoom {
     };
     /** Draws the room from another camera (a debug view: the player's camera, the arms and the tool stay as they are) until it is given null. Look at the arms from the side or at a hand from 25 cm. */
     setDebugCamera(view: {
-        position: Vec3;
-        target: Vec3;
+        position: Vec3$1;
+        target: Vec3$1;
         fov?: number;
     } | null): void;
     /** What the avatar was last given. */
@@ -766,7 +914,7 @@ interface ScenarioReport {
 declare function createTestRoom(options: TestRoomOptions): TestRoom;
 
 /** Spec of the brick target wall: `cols` x `rows` brick panels, the bottom row anchored, mortar joints between neighbours. */
-declare function brickWallSpec(cols?: number, rows?: number, panel?: Vec3): DestructibleSpec;
+declare function brickWallSpec(cols?: number, rows?: number, panel?: Vec3$1): DestructibleSpec;
 
 /** Default look of each built-in destruction material (`0xRRGGBB`). */
 declare const MATERIAL_COLORS: Record<string, number>;
@@ -805,4 +953,4 @@ declare function encodeBenchState(controls: readonly BenchControl[], layers: rea
 /** Reads an encoded state as hostile input: unknown ids, NaN, options not offered and malformed pairs are dropped; numbers are clamped. */
 declare function decodeBenchState(encoded: string, controls: readonly ModuleControl[], layers: readonly ModuleLayer[]): Map<string, ControlValue>;
 
-export { type AnimationInfo, type BenchControl, type BenchHandle, type BenchLayer, type BuildFromSpecOptions, type CameraMode, DEFAULT_HAND_STANCES, DEFAULT_STRIKE_CLIPS, type HudState, type InspectInfo, type KickLeg, LOADING_CLASS, LOADING_CSS, type LoadingOptions, type LoadingState, type LogEntry, MATERIAL_COLORS, type ModuleReport, type NewEntry, type NewLogEntry, type ProjectileModel, type ProjectileQuery, type RoomAvatar, type RoomAvatarState, type RoomFirstPersonState, type RoomLoading, type RoomMetricId, type RoomStrings, type ScenarioContext, type ScenarioReport, type SceneryObject, type SceneryTap, type SpawnedObject, type TestRoom, type TestRoomItem, type TestRoomLocale, type TestRoomLog, type TestRoomOptions, type TestRoomScenario, type ThirdPersonOptions, type ThreeNamespace, type WritableLog, brickWallSpec, buildFromSpec, createLoading, createLog, createTestRoom, decodeBenchState, encodeBenchState, loadingMarkup, locales, nextPaint, resolveStrings };
+export { type AnimationInfo, type BenchControl, type BenchHandle, type BenchLayer, type BuildFromSpecOptions, type CameraMode, DEFAULT_HAND_STANCES, DEFAULT_STRIKE_CLIPS, DEFAULT_TRIALS, type HudState, type InspectInfo, type KickLeg, LOADING_CLASS, LOADING_CSS, type LoadingOptions, type LoadingState, type LogEntry, MATERIAL_COLORS, type ModuleReport, type NewEntry, type NewLogEntry, type ProjectileModel, type ProjectileQuery, type RoomAvatar, type RoomAvatarState, type RoomFirstPersonState, type RoomLoading, type RoomMetricId, type RoomStrings, type ScenarioContext, type ScenarioReport, type SceneryObject, type SceneryTap, type SpawnedObject, TRIAL_KINDS, type TestRoom, type TestRoomItem, type TestRoomLocale, type TestRoomLog, type TestRoomOptions, type TestRoomScenario, type TestTable, type TestTableContext, type TestTableObject, type TestTableOptions, type TestTablePage, type ThirdPersonOptions, type ThreeNamespace, type TrialKind, type TrialTool, type WritableLog, brickWallSpec, buildFromSpec, createLoading, createLog, createTestRoom, createTestTable, decodeBenchState, encodeBenchState, fitRow, loadingMarkup, locales, nextPaint, resolveStrings, rowCentres, trialView };