@adatechnology/game-test-room 0.11.0 → 0.12.0

package/README.md

@@ -18,13 +18,13 @@ pnpm add @adatechnology/game-test-room three
 
 ```ts
 import * as THREE from 'three'
-import { createTestRoom, demoItems } from '@adatechnology/game-test-room'
+import { createTestRoom } from '@adatechnology/game-test-room'
 
 const room = createTestRoom({
   THREE,
   container: document.getElementById('app')!,
   locale: 'en', // 'en' or 'pt-BR'
-  catalog: demoItems('en'),
+  catalog: [], // the room ships no items: load modules (`room.loadModule`) or pass your own
 })
 room.runScenarios().then((report) => console.log(report.passed, report.failed))
 console.log(room.log.toNDJSON())
@@ -39,7 +39,6 @@ const room = createTestRoom({
   THREE,
   container,
   catalog: [
-    ...demoItems('en'),
     { id: 'my_crate', name: 'My crate', group: 'Mine', build: (T) => buildMyCrate(T), specOptions: { /* material per mesh name */ } },
   ],
   scenarios: [
@@ -56,8 +55,48 @@ const room = createTestRoom({
 })
 ```
 
-`DEMO_MATERIALS` is now empty (kept for compatibility: the demo items use only core materials). `buildFromSpec` turns a `DestructibleSpec` into meshes,
-and `brickWallSpec` / `DEMO_ITEMS` / `SCENARIOS` are exported to reuse or extend.
+`buildFromSpec` turns a `DestructibleSpec` into meshes, and `brickWallSpec` (the arena's target wall) is exported to reuse.
+
+## Breaking: the demo catalogue and the built-in scenarios are gone
+
+The room used to ship 19 procedural box/cylinder items (`demoItems`, `DEMO_ITEMS`, `DEMO_MATERIALS`: chair, sofa, crate, jerrycan...) and its built-in scenarios (`SCENARIOS`, `scenariosFor`, `makeScenarios`) built on them. They were not the game's items, so they were removed: the room now holds only the generic contracts and the arena. Migrate:
+
+- `catalog: demoItems(locale)` becomes `catalog: []`, and the items come from the SDK modules loaded with `room.loadModule` (weapons, items, household furniture, vehicles, characters...). `examples/interactables-test-area` loads all of them; `examples/test-room` opens with that set.
+- `room.scenarios` is empty until the host passes `scenarios` or a module brings its own. The destruction checks the removed ones made (steel sheet, glass, concrete, fire, collapse) are covered by the tests of `game-destruction`, `game-fluids` and the module scenarios of the content packages.
+- A test that needs a throwaway item should define it in its own fixture (see `tests/fixtures/demo-items.ts`, not exported).
+
+## Scenery
+
+The arena holds three destructible pieces by default, hand-made from boxes: `target_wall` (a brick wall of 48 panels at z = -11), `table` (with the water tap on a post beside it, at x = 3.5) and `shelf` (x = -3.5). `scenery` is a registry keyed by arena object id, so a host can use its own pieces without touching the room:
+
+| `scenery[id]` | Effect |
+|---|---|
+| a key of a default (`target_wall`, `table`, `shelf`) | replaces that piece; `position` defaults to the replaced one's |
+| `null` | removes the piece (no table: no tap either) |
+| a new key | adds a piece; `position` is required |
+
+```ts
+createTestRoom({ ..., scenery: {
+  target_wall: { spec: wallSpec, position: [0, 0, -11], build: (THREE) => drawWall(THREE) },
+  table: { spec: tableSpec, build: drawTable, top: { part: 'wood_0', y: 0.78 } },
+  crate: { spec: crateSpec, position: [0, 0, -4], rotationY: 0.4, label: 'Crate' },
+  shelf: null,
+} })
+```
+
+A `SceneryObject` is `{ spec, position?, rotationY?, colors?, build?, label?, top? }`:
+
+- `spec`: the `DestructibleSpec` the world is given. The player collider is the footprint of its parts (what lies lower than 10 cm is walked over); the `target_wall` collider also closes the arena behind the wall.
+- `build(THREE)`: draws the piece as a group whose meshes are named by part id (`userData.destructionPart` too), like `buildFromSpec` does. Without it the room draws one plain mesh per part with `buildFromSpec` and `colors`.
+- `top: { part, y }`: loose things rest on that part's footprint at height `y` while the part stands (`room.groundAt`), and liquids pool on it. The tap stands beside the `table` top.
+- `spout`: where a water tap of the piece pours (a sink, a tub), in the spec's space. The room's tap pours from the first piece that has one, so the piece's own model is the tap; without one the tap stands on the `table` top (see `tap` below).
+- `label`: the name in the inspector and the log (the defaults are translated).
+
+`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.
+
+## 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)`.
 
 ## Loading a module
 
@@ -67,7 +106,17 @@ A game module hands the room a `TestableModule` from `@adatechnology/game-contra
 const report = room.loadModule(RENTAL_CARS) // { module, items, scenarios, ok, problems }
 ```
 
-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.
+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 the SDK's content modules (the same set as `examples/interactables-test-area`).
+
+## Loading indicator
+
+Anything slow shows a spinner or a bar with a line of text over the room, so the page never looks frozen. `room.loading` (`RoomLoading`) is the component and `room.busy(label, work)` its shortcut: `busy` shows the indicator, waits for it to be painted (a synchronous job cannot paint it itself), runs `work` and takes it down, even when `work` throws. For a job in steps use `const task = room.loading.begin(label, { total })`, `task.step(text, done)`, `await task.paint()` and `task.end()`; tasks nest and the last one to end hides the card. `await room.loading.idle()` resolves when no task is open: the way for a scenario or a test to wait for a rebuild that runs behind the indicator. `room.openAreaAsync(area)` is `openArea` behind it. The text follows the room's `locale`, a room with `ui: false` draws nothing and tells the state through `room.loading.on(...)`.
+
+A module declares what is slow and the room does the rest: `ModuleControl.slow` (an action or a control that takes a third of a second or more) and `TestableItem.slow` (a vehicle) make the room's own panel and catalogue run the press or the spawn behind the indicator (`bench().act/set` and `spawn` stay synchronous for scenarios). A module with a job of its own (a house rebuilt after a seed change) calls `host.loading.busy(...)`. `LOADING_CSS` and `loadingMarkup` are the same card as static HTML, for a page that must show it before its scripts run (the default test room's first frame does).
+
+## Blasts shove what is around them
+
+An `explosion` moves the loose items, the heavy furniture that is not fixed, and the bodies of the modules that answer it. One rule, `blastShove` of `@adatechnology/game-contracts`: `min(maxSpeed, sqrt(2 * energy * coupling / mass)) * (1 - d / r)^2` away from the centre with some lift, and nothing under `minSpeed`. The room's `blastShove` option sets the numbers (`coupling` 0.02, `maxSpeed` 20 m/s, `lift` 0.3, `minSpeed` 0.3, `falloffPower` 2) for the renderer's pieces and, as `host.blastShove`, for modules such as the characters area, which slide and knock their people down.
 
 ## Module bench
 
