@adatechnology/game-test-room 0.2.0 → 0.3.0

package/README.md

@@ -68,6 +68,27 @@ const report = room.loadModule(RENTAL_CARS) // { module, items, scenarios, ok, p
 
 The items join the catalogue under the module's group and its scenarios become buttons. The contract checks run at once and write one line per result to the log: `checkDestructible` for every item with an `impl`, `checkAnimation` for every clip (`✓ Rental car: destructible contract ok (4 parts...)` or `✗ ...: <problem>`). The animations panel lists the clips of the aimed or held item; `room.playAnimation(clipId)` plays one (poses are offsets from the rest pose, events go to the log and `sound` events to `onSound`). The example (`examples/test-room`) loads a `DEMO_MODULE` rental car that owns its damage rule, its door `open` clip and a wheel that comes off with a wrench.
 
+## Module bench
+
+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
+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.
+
+```ts
+const room = createTestRoom({ ..., metrics: ['fps', 'draw_calls'], bench: { state: { lab: params.get('bench.lab') ?? '' }, onChange: (moduleId, encoded) => keepInUrl(moduleId, encoded) } })
+room.bench()?.set('size', 2) // clamped and snapped; false for an unknown id, a wrong type or an option not offered
+room.metrics() // { room: { fps, draw_calls, ... }, module: { particles: 120 } }
+```
+
+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
+mode (`mode` event) and `shot` events carry `rounds` and `mode`.
+
 ## Controls
 
 | Input | Action |
@@ -110,6 +131,9 @@ Uma sala de testes em primeira pessoa para three.js. Você passa o seu catálogo
 derrama líquidos, e lê o que aconteceu em linguagem simples no registro de comportamento (também exportável em JSON, NDJSON ou texto). Os cenários
 automáticos conferem o resultado e gravam aprovado/reprovado no mesmo registro. Use `locale: 'pt-BR'` para textos em português.
 
+Um módulo que declara controles, camadas ou contadores ganha um painel de bancada genérico; o estado vai para a URL do exemplo (`?bench.<idDoMódulo>=`) e
+`room.bench()` / `room.metrics()` dirigem e leem a bancada por script.
+
 ## Known limitations
 
 The quality select does not recreate the destruction renderer; it only changes the room's own settings. Unit tests use an injected stub renderer (no WebGL).

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import { SpecFromObjectOptions, DestructionRenderer, Quality } from '@adatechnol
 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 { DestructibleImpl, AnimationClipSpec, TestableModule } from '@adatechnology/game-contracts';
+import { ModuleControl, ControlValue, ModuleLayer, DestructibleImpl, AnimationClipSpec, TestableModule } from '@adatechnology/game-contracts';
 export { AnimationClipSpec, DestructibleImpl, ItemAnimationContract, ModuleScenario, TestableItem, TestableModule } from '@adatechnology/game-contracts';
 
 type NewEntry = NewLogEntry;
@@ -186,6 +186,40 @@ interface TestRoomOptions {
     onSound?: (key: string, point: Vec3, volume: number) => void;
     /** 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. */
+    metrics?: readonly RoomMetricId[] | false;
+    /**
+     * Module bench state. `state` maps a module id to its encoded state, restored when that module is first loaded (a module reloaded
+     * keeps its live state instead) before its first changes are sent; ids are per module, so two modules may share a control id.
+     * `onChange` gets the encoded state of a module whenever it changes (a page keeps it in its URL). The room never touches `location`.
+     */
+    bench?: {
+        readonly state?: Readonly<Record<string, string>>;
+        readonly onChange?: (moduleId: string, encoded: string) => void;
+    };
+}
+/** 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';
+/** 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;
+    readonly value?: ControlValue;
+};
+type BenchLayer = ModuleLayer & {
+    readonly on: boolean;
+};
+/** The bench of a loaded module, driven from outside the panel (tests, scripts, a page that keeps the state in its URL). */
+interface BenchHandle {
+    controls(): BenchControl[];
+    layers(): BenchLayer[];
+    value(id: string): ControlValue | undefined;
+    layer(id: string): boolean;
+    /** Numbers are clamped and snapped to the step. False for an unknown id, a wrong type, an option not offered or a disabled control. */
+    set(id: string, value: ControlValue): boolean;
+    setLayer(id: string, on: boolean): boolean;
+    act(id: string): boolean;
+    /** `id=value;id=value`, the format `TestRoomOptions.bench.state[moduleId]` reads back. */
+    encode(): string;
 }
 interface SpawnedObject {
     objectId: string;
@@ -273,6 +307,13 @@ interface TestRoom {
      * offsets from the rest pose, interpolated linearly; the item keeps the last pose. Events are logged (and `sound` events reach `onSound`).
      */
     playAnimation(clipId: string, objectId?: string): boolean;
+    /** 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. */
+    metrics(): {
+        room: Partial<Record<RoomMetricId, number>>;
+        module: Record<string, number | string>;
+    };
     dispose(): void;
 }
 /** What `TestRoom.loadModule` did. */
@@ -437,4 +478,9 @@ interface BuildFromSpecOptions {
  */
 declare function buildFromSpec(THREE: typeof THREE_NS, spec: DestructibleSpec, options?: BuildFromSpecOptions): THREE_NS.Group;
 
-export { type AnimationInfo, type BuildFromSpecOptions, DEMO_ITEMS, DEMO_MATERIALS, type HudState, type InspectInfo, type LogEntry, MATERIAL_COLORS, type ModuleReport, type NewEntry, type NewLogEntry, type RoomStrings, SCENARIOS, type ScenarioContext, type ScenarioReport, type SpawnedObject, type TestRoom, type TestRoomItem, type TestRoomLocale, type TestRoomLog, type TestRoomOptions, type TestRoomScenario, type ThreeNamespace, type WritableLog, brickWallSpec, buildFromSpec, createLog, createTestRoom, demoItems, locales, makeScenarios, resolveStrings, scenariosFor };
+/** `id=value;id=value`, values with `encodeURIComponent`, booleans and layers as `1` / `0`. */
+declare function encodeBenchState(controls: readonly BenchControl[], layers: readonly BenchLayer[]): string;
+/** 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, DEMO_ITEMS, DEMO_MATERIALS, type HudState, type InspectInfo, type LogEntry, MATERIAL_COLORS, type ModuleReport, type NewEntry, type NewLogEntry, type RoomMetricId, type RoomStrings, SCENARIOS, type ScenarioContext, type ScenarioReport, type SpawnedObject, type TestRoom, type TestRoomItem, type TestRoomLocale, type TestRoomLog, type TestRoomOptions, type TestRoomScenario, type ThreeNamespace, type WritableLog, brickWallSpec, buildFromSpec, createLog, createTestRoom, decodeBenchState, demoItems, encodeBenchState, locales, makeScenarios, resolveStrings, scenariosFor };