@adatechnology/game-test-room 0.6.1 → 0.8.0

package/README.md

@@ -71,10 +71,16 @@ The items join the catalogue under the module's group and its scenarios become b
 
 ## Module bench
 
+The room makes **one** effects world (`game-vfx` and its `game-vfx-three` layer) and steps it once per frame, after the destruction renderer. The destruction
+renderer draws into it, every module gets it as `host.effects` (an `EffectSink`: `play({ effect: 'm67', point })`, `catalog()`), grenades and rockets play the
+profile of their explosive (`explosive` is on the `explosion` host event), the camera shakes and the screen flashes through an overlay in the container, and the
+`particles` metric counts its pools. Without a DOM nothing is drawn on the screen. `TestRoom.applyCamera()` wraps a host's own `render`; the room's loop does it itself.
+`craters: true` swaps the floor for a deformable patch that big explosions dig into.
+
 A module that declares `controls`, `layers` or `metrics` (see `@adatechnology/game-contracts`) gets a bench: `loadModule` checks it with
 `checkBench` (a `✓ ... bench ok` / `✗ ... bench broken` line), lends `host.bench` to `attach`, then sends one change per control and layer. The
 panel between the animations and the tests shows the active module (the one of the last `openArea`; else the first loaded with a bench, a later module never takes the panel from the one on screen): a
-range per number, a checkbox per boolean, buttons (up to four options) or a select per choice, a button per action, the layers, and the
+range per number, a checkbox per boolean, buttons (up to four options, no groups) or a select per choice (options with a `group` sit under `optgroup`s), a button per action, the layers, and the
 module counters at 4 Hz with a bar when they have a budget (`warn` from 80 %, `bad` past it). A compact line on top shows the room counters
 (`fps`, `frame_ms`, `draw_calls`, `triangles`, `objects`, `fragments`, `particles`, `decals`); `fps` uses the real frame time, so slow motion
 does not change it.
@@ -85,6 +91,9 @@ room.bench()?.set('size', 2) // clamped and snapped; false for an unknown id, a
 room.metrics() // { room: { fps, draw_calls, ... }, module: { particles: 120 } }
 ```
 
+A module can put a **sheet** on the panel (`host.bench.sheet(sheet)`, `BenchSheet` of the contracts): a card with a kicker, a title, a text, facts, steps, colour swatches and a timeline of named segments whose playhead follows one of the module's numeric metrics.
+The room also runs the film of the liquids that have one (`createFilmManager` of `game-fluids-three`): a leak of fuel, oil or blood drips into grids on the floor near the camera.
+
 The state is `id=value;id=value` (`encodeBenchState` / `decodeBenchState`); decoding treats it as hostile input. `bench.state` is keyed by
 module id, so two modules can share a control id; a module loaded again keeps its live values. The room never touches
 `location`: the example page keeps it in `?bench.<moduleId>=`. `fps` and `frame_ms` use the real frame time, even past the 50 ms the simulation is clamped to. Loading a module again detaches the previous `attach` first. Q now reports the new fire

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import * as THREE_NS from 'three';
+import { AudioEngine } from '@adatechnology/game-audio';
 import { DestructibleSpec, Vec3, DestructionWorld, DestructionOptions, DestructionEvent, MaterialDef } from '@adatechnology/game-destruction';
 export { DestructionEvent, Vec3 } from '@adatechnology/game-destruction';
 import { SpecFromObjectOptions, DestructionRenderer, Quality } from '@adatechnology/game-destruction-three';
 import { Arsenal, WeaponState, WeaponDef } from '@adatechnology/game-weapons';
 import { FluidRenderer } from '@adatechnology/game-fluids-three';
 import { ContainerSpec, FluidWorld, LiquidDef, ItemUseDef, SurfaceSpec } from '@adatechnology/game-fluids';
-import { ModuleControl, ControlValue, ModuleLayer, DestructibleImpl, AnimationClipSpec, TestableModule } from '@adatechnology/game-contracts';
+import { ModuleControl, ControlValue, ModuleLayer, DestructibleImpl, AnimationClipSpec, EnvironmentBus, TestableModule } from '@adatechnology/game-contracts';
 export { AnimationClipSpec, DestructibleImpl, ItemAnimationContract, ModuleScenario, TestableItem, TestableModule } from '@adatechnology/game-contracts';
 
 type NewEntry = NewLogEntry;
@@ -181,6 +182,8 @@ interface TestRoomOptions {
     world?: DestructionWorld;
     worldOptions?: DestructionOptions;
     quality?: Quality;
+    /** Replaces the arena floor with a deformable patch (60 m, 33 cm cells) that the craters of big explosions dig into. Default false. */
+    craters?: boolean;
     /** Heaviest object the player can carry (default 60 kg). */
     maxCarryKg?: number;
     /** Arena half size in metres (default 14). */
@@ -192,6 +195,13 @@ interface TestRoomOptions {
     /** 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;
+    /**
+     * 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.
+     */
+    audio?: AudioEngine | false;
+    /** The environment store modules get as `host.environment` (the weather module writes it, the others read it). Default: a new one with a calm dry day. */
+    environment?: EnvironmentBus;
     /** Show the built-in HUD and panels (default true). */
     ui?: boolean;
     /** Room counters the bench panel shows and `TestRoom.metrics()` returns (default all); `false` for none. */
@@ -236,6 +246,10 @@ interface SpawnedObject {
     movable: boolean;
 }
 interface TestRoom {
+    /** The room's sound engine, or `null` in a silent room. */
+    readonly audio: AudioEngine | null;
+    /** The environment store lent to modules as `host.environment`. */
+    readonly environment: EnvironmentBus;
     readonly world: DestructionWorld;
     readonly renderer: DestructionRenderer;
     readonly scene: THREE_NS.Scene;
@@ -320,6 +334,11 @@ interface TestRoom {
     /** The bench of a loaded module (default the active one: the module of the last `openArea`, else the last loaded with a bench), or null. */
     bench(moduleId?: string): BenchHandle | null;
     /** Room counters and the active module's metrics, read now. */
+    /**
+     * Shakes the camera for the render that follows, by the shake of the effects world, and answers the function that puts it back. The room's own loop
+     * wraps its render in it; a host that renders by itself calls it around its own `render`.
+     */
+    applyCamera(): () => void;
     metrics(): {
         room: Partial<Record<RoomMetricId, number>>;
         module: Record<string, number | string>;