@@ -116,11 +165,33 @@ when a body (the player, an object of the room) crosses it; whatever was already
 | E | grab / drop |
 | R | rotate the held item |
 | Right button or G | throw |
-| F | use a fluid item (drink); Z tilt; C fill from the tap; V pour (holding a fluid item) or kick (otherwise, with the `kick` tool whatever is selected) |
+| F | use a fluid item (drink); Z tilt; C fill from the tap; V pour (holding a fluid item); otherwise V toggles 1st/3rd person when a body is set (`setAvatar`), and kicks when there is none (Shift+V kicks with a body too; the `kick` tool whatever is selected) |
 | Tab | show / hide the panels |
 
 Panels: catalogue tabs (spawn, Clear, Reset all), slow motion 0.25x, time x10, quality select, inspector (material, state, hp, temperature, char, marks, joints, load and stress) and the behaviour log with filters.
 
+## The player's body and the third-person camera
+
+The room is a bare first-person camera until you give it a body. `room.setAvatar(avatar | null)` takes anything shaped like `RoomAvatar` (the room imports no character code):
+
+```ts
+interface RoomAvatar {
+  root: Object3D
+  update(dt: number, state: { speed: number; running: boolean; crouch: boolean; down: boolean; armed: boolean; pitch: number }): void
+  hand?(side: 'R' | 'L'): Object3D
+  firstPerson?: { root: Object3D; update(dt: number, state: { camera: Object3D; targets: HandTargets | null; stance: string; speed: number; running: boolean; crouch: boolean }): void }
+  strike?(clipId: string): number | null
+}
+```
+
+Every frame the room puts `root` at the player's feet turned to where the player looks (the body's front is +z, as the catalogue items'; `rotation.y` is the yaw plus pi) and calls `update` with the ground speed of the player's movement, Shift, `armed` (a firearm is the tool in hand) and the camera `pitch` (radians, positive looking up). `crouch` and `down` are not known to the room: a player module sets them with `room.setAvatarState({ crouch, down })` (`avatarState()` reads them back). `@adatechnology/game-characters-three` has such a body: `toRoomAvatar(createPlayerAvatar(THREE))`.
+
+**First-person arms and strikes.** An avatar may carry `firstPerson` (arms drawn in the camera's space; the room shows them only in the first person, updates them every frame after the modules' frame hooks and hands them where the tool in the hands asks the hands to be) and `strike(clipId)`. The hand targets come from the module that places the tool (`host.setHandTargets(source)`, `HandTargets` of `@adatechnology/game-contracts`: world-space poses of the right and left hand plus the grip closure and the size of the hands), else from the carried item, else null; the stance is `hold` when there are targets, else `handStances[toolId]` (default `{ fists: 'fists' }`) or `relaxed`. A melee strike (`fists`, `shove`, Shift+V kick) no longer lands at the click: the room calls `avatar.strike(strikeClips[toolId])` (default `{ fists: 'punch_right', shove: 'shove_two_hands', kick: 'front_kick' }`), which plays the clip on the arms and on the body and answers the seconds to its impact, writes a `strike` line to the log, and calls the existing `meleeUse` at that second with the aim read again. A tool without a clip, or an avatar that answers null, keeps the instant blow; a strike pending blocks the same tool. `toRoomAvatar(createPlayerAvatar(THREE))` already gives all of it (`firstPerson: false` for no arms).
+
+`room.setCameraMode('first' | 'third')` (option `cameraMode`, property `cameraMode`, event `room.on('camera', fn)`; every change is a `camera` action in the log). V toggles it when a body is set. In `first` the body is hidden; in `third` it is shown, the camera stands over the shoulder, and a carried item rides `avatar.hand('R')` instead of the camera frame. Option `thirdPerson` changes the view; the defaults are the team game's shoulder camera (`zombiada-modo-livre.html`, `cameraUpdate`, line 76546): `back` 3.8 m, `side` 0.9 m to the right, `up` 1.95 m (`crouchUp` 1.4 m), `lift` 0.1 m, three probe rays (`probes` 0 and +-0.2 m) that pull the camera in `margin` 0.3 m short of a wall (never closer than `minDistance` 0.2 m) and let it out at `recover` 4 per second.
+
+The simulation always sees the eye: tools, grabs, scripted walks and the listener work as in first person. Only the render moves the camera (`applyCamera()` does it, a host that renders by itself calls it around its `render`). A shot or grab leaves the eye toward the point the camera ray hits, so the crosshair stays true.
+
 ## Log format
 
 One JSON object per line (`log.toNDJSON()`, "Baixar NDJSON"):
