@adatechnology/game-test-room 0.16.0 → 0.17.0

package/README.md

@@ -181,6 +181,7 @@ 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 |
+| K | kick with the `kick` tool whatever is in hand (`kick.keys`, default `['KeyK']`; also the Kick button and `room.kick()`); a 250 J blunt blow, ten times the punch, that lands from the leg (`kickHeights`, every 10 cm from 0.25 to 0.85 m above the feet, level) on what stands low in front, else where the eye aims |
 | 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 |
 
@@ -202,7 +203,9 @@ interface RoomAvatar {
 
 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. The left click with bare hands (`hand`, the default tool) punches too (E or the right button grab). Punches alternate hands, right first (`punchHand`: `alternate`, `left`, `right`; `punchTools`, default `['hand', 'fists']`): the room calls `strike(clip, { hand })` and logs the hand, as the kick does with `kickLeg` and `{ leg }`. 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).
+**Pushing furniture.** Against a piece that stands on the floor, with bare hands, a tap on E grabs as ever and holding E fills a ring around the crosshair (longer the heavier). Then W pushes, S pulls, slower with the mass; letting go ends it. Before each step the volume of the piece is swept (`world.sweepBox`) against everything and the arena: at an obstacle the piece and the player stop and the player strains, and a piece too heavy for the player (`RoomOptions.push`, `FurniturePushRules` of game-player) never moves. A piece lower than a table is pushed from above, bent over it. Scripted: `room.push`. Try it: `?scene=push` in the example.
+
+**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. The left click with bare hands (`hand`, the default tool) punches too (E or the right button grab). Punches alternate hands, right first (`punchHand`: `alternate`, `left`, `right`; `punchTools`, default `['hand', 'fists']`): the room calls `strike(clip, { hand })` and logs the hand, as the kick does with `kickLeg` and `{ leg }`. A **strike combo** is an ability the page gives (`strikeCombo`, such as `PUNCH_COMBO` of `game-characters-people`: jab, cross, hook, uppercut): while it is on (N, its button, `setStrikeCombo(true)`, `strikeComboOn`) each blow of its tools plays its next step (`{ clip, hand }`) and a pause longer than its `reset` starts it over; off, the tools strike as usual. The strike line carries `combo` and `step`. 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.
 
@@ -237,7 +240,7 @@ 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.
+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; K (ou Shift+V, o botão Chute e `room.kick()`) chuta com qualquer ferramenta na mão. 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
 

package/dist/index.d.ts

@@ -2,14 +2,40 @@ 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';
 export { DestructionEvent, Vec3 } from '@adatechnology/game-destruction';
