@adatechnology/game-test-room 0.20.0 → 0.21.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { LightBudget } from '@adatechnology/game-render-three';
 import * as THREE_NS from 'three';
 import { AudioEngine } from '@adatechnology/game-audio';
 import { Vec3 as Vec3$1, DestructionWorld, BlastOptions, DestructibleSpec, DestructionOptions, DestructionEvent } from '@adatechnology/game-destruction';
@@ -6,9 +7,12 @@ import { DoorUsePhase, FurniturePushPhase, FurniturePushBlock, FurniturePushRule
 import { BusySink, ItemSeat, Vec3, HandTargets, ModuleControl, ControlValue, ModuleLayer, EnvironmentBus, BusyTask, BusyOptions, TestableModule, ModuleItemSeal, DestructibleImpl, AnimationClipSpec, GroundLayout, BlastShoveOptions } from '@adatechnology/game-contracts';
 export { AnimationClipSpec, DestructibleImpl, ItemAnimationContract, ModuleScenario, TestableItem, TestableModule } from '@adatechnology/game-contracts';
 import { DestructionRenderer, SpecFromObjectOptions, Quality, FragmentLifeRule } from '@adatechnology/game-destruction-three';
-import { Arsenal, WeaponState, WeaponDef } from '@adatechnology/game-weapons';
+import { StorageLike, GraphicsController } from '@adatechnology/game-graphics';
+import { GraphicsScreen } from '@adatechnology/game-graphics/screen';
+import { Arsenal, WeaponState, TriggerResult, WeaponDef } from '@adatechnology/game-weapons';
 import { VfxWorld, SpriteKindDef } from '@adatechnology/game-vfx';
 import { Terrain, TerrainBudget } from '@adatechnology/game-terrain';
+import { SchedulerStats } from '@adatechnology/game-runtime';
 import { FilmBridge, FluidRenderer } from '@adatechnology/game-fluids-three';
 import { FluidWorld, ContainerSpec, LiquidDef, ItemUseDef, SurfaceSpec } from '@adatechnology/game-fluids';
 
@@ -101,6 +105,21 @@ interface LoadingOptions {
 declare const nextPaint: () => Promise<void>;
 declare function createLoading(options: LoadingOptions): RoomLoading;
 
+/** The room's graphics settings (`TestRoomOptions.graphics`). */
+interface RoomGraphicsOptions {
+    /** Where the player's choice is kept (default `localStorage`; null keeps it in memory). */
+    readonly storage?: StorageLike | null;
+    /** The key it is kept under (default `adatechnology.graphics`). */
+    readonly key?: string;
+    /** The short test of the first load, seconds (default 3; 0 skips it and starts the automatic mode at Alta). */
+    readonly calibrationSeconds?: number;
+    /**
+     * When the calibration of a first run starts: `idle` (default) after a few drawn frames with nothing on the loading indicator, or `manual`, where the page calls
+     * `room.graphics.calibrateIfNeeded()` once its content is in (a page that loads its content before it shows the room).
+     */
+    readonly calibrate?: 'idle' | 'manual';
+}
+
 /**
  * The room's seats: puts the player on a seat an item brings (`TestRoomItem.seats`, the shape of a `game-interactables` seat) and back on its feet at the seat's exit.
  * Seated, the keys do not walk and the view stays within reach of the seat's facing; a walk key or a jump gets up, and so does losing the seat (the item is gone).
@@ -452,6 +471,11 @@ interface RoomAvatar {
         leg?: 'left' | 'right';
         hand?: 'left' | 'right';
     }): number | null;
+    /**
+     * The foot the body put down since the last call (its walk cycle reached a heel strike), or null. The room asks after each `update` and sends the footfall to the
+     * modules (`HostEvent` `footfall`), so the step is heard on the frame the foot is seen on the ground. Without it the room counts strides by distance.
+     */
+    footfall?(): 'left' | 'right' | null;
     /**
      * Brings the body's hands to the tool in them (`HandTargets`, world space: the module's). The room calls it in both views every frame, after the modules have placed the tool and
      * before the render, with `view` (the eye's camera, and `contact` to keep the hands out of walls) in both views. An avatar without it keeps the hands where its own pose puts them.
@@ -677,6 +701,12 @@ interface TestRoomOptions {
     world?: DestructionWorld;
     worldOptions?: DestructionOptions;
     quality?: Quality;
+    /**
+     * The player's graphics settings (`game-graphics`): a Gráficos button opens the screen (presets Automático, Baixa, Média, Alta, Ultra and each option), the
+     * choice is kept in the browser, the first load runs a short calibration on the loading indicator and the automatic mode moves what is left on auto. Only on a
+     * renderer the room makes. Default off (the fixed look of `quality`).
+     */
+    graphics?: boolean | RoomGraphicsOptions;
     /** What the floor is made of until an area lays its own (`TestableModule.ground`). Default a concrete slab. */
     ground?: GroundLayout;
     /** Limits of the floor's marks, thrown pieces and redraws per frame. */
@@ -754,6 +784,11 @@ interface TestRoomOptions {
     handStances?: Readonly<Record<string, string>>;
     /** The over-the-shoulder view of the `third` mode: distance, shoulder, height, wall probes. Defaults are the team game's. */
     thirdPerson?: ThirdPersonOptions;
+    /**
+     * Milliseconds of every frame the deferred queues (sound voices, destruction events, breach paint, vehicle crease) share. Default 8, the biggest budget the loose
+     * queues had; 4 is the library default of `@adatechnology/game-runtime`, for a room whose `maxFramesWaiting` stays under 15 (see `frameStats()`).
+     */
+    frameBudgetMs?: number;
     /** Room counters the bench panel shows and `TestRoom.metrics()` returns (default all); `false` for none. */
     metrics?: readonly RoomMetricId[] | false;
     /**
@@ -762,12 +797,21 @@ interface TestRoomOptions {
      * sprites (dust, smoke, chips, sparks...) by kind, e.g. `{ dust: { life: [10, 30] } }` (seconds, min and max). Loose pieces (what breaks off whole: a door, a leg,
      * a slab) stay as part of the map, with collision.
      */
+    /** Slots of the room's light budget (default 16 point and 4 spot). Each light is paid per pixel, lit or not, so a weak GPU gets fewer; changing them recompiles every lit program, so they are fixed at load. */
+    lightSizes?: {
+        readonly point?: number;
+        readonly spot?: number;
+    };
+    /** Drawn frames the GPU may be behind before the room holds a draw back (`createFramePacer`, default 2). */
+    framesInFlight?: number;
     debris?: {
         fragmentLife?: number | FragmentLifeRule;
         maxFragments?: number;
         particles?: Readonly<Record<string, Partial<SpriteKindDef> | null>>;
         /** Milliseconds of destruction events the renderer applies per frame; the rest wait for the next frames (default 8). `Infinity` applies every event in the frame it happens, which a test comparing counts needs. */
         eventBudgetMs?: number;
+        /** The most loose bodies (ejected casings, dropped magazines) modules may keep alive at once, lent as `ModuleHost.particleLimit` (default 900). */
+        particleLimit?: number;
     };
     /** Blast options every explosion of the room starts with (`shelter`, `fragmentHits`, `confinement`; default all off). The HUD toggles them and `TestRoom.setBlast` changes them. */
     blast?: BlastOptions;
@@ -794,7 +838,9 @@ interface TestRoomOptions {
 /** 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'
 /** Of the last blast, once the room's blast options are on: the share that reached the most sheltered target (%), the pressure multiplier, the fragment hits. */
- | 'blast_shelter' | 'blast_confinement' | 'blast_fragments';
+ | 'blast_shelter' | 'blast_confinement' | 'blast_fragments'
+/** Memory: geometries and textures alive on the GPU (three's `renderer.info.memory`), the JS heap in MB where the browser tells it. */
+ | 'geometries' | 'textures' | 'heap_mb';
 /** A module control as the room holds it: the declaration with the module's patches applied, and its value (none for an action). */
 type BenchControl = ModuleControl & {
     readonly disabled: boolean;
@@ -831,6 +877,10 @@ interface TestRoom {
     readonly renderer: DestructionRenderer;
     readonly scene: THREE_NS.Scene;
     readonly camera: THREE_NS.PerspectiveCamera;
+    /** The room's light budget (what `host.lights` lends): the one owner of its point and spot lights. */
+    readonly lights?: LightBudget;
+    /** The WebGL renderer the room draws with, for tools that read what the GPU got (the `light_slots` phase of `perf.mjs` reads the uniforms of a lit material). */
+    readonly webgl?: THREE_NS.WebGLRenderer;
     /** 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). */
@@ -850,8 +900,12 @@ 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), as the click does: bare hands punch (or let go of what they hold). `hold` seconds for continuous tools. */
-    use(hold?: number): void;
+    /**
+     * 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.
+     * Answers what the trigger said: `ok` when the tool did something; `drawing` when the draw is not over for the trigger yet (the frame that ends the draw is the trigger's
+     * too, so `tool.phase` turns null one frame before the first pull can go: a script waits a frame and pulls again), `cooldown`, `empty`, `reloading`... otherwise.
+     */
+    use(hold?: number): UseStatus;
     /** Where the player's feet are. */
     readonly playerPosition: Vec3$1;
     /** Grab what the camera looks at (or drop what is held). */
@@ -888,11 +942,12 @@ interface TestRoom {
     /** Everything the inspector panel shows for the aimed part (state, joints and the tools that undo them), or null. */
     inspectInfo(): InspectInfo | null;
     spawned(): SpawnedObject[];
-    /** Advance one frame (only needed when the host owns the loop). */
+    /** Advance one frame, and throw what a system threw in it. The host that owns the loop must call it every frame: the deferred queues lent to the room's budget (sound voices, destruction events) drain only inside a frame. */
     update(dt: number): void;
     /** Advance frames until the tool in hand has no phase left (the draw `setTool` plays, a reload, a cycle) or `maxSeconds` pass; plus one frame so the next pull is not inside the phase; returns the seconds waited. */
     waitUntilReady(maxSeconds?: number): number;
-    on(type: 'spawn' | 'tool' | 'grab' | 'throw' | 'event' | 'camera', fn: (data: unknown) => void): () => void;
+    /** `footfall`: a foot of the player's body touched the ground (`{ foot, gait, time }`), the moment its footstep sounds. */
+    on(type: 'spawn' | 'tool' | 'grab' | 'throw' | 'event' | 'camera' | 'footfall', fn: (data: unknown) => void): () => void;
     /** Tilt the held item by `rad` radians around its own x axis (hold Z in the room). Pouring and spilling follow from the tilt. */
     tilt(rad: number): void;
     /** Open or close the tap over the table (default: toggle). Returns whether it is open. */
@@ -939,6 +994,10 @@ interface TestRoom {
     openAreaAsync(group: string): Promise<SpawnedObject[]>;
     /** The loading indicator of the room: `begin`, `busy`, `state`, `on` (see `RoomLoading`); modules get it as `ModuleHost.loading`. */
     readonly loading: RoomLoading;
+    /** The player's graphics settings (`options.graphics`): presets, options, the automatic mode, the calibration; null without them. */
+    readonly graphics: GraphicsController | null;
+    /** The graphics screen (open, close, toggle); null without settings or without the panels. */
+    readonly graphicsScreen: GraphicsScreen | null;
     /** `loading.busy`: shows the indicator, waits for it to be painted, runs `work` and takes it down. The way to run a slow, synchronous job. */
     busy<T>(label: string, work: (task: BusyTask) => T | Promise<T>, options?: BusyOptions): Promise<T>;
     /** The scenarios the panel offers: the built-in `SCENARIOS` in the room locale plus `TestRoomOptions.scenarios`. */
@@ -1024,6 +1083,8 @@ interface TestRoom {
         room: Partial<Record<RoomMetricId, number>>;
         module: Record<string, number | string>;
     };
+    /** What the frame scheduler measured: ms per phase of the last frame, substeps, and per deferred queue the work waiting, run, forced and the most frames anything waited. */
+    frameStats?(): SchedulerStats;
     dispose(): void;
 }
 /** What `TestRoom.loadModule` did. */
@@ -1141,6 +1202,9 @@ interface ScenarioReport {
     }>;
 }
 
+/** What the trigger answered to `TestRoom.use`: the status of the weapons package's trigger. */
+type UseStatus = TriggerResult['status'];
+
 /**
  * Create the test room. See `TestRoomOptions`. The room owns a renderer, scene and camera unless you pass them; with your own renderer you call
  * `room.update(dt)` every frame and render yourself.
@@ -1187,4 +1251,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, 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 PunchHand, type RoomAvatar, type RoomAvatarState, type RoomDoorEvent, type RoomDoorState, type RoomFirstPersonState, type RoomLoading, type RoomMetricId, type RoomPushEvent, type RoomPushState, type RoomReachView, type RoomSeat, type RoomStrings, type ScenarioContext, type ScenarioReport, type SceneryObject, type SceneryTap, type SpawnedObject, type StrikeComboOption, 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 };
+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 PunchHand, type RoomAvatar, type RoomAvatarState, type RoomDoorEvent, type RoomDoorState, type RoomFirstPersonState, type RoomGraphicsOptions, type RoomLoading, type RoomMetricId, type RoomPushEvent, type RoomPushState, type RoomReachView, type RoomSeat, type RoomStrings, type ScenarioContext, type ScenarioReport, type SceneryObject, type SceneryTap, type SpawnedObject, type StrikeComboOption, 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 UseStatus, type WritableLog, brickWallSpec, buildFromSpec, createLoading, createLog, createTestRoom, createTestTable, decodeBenchState, encodeBenchState, fitRow, loadingMarkup, locales, nextPaint, resolveStrings, rowCentres, trialView };