@@ -150,6 +221,8 @@ automáticos conferem o resultado e gravam aprovado/reprovado no mesmo registro.
 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.
 
+Corpo do jogador: `room.setAvatar(corpo)` põe um corpo (qualquer objeto no formato `RoomAvatar`) nos pés do jogador; `room.setCameraMode('first' | 'third')` e a tecla V alternam entre 1ª e 3ª pessoa (câmera sobre o ombro com os números do jogo da equipe, puxada para perto de paredes). `room.setAvatarState({ crouch, down })` deixa um módulo de jogador agachar e derrubar o corpo. Com corpo, V alterna a câmera e Shift+V chuta. Em primeira pessoa o corpo pode trazer braços e mãos (`avatar.firstPerson`) que seguram a arma onde o módulo manda (`host.setHandTargets`): mão direita no punho, esquerda no guarda-mão, as duas na pistola, esquerda ao carregador na recarga; sem nada na mão ficam relaxadas, e `fists` levanta os punhos. Soco, empurrão e chute tocam o clipe (`avatar.strike`, opção `strikeClips`) e o efeito só acontece no instante do impacto, não no clique; um golpe pendente bloqueia a mesma ferramenta.
+
 ## 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

@@ -1,14 +1,54 @@
 import * as THREE_NS from 'three';
 import { AudioEngine } from '@adatechnology/game-audio';