-import { BusySink, Vec3, HandTargets, ModuleControl, ControlValue, ModuleLayer, EnvironmentBus, BusyTask, BusyOptions, TestableModule, DestructibleImpl, AnimationClipSpec, BlastShoveOptions } from '@adatechnology/game-contracts';
+import { FurniturePushPhase, FurniturePushBlock, FurniturePushRules } from '@adatechnology/game-player';
+import { BusySink, Vec3, HandTargets, ModuleControl, ControlValue, ModuleLayer, EnvironmentBus, BusyTask, BusyOptions, TestableModule, DestructibleImpl, AnimationClipSpec, GroundLayout, 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 { Terrain, TerrainBudget } from '@adatechnology/game-terrain';
 import { FilmBridge, FluidRenderer } from '@adatechnology/game-fluids-three';
 import { FluidWorld, ContainerSpec, LiquidDef, ItemUseDef, SurfaceSpec } from '@adatechnology/game-fluids';
 
+/**
+ * The room's side of pushing furniture: finds what the player leans on, asks `createFurniturePush` (game-player) how it goes, tests the volume of the piece before each
+ * step (the world, the walls of the arena, the blockers of the modules) and moves it with the player. The animations read `avatarState` and `handTargets`.
+ */
+
+type RoomPushEvent = {
+    readonly type: 'grip' | 'release';
+    readonly objectId: string;
+    readonly name: string;
+    readonly massKg: number;
+} | {
+    readonly type: 'engaged' | 'too_heavy' | 'obstacle';
+    readonly objectId: string;
+    readonly name: string;
+    readonly massKg: number;
+};
+type RoomPushState = {
+    readonly objectId: string;
+    readonly phase: FurniturePushPhase;
+    readonly progress: number;
+    readonly block: FurniturePushBlock;
+    readonly massKg: number;
+};
+
 /** 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;
@@ -273,6 +299,8 @@ interface HudState {
     timeScale: number;
     fast: boolean;
     tap: boolean;
+    /** The strike combo (`strikeCombo`) is on; null when the room has none. */
+    combo?: boolean | null;
     /** The room's blast options that are on. */
     blast: {
         shelter: boolean;
@@ -311,6 +339,11 @@ interface RoomAvatarState {
     holding?: boolean;
     /** Active scripted item use (`drink`, `sip`, `chug`, `pour`, `open`, `close`, `tilt`). */
     itemUse?: RoomAvatarItemUse | null;
+    /** Hands on a piece of furniture: `grip` while the hold timer fills (`progress`), `push` walking with it, `strain` straining against what does not give. */
+    push?: {
+        readonly phase: 'grip' | 'push' | 'strain';
+        readonly progress: number;
+    } | null;
 }
 /** What the room tells the first-person arms every frame, after the modules have placed the tool in the hands. */
 interface RoomFirstPersonState {
@@ -398,6 +431,18 @@ interface ThirdPersonOptions {
  * from buttons (or headless in tests) and write pass/fail checks to the same log, so people and agents can verify the behaviour.
  */
 
+/** What `strikeCombo` takes: the shape of `StrikeCombo` of game-characters-people, restated so the room does not depend on it. */
+type StrikeComboOption = {
+    readonly id: string;
+    readonly name?: Readonly<Record<string, string>>;
+    readonly tools: readonly string[];
+    readonly steps: ReadonlyArray<{
+        readonly clip: string;
+        readonly hand?: 'left' | 'right';
+    }>;
+    readonly reset: number;
+};
+
 type ThreeNamespace = typeof THREE_NS;
 /** One entry of the catalogue: something the host can build. */
 interface TestRoomItem {
@@ -478,6 +523,7 @@ interface SceneryObject {
     top?: {
         part: string;
         y: number;
+        parts?: readonly string[];
     };
     /**
      * 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.
@@ -538,8 +584,10 @@ 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;
+    /** 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. */
+    terrainBudget?: Partial<TerrainBudget>;
     /** Heaviest object the player can carry (default 60 kg). */
     maxCarryKg?: number;
     /** Arena half size in metres (default 14). */
@@ -557,7 +605,7 @@ interface TestRoomOptions {
      * 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;
-    /** Keys (`KeyboardEvent.code`) that crouch while held; default `['KeyC']`. Ctrl is left out on purpose: Ctrl+W closes the tab. */
+    /** Keys (`KeyboardEvent.code`) that crouch (a tap stays crouched until the next tap, a longer press crouches while held); default `['KeyC']`. Ctrl is left out on purpose: Ctrl+W closes the tab. */
     crouch?: {
         keys?: string[];
     };
@@ -586,12 +634,27 @@ interface TestRoomOptions {
      * 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>>;
+    /** The numbers of pushing furniture (`FurniturePushRules` of game-player): the player's force, the friction by material, the hold time, the speed. */
+    push?: Partial<FurniturePushRules>;
     /** Which leg the kick uses: `alternate` (default) swaps at each kick starting with the right, or always `left` or `right`. */
     kickLeg?: KickLeg;
+    /** Metres above the feet the kick looks for a target from (level, the way the player faces; the nearest hit wins), so it finds what stands low in front; default every 10 cm from 0.25 to 0.85 m (shin to hip). */
+    kickHeights?: readonly number[];
+    /** Keys (`KeyboardEvent.code`) that kick with the arsenal's `kick` tool, whatever tool is in hand; default `['KeyK']` (Shift+V kicks too). */
+    kick?: {
+        keys?: string[];
+    };
     /** Which hand throws the one-handed strikes (`punchTools`): `alternate` (default) swaps at each punch starting with the right, or always `left` or `right`. */
     punchHand?: PunchHand;
     /** The tools whose strike is thrown with one hand, so `punchHand` picks it (default `['hand', 'fists']`); the shove and the kick are not. */
     punchTools?: readonly string[];
+    /**
+     * A strike combo the player has (an ability, such as `PUNCH_COMBO` of game-characters-people): while it is on (N, the combo button or `setStrikeCombo`), each blow of its
+     * `tools` plays its next step (`{ clip, hand }`) and a pause longer than `reset` seconds starts it over; while it is off the tools strike as usual. Default none.
+     */
+    strikeCombo?: StrikeComboOption;
+    /** Start with the combo on. Default false. */
+    strikeComboOn?: boolean;
     /** 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. */
@@ -681,8 +744,20 @@ interface TestRoom {
     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;
+    /** Where the player's feet are. */
+    readonly playerPosition: Vec3$1;
     /** Grab what the camera looks at (or drop what is held). */
     grab(): boolean;
+    /**
+     * Pushing furniture, as holding E against it does: `begin` leans on what the camera looks at (false: nothing within reach to lean on), `setWalk` walks by script (world `[x, z]`, unit; null: the keys), `end`
+     * lets go, and `state` says the phase (`grip` while the hold timer fills, `push`, `strain`), the timer and what stops it (`too_heavy`, `obstacle`).
+     */
+    readonly push: {
+        begin(): boolean;
+        end(): boolean;
+        setWalk(walk: readonly [number, number] | null): void;
+        readonly state: RoomPushState | null;
+    };
     /** Throw what is held at `speed` m/s (default 9). */
     throwHeld(speed?: number): boolean;
     /** Point the camera (scripted demos and tests). */
@@ -718,12 +793,20 @@ interface TestRoom {
     setSlowMotion(on: boolean): void;
     /** Run the simulation 10x per frame (fire, melting and drying take a tenth of the time). */
     setFastForward(on: boolean): void;
+    /** Turn the strike combo (`strikeCombo`) on or off (N and the combo button do the same); nothing without a combo. */
+    setStrikeCombo(on: boolean): void;
+    /** Whether the strike combo is on; null when the room has none. */
+    readonly strikeCombo: boolean | null;
+    /** Kick with the arsenal's `kick` tool, whatever tool is in hand (K, Shift+V and the kick button do the same); false when there is none or it is not ready yet. */
+    kick(): boolean;
     /** Equip a weapon by id, adding it to the hotbar when it is not there. Same as selecting a catalogue item with `TestRoomItem.weapon`. */
     equip(weaponId: string): void;
     /**
      * Set the room up to test one catalogue group or loaded module (by its group or id): clear it and open the catalogue on that tab. A module
      * 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.
      */
+    /** The floor: what it is made of, how deep it was dug, its marks and thrown pieces. */
+    readonly terrain: Terrain;
     openArea(group: string): SpawnedObject[];
     /** The loaded modules (`loadModule`): id, name, catalogue group and whether it lays an area of its own. */
     modules(): Array<{
@@ -974,4 +1057,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 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 };
+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 RoomFirstPersonState, type RoomLoading, type RoomMetricId, type RoomPushEvent, type RoomPushState, 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 };