-import { DestructibleSpec, Vec3, DestructionWorld, BlastOptions, DestructionOptions, DestructionEvent, MaterialDef } from '@adatechnology/game-destruction';
+import { Vec3, DestructionWorld, BlastOptions, DestructibleSpec, DestructionOptions, DestructionEvent } from '@adatechnology/game-destruction';
 export { DestructionEvent, Vec3 } from '@adatechnology/game-destruction';
-import { SpecFromObjectOptions, DestructionRenderer, Quality } from '@adatechnology/game-destruction-three';
+import { BusySink, 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';
 import { VfxWorld } from '@adatechnology/game-vfx';
 import { FilmBridge, FluidRenderer } from '@adatechnology/game-fluids-three';
-import { ContainerSpec, FluidWorld, LiquidDef, ItemUseDef, SurfaceSpec } from '@adatechnology/game-fluids';
-import { ModuleControl, ControlValue, ModuleLayer, DestructibleImpl, AnimationClipSpec, EnvironmentBus, TestableModule } from '@adatechnology/game-contracts';
-export { AnimationClipSpec, DestructibleImpl, ItemAnimationContract, ModuleScenario, TestableItem, TestableModule } from '@adatechnology/game-contracts';
+import { FluidWorld, ContainerSpec, LiquidDef, ItemUseDef, SurfaceSpec } from '@adatechnology/game-fluids';
+
+/** What the indicator shows now: the label of the task on top, its line of text, and how far it is (the bar) when it knows. */
+interface LoadingState {
+    readonly label: string;
+    readonly text: string;
+    readonly done: number;
+    readonly total: number | undefined;
+    /** The task hides what is behind the indicator. */
+    readonly opaque: boolean;
+    /** Tasks open at once (an area that builds a house inside a slow action counts two). */
+    readonly depth: number;
+}
+/**
+ * The loading indicator of the room: an overlay with a spinner or a bar and a line of text, shown for any slow job so that the page never looks frozen. `begin` shows it at once, `busy` also waits for the
+ * paint before it runs the work (the only way to show a bar before a heavy synchronous job), and the last task to end takes it down. The room lends it to modules as `ModuleHost.loading`.
+ */
+interface RoomLoading extends BusySink {
+    /** True while a task is open. */
+    readonly active: boolean;
+    /** Resolves once no task is open (at once when none is): a scenario or test awaits it after a change that rebuilds behind the indicator, instead of sleeping. */
+    idle(): Promise<void>;
+    /** What it shows now, or undefined when nothing is open. */
+    state(): LoadingState | undefined;
+    /** Follows it: called whenever a task opens, steps or ends, with `undefined` once none is left. Returns the function that stops following. */
+    on(listener: (state: LoadingState | undefined) => void): () => void;
+    /** The overlay element (undefined in a room with `ui: false`, where the page draws its own from `on`). */
+    readonly element: HTMLElement | undefined;
+    dispose(): void;
+}
+interface LoadingOptions {
+    /** The room's container: the overlay covers it. */
+    readonly container: HTMLElement;
+    /** False for a room with `ui: false`: the state is kept and told through `on`, nothing is drawn. Default true. */
+    readonly draw?: boolean;
+    /** Text of a task that has none yet (already translated). */
+    readonly working: string;
+}
+/** Resolves once the browser has painted a frame (a frame callback, then a timer), or after a short wait when frames are not running (a hidden tab, a test). */
+declare const nextPaint: () => Promise<void>;
+declare function createLoading(options: LoadingOptions): RoomLoading;
 
 type NewEntry = NewLogEntry;
 /** The log the room writes to (a `TestRoomLog` plus the write side). */
@@ -26,7 +66,7 @@ declare function createLog(options?: LogOptions): WritableLog;
 /** Locales shipped with the package. Unknown locales fall back to `en`. */
 type TestRoomLocale = 'en' | 'pt-BR';
 interface RoomStrings {
-    /** Display name per demo item id (see `DEMO_ITEMS`). */
+    /** Display name per item id the room itself names (none: the items come from the modules). */
     items: Record<string, string>;
     /** Display name per demo catalogue group. */
     groups: Record<string, string>;
@@ -107,6 +147,98 @@ interface HudState {
     };
     quality: string;
     objects: number;
+    /** The view when the room has a body (`null`: no body, no shortcut). */
+    camera: 'first' | 'third' | null;
+}
+
+/**
+ * The player's body in the room and the third-person camera. Generic: the room knows an avatar only by this interface (a body from any package
+ * that fits it, such as `createPlayerAvatar` of `@adatechnology/game-characters-three`), and no character code is imported here.
+ */
+
+/** What the room tells the avatar every frame. */
+interface RoomAvatarState {
+    /** Ground speed of the player, m/s (from the movement of the feet, jumps ignored). */
+    speed: number;
+    /** Shift held. */
+    running: boolean;
+    crouch: boolean;
+    down: boolean;
+    /** A firearm is the tool in hand. */
+    armed: boolean;
+    /** Camera pitch, radians, positive looking up (the room's own convention). */
+    pitch: number;
+}
+/** What the room tells the first-person arms every frame, after the modules have placed the tool in the hands. */
+interface RoomFirstPersonState {
+    /** The player's eye: the arms are drawn in its space. */
+    camera: THREE_NS.Object3D;
+    /** Where the tool in the hands asks them to be (world space): the module's, else the carried item's, else null. */
+    targets: HandTargets | null;
+    /** `hold` when something is held (targets), else the rest stance of the tool in hand (`relaxed`, `fists`...; `RoomOptions.handStances`). */
+    stance: string;
+    /** How far the index finger of the shooting hand is curled, 0 extended along the frame to 1 pulled on the trigger; null when no tool asks for it. */
+    triggerFinger: number | null;
+    speed: number;
+    running: boolean;
+    crouch: boolean;
+    /** The distance along a ray (world space) to the first thing in the room, or null: what the arms use to stop at a wall or a wardrobe. */
+    contact(origin: [number, number, number], direction: [number, number, number], maxDistance: number): number | null;
+}
+/** A body the room can show. The room puts `root` at the player's feet turned to where the player looks: the body's front is +z (as the catalogue items'), so `rotation.y` is the player's yaw plus pi. */
+interface RoomAvatar {
+    root: THREE_NS.Object3D;
+    update(dt: number, state: RoomAvatarState): void;
+    /** A socket at a hand: the carried item follows `hand('R')` in third person. */
+    hand?(side: 'R' | 'L'): THREE_NS.Object3D;
+    /**
+     * The arms of the first-person view. The room shows `root` only in first person (the body only in third), updates it every frame after the modules'
+     * frame hooks (so the tool in the hands is already placed) and before the render.
+     */
+    firstPerson?: {
+        root: THREE_NS.Object3D;
+        update(dt: number, state: RoomFirstPersonState): void;
+    };
+    /**
+     * Plays the strike `clipId` (on the body and on the arms) and answers the seconds until its impact, or null when this avatar has no such clip. The room then waits that long
+     * before the blow lands (`strikeClips`); an avatar without `strike`, or one that answers null, gets the blow at the click.
+     */
+    strike?(clipId: string, options?: {
+        leg?: 'left' | 'right';
+    }): number | null;
+}
+/** Which leg a kick uses: `alternate` swaps at each kick (right first). */
+type KickLeg = 'alternate' | 'left' | 'right';
+type CameraMode = 'first' | 'third';
+/** Which clip a melee tool plays before its blow lands (`TestRoomOptions.strikeClips`). */
+declare const DEFAULT_STRIKE_CLIPS: Readonly<Record<string, string>>;
+/** The first-person stance of the tools that choose one (`TestRoomOptions.handStances`). */
+declare const DEFAULT_HAND_STANCES: Readonly<Record<string, string>>;
+/**
+ * The over-the-shoulder view, metres. Defaults are the numbers of the team game's shoulder camera
+ * (`site/pages/jogo/zombiada-modo-livre.html`, `cameraUpdate`, line 76546): `view.cb` 3.8 back, `view.cs` 0.9 to the side, `view.cu` 1.95 high
+ * (1.4 crouched), the `+ 0.1` lift of the camera at line 76551, and three probe rays (centre and +-0.2 m, line 76557) that pull the camera in
+ * 0.3 m short of a wall (`h.t - 0.3`, never closer than 0.2 m) and let it out again slowly (`dt * 4`, line 76558).
+ */
+interface ThirdPersonOptions {
+    /** Distance behind the pivot. Default 3.8. */
+    back?: number;
+    /** Pivot offset to the right of the player (negative: left shoulder). Default 0.9. */
+    side?: number;
+    /** Pivot height above the feet. Default 1.95. */
+    up?: number;
+    /** Pivot height above the feet while crouched. Default 1.4. */
+    crouchUp?: number;
+    /** Extra height of the camera over the line from the pivot. Default 0.1. */
+    lift?: number;
+    /** How far short of a wall the camera stops. Default 0.3. */
+    margin?: number;
+    /** Closest the camera comes to the pivot. Default 0.2. */
+    minDistance?: number;
+    /** Sideways offsets of the probe rays. Default `[0, 0.2, -0.2]`. */
+    probes?: readonly number[];
+    /** Per second rate at which the camera returns after a wall is gone. Default 4. */
+    recover?: number;
 }
 
 /**
@@ -138,6 +270,8 @@ interface TestRoomItem {
     movable?: boolean;
     /** Short note shown in the inspector. */
     note?: string;
+    /** Building it takes a noticeable time (a vehicle): the catalogue shows the loading indicator while it spawns one. `true`, or the text to show. */
+    slow?: boolean | string;
     /**
      * The item holds a liquid (a cup of coffee, a bottle, a jerrycan, a fuel tank). `part` is the destruction part that is the container (a
      * bullet hole in it makes it leak). `uses` are the item uses offered while it is held (`drink`, `pour`...; defaults from `ITEM_USES`).
@@ -162,6 +296,61 @@ interface TestRoomItem {
     /** Author and licence of the thumbnail, shown as the tooltip of the picture in the inspector. */
     thumbnailCredit?: string;
 }
+/**
+ * One piece of destructible scenery of the arena (the target wall, the table, the shelf, or any piece the host adds): a spec, where it stands and how it is drawn.
+ * Keyed by arena object id in `TestRoomOptions.scenery`.
+ */
+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;
+    /** Turn about the vertical axis, radians (default 0). */
+    rotationY?: number;
+    /** Colour per part id, then per material id, for the default drawing (`buildFromSpec`). */
+    colors?: Record<string, number>;
+    /**
+     * Draws the object: a group whose meshes are named by part id (and carry `userData.destructionPart`), in the space of the spec. Without it the room
+     * draws one plain mesh per part with `buildFromSpec`.
+     */
+    build?: (THREE: ThreeNamespace) => THREE_NS.Object3D;
+    /** Name shown in the inspector and the log (default the translated name of a default id, else the id). */
+    label?: string;
+    /**
+     * A top that loose things rest on (and liquids pool on) while that part stands: the part id and the height of its upper face in the spec's space.
+     * The rectangle is the part's footprint. Without it nothing rests on the object.
+     */
+    top?: {
+        part: string;
+        y: number;
+    };
+    /**
+     * 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;
+}
+/** 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 {
+    weapon: string;
+    explosive?: string;
+    kind: 'grenade' | 'molotov' | 'rocket' | 'charge';
+}
+/** 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;
+}
+/** 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;
+    /** 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;
+    /** Turn about the vertical axis, radians (default 0). */
+    rotationY?: number;
+}
 interface TestRoomOptions {
     THREE: ThreeNamespace;
     /** Element the bench fills (canvas + HUD). */
@@ -195,6 +384,19 @@ interface TestRoomOptions {
     maxCarryKg?: number;
     /** Arena half size in metres (default 14). */
     arenaSize?: number;
+    /**
+     * The destructible scenery of the arena, by object id. The defaults are `target_wall` (a brick wall of panels 11 m ahead of the start), `table` (with the
+     * water tap beside it) and `shelf`. A key that matches a default replaces it (the position defaults to the replaced one), `null` removes it, a new key adds
+     * a piece (its `position` is required). The player cannot walk through any of them: the collider is the footprint of the spec's parts.
+     */
+    scenery?: Record<string, SceneryObject | null>;
+    /** The tap of the room. Omitted: a tap drawn from primitives on a post beside the table; an object: that model (see `SceneryTap`); `null`: no tap. */
+    tap?: SceneryTap | null;
+    /**
+     * The model of something thrown (a grenade, a molotov, a rocket) or set down (a charge). The room only knows the arsenal's ids, so the host's weapons package
+     * supplies the real model; where it answers nothing the room draws a plain primitive (a sphere, a cylinder, a box).
+     */
+    projectileModel?: (query: ProjectileQuery) => ProjectileModel | null | undefined;
     /** Spawn these catalogue ids on start, in a row in front of the player. */
     initial?: string[];
     /** Open on one catalogue group (`furniture`, `structure`, `weapons`…): see `TestRoom.openArea`. */
@@ -211,10 +413,30 @@ interface TestRoomOptions {
     environment?: EnvironmentBus;
     /** Show the built-in HUD and panels (default true). */
     ui?: boolean;
+    /** The player's body (see `TestRoom.setAvatar`). */
+    avatar?: RoomAvatar;
+    /** The view the room starts in (default `first`; the V key and `TestRoom.setCameraMode` change it). */
+    cameraMode?: CameraMode;
+    /**
+     * The strike clip each melee tool plays before its blow lands, by tool id. The blow (`meleeUse`, with the aim read again) falls at the clip's impact second, which
+     * the avatar's `strike` answers; a tool that is not here, or an avatar that cannot play the clip, strikes at the click. Default `{ fists: 'punch_right', shove: 'shove_two_hands', kick: 'front_kick' }`.
+     */
+    strikeClips?: Readonly<Record<string, string>>;
+    /** Which leg the kick uses: `alternate` (default) swaps at each kick starting with the right, or always `left` or `right`. */
+    kickLeg?: KickLeg;
+    /** The first-person stance of the arms by tool id, for the tools that hold nothing the module places (default `{ fists: 'fists' }`; any other tool holds, or is `relaxed` with nothing to hold). */
+    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;
     /** Room counters the bench panel shows and `TestRoom.metrics()` returns (default all); `false` for none. */
     metrics?: readonly RoomMetricId[] | false;
     /** 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;
+    /**
+     * The numbers of the shove an explosion gives to what is around it: loose items, furniture, and the bodies of the modules (people), which read them from `ModuleHost.blastShove`.
+     * Default: the SDK's (`DEFAULT_BLAST_SHOVE` of game-contracts: 2 % of the energy becomes speed, 20 m/s at most, falloff `(1 - d / r)^2`).
+     */
+    blastShove?: BlastShoveOptions;
     /**
      * 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.
@@ -303,7 +525,7 @@ interface TestRoom {
     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', fn: (data: unknown) => void): () => void;
+    on(type: 'spawn' | 'tool' | 'grab' | 'throw' | 'event' | 'camera', 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. */
@@ -328,6 +550,15 @@ 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[];
+    /**
+     * `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.
+     */
+    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;
+    /** `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`. */
     readonly scenarios: TestRoomScenario[];
     /** The liquid renderer of `@adatechnology/game-fluids-three` (containers, streams, stains). */
@@ -342,6 +573,12 @@ interface TestRoom {
      * clip) writing a check line (pass or fail) per result to the log. Loading the same module twice replaces its items and scenarios.
      */
     loadModule(module: TestableModule<ScenarioContext>): ModuleReport;
+    /**
+     * Compiles the shader programs that the first hit, decal or effect would otherwise compile in the middle of a frame, then draws a throw-away blast (its particle materials
+     * and lights make the materials recompile the first time they appear) and a fire and clears them, so a loading screen can pay those first-frame costs. Nothing of it stays
+     * in the world, the log or the sound. Call it once the lights of the scene are set (a module that adds lights changes the programs).
+     */
+    warmUp(): void;
     /** Animations of the aimed (or held) item: what the animations panel shows. */
     animations(): AnimationInfo | null;
     /**
@@ -351,6 +588,37 @@ interface TestRoom {
     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;
+    /**
+     * Show a body for the player (or none with null). The room adds `root` to the scene, puts it at the player's feet with the player's yaw every
+     * frame and calls `update` with the speed of the player's movement, Shift, the crouch/down set by `setAvatarState`, whether a firearm is in hand
+     * and the camera pitch. Hidden in first person, shown in third. In third person the carried item follows `avatar.hand('R')`. The previous
+     * avatar is taken out of the scene, not disposed.
+     */
+    setAvatar(avatar: RoomAvatar | null): void;
+    readonly avatar: RoomAvatar | null;
+    /** Crouch and knocked-down state a player module drives (merged over what is set; the room fills the rest). `armed` forces the armed arms (`null`: follow the tool in hand again). */
+    setAvatarState(state: {
+        crouch?: boolean;
+        down?: boolean;
+        armed?: boolean | null;
+    }): void;
+    /** What the first-person arms were last given: the stance, how far the trigger finger is curled (0 extended to 1 pulled) and the targets. Read it on each shot to see the finger. */
+    handState(): {
+        stance: string;
+        triggerFinger: number | null;
+        targets: HandTargets | null;
+    };
+    /** 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;
+        fov?: number;
+    } | null): void;
+    /** What the avatar was last given. */
+    avatarState(): RoomAvatarState;
+    /** `first` (the camera is the eye) or `third` (over the shoulder). V toggles it when a body is set. Logged as a `camera` action. */
+    setCameraMode(mode: CameraMode): void;
+    readonly cameraMode: CameraMode;
     /** 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
@@ -484,29 +752,8 @@ interface ScenarioReport {
  */
 declare function createTestRoom(options: TestRoomOptions): TestRoom;
 
-/**
- * Extra materials the demo items need on top of the core ones. None any more (the bottle uses the core `glass`, which now breaks from a drop);
- * kept so that code passing it to `worldOptions.materials` keeps working.
- */
-declare const DEMO_MATERIALS: MaterialDef[];
 /** 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;
-/**
- * The generic demo catalogue, names and groups translated for `locale` (`en` or `pt-BR`). Every item is a procedural low-poly build (one mesh per
- * destruction part, drawn by `buildFromSpec`) plus an explicit destruction spec. Containers carry a fluid container where it makes sense.
- */
-declare function demoItems(locale?: string, extra?: TestRoomItem[]): TestRoomItem[];
-/** The demo catalogue in English (see `demoItems` for other locales). */
-declare const DEMO_ITEMS: TestRoomItem[];
-
-type T = (key: string, vars?: Record<string, string | number>) => string;
-type Num = (n: number, digits?: number) => string;
-/** Built-in scripted checks over the generic `DEMO_ITEMS`. Names and check texts come from the room locale. */
-declare function makeScenarios(t: T, num: Num, _locale?: string): TestRoomScenario[];
-/** The built-in scenarios for a locale (`en` or `pt-BR`), standalone: no room needed to list them. */
-declare function scenariosFor(locale?: string): TestRoomScenario[];
-/** The built-in scenarios in English. The room offers them in its own locale. */
-declare const SCENARIOS: TestRoomScenario[];
 
 /** Default look of each built-in destruction material (`0xRRGGBB`). */
 declare const MATERIAL_COLORS: Record<string, number>;
@@ -525,9 +772,24 @@ interface BuildFromSpecOptions {
  */
 declare function buildFromSpec(THREE: typeof THREE_NS, spec: DestructibleSpec, options?: BuildFromSpecOptions): THREE_NS.Group;
 
+/**
+ * The look of the loading indicator, with no dependency: a card with a title, a bar and a line of text over a dim backdrop. The room draws it (`createLoading`), and a page that must show it before any
+ * script has run (the default test room's first frame) writes the same markup and styles from `loadingMarkup` and `LOADING_CSS`, so the screen the page starts with and the one the room shows later are one.
+ */
+declare const LOADING_CLASS = "tr-loading";
+declare const LOADING_CSS: string;
+/** The markup of the indicator as a string, for a page that writes it into its HTML. `solid` is the opaque backdrop of a first screen, `fixed` covers the window instead of the room. */
+declare function loadingMarkup(options: {
+    title: string;
+    step?: string;
+    solid?: boolean;
+    fixed?: boolean;
+    id?: string;
+}): string;
+
 /** `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 };
+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 };