@adatechnology/game-weapons-three 0.7.1 → 0.8.0

package/README.md

@@ -4,6 +4,16 @@ three.js presentation for `@adatechnology/game-weapons`: the real models of the
 
 The muzzle flash, the smoke, the backblast of a launched rocket and the flame jet of the weapon in the hands are not built here: they are recipes of `@adatechnology/game-vfx` (`viewmodel_muzzle_flash`, `weapon_smoke_puff`, `launcher_backblast`, `flame_jet`) that draw them as the gallery does, as solids (an open cone, four small cones and a core for 55 ms growing from 0.6 to 1.5 times their size, a light of `4 k` that holds, spheres of smoke that rise and grow, icosahedra of fire), with the gallery's numbers and the barrel's whole turn (`orientation`, pitch and roll included). `createWeaponFx({ effects })` plays them through the host's effect sink (the test area passes `host.effects`); with no sink the viewer makes a world of effects of its own, stepped and drawn with the weapon. Casings, magazines, the rocket itself and the burning droplets stay meshes of this package.
 
+**Hands.** The weapon in the hands tells the host where the hands go (`host.setHandTargets`, `HandTargets` of `game-contracts`): the right on the pistol grip (the `grip` pivot of the model, else under the receiver), the left on the handguard, on the pump of a pump gun (it moves with the pump), under the right on a handgun, and to the magazine while it is changed; the generic props take the right hand on the `handle` and the left under the `head` of a long gun. Sizes come from the model, the hands shrink with a model drawn small.
+
+**Reload sounds.** Each step of a reload makes its noise where the clip says: the clips carry `sound` cues (`cue(t, 'sound', { id })`), so the sound follows the animation and scales with the weapon's reload time (`mag_release`, `mag_out`, `mag_insert`, `mag_seat`, `slide_release`, `charging_handle_pull/release`, `bolt_lift/pull/push/lock`, `shell_insert` once per round, `pump_back/forward`, `lever_open/close`, `cylinder_open/eject/close`, `speedloader`, `barrels_open/close`, `belt_cover_open/close`, `belt_insert`, `rocket_load/seat`, `grenade_load`, `breech_open/close`, `tube_drop/seat`). The recipes are data (`src/data/reload-sounds.json`: layers of the game-audio primitives); a profile (`soundProfileOf`: weight light/medium/heavy from the model family, steel or polymer from a list in the data) changes their pitch and level, and `createWeaponAudio(volume, { reloadCues })` replaces or adds recipes. `createWeaponFx({ onSound })` is told at each cue (the test area logs it as a `sound` entry); `WeaponFx.clips` says which reload variant is playing. `tests/reload-sounds.test.ts` checks the cue order of every weapon and kind, one recipe per cue, and the per-round sounds.
+
+## Geometry
+
+The models' geometry comes from [`game-shapes`](../game-shapes): the model kit's `THREE` is `shapeGeometries(host)` (box, cylinder, cone, sphere,
+torus with the same bytes and classes as three's, from a template cache; icosahedron and tube are still three's). `tests/exact-golden.test.ts`
+holds every bit of the models, accessories, cartridges and props as the old path made them (`UPDATE_EXACT=1` rewrites it).
+
 ## Licenses
 
 The code is MIT. The `assets/weapon-svg/` thumbnails are not code and have their own licenses, which is why the `license` field is an expression:
@@ -14,3 +24,28 @@ The code is MIT. The `assets/weapon-svg/` thumbnails are not code and have their
 Read `assets/weapon-svg/LICENSE-NOTE.md` before redistributing the folder and keep `assets/weapon-svg/CREDITS.md` (author, license, link and modifications of every file) and `manifest.json` with it. The kit's demo site shows the same credits at `weapon-svg/credits.html`.
 
 Unused generated fallbacks: every weapon keeps its `generated/` file even when it has a `commons/` one; the manifest does not reference those, they are what the weapon returns to if the Commons file is removed.
+
+## Models of thrown and fired explosives
+
+`projectileModel(THREE, { weapon, explosive, kind })` gives a host the model of the round a launcher fires (the RPG-7's PG-7V, the Carl Gustaf's 84 mm round, the rocket of the disposable tubes; the same code the weapon in the hands uses to fly it), long axis +x, or `null`. It is the hook the test room's `projectileModel` option takes. The gallery has no model yet for the throwables (M67, molotov, pipe bomb, dynamite, C4, Claymore, flashbang) nor for the grenade launchers (M203, GP-25, AG36: their rounds), so those answer `null`.
+
+`createWeaponsTestModule({ flyRocket: false })` (and `createWeaponFx`) keeps the viewmodel from flying a rocket of its own out of the launcher, for a host that draws the projectile itself (the test room does, with `projectileModel`): one round flies, not two. The backblast stays.
+
+## Área de explosivos (`explosives_area`)
+O botijão P13 de cozinha com o modelo real do time (`lpg_cylinder_13kg`, 0,353 x 0,49 x 0,358 m), numa quina de cozinha junto da parede de tijolo: geladeira, balcão, fogão e mesa, um zumbi a 3 m, um sobrevivente a 8 m, anéis no chão a 5 m (letal) e 14 m (ferimento) e o jogador a cerca de 6 m (fora do anel letal). Abre por `?area=explosives_area` (ou `?area=Explosivos`; em inglês `Explosives`); a página padrão da sala já a carrega.
+| Id | Tipo | O que faz |
+|---|---|---|
+| `shoot` | botão | "Atirar no botijão": 9 mm no casco; jato branco, tocha em 0,8 s, explosão em 1,4 s |
+| `valve` | botão | "Abrir o registro": vaza sem fogo; sem chama não explode |
+| `light` | botão | "Acender (isqueiro)": a chama acende o vazamento, vira tocha e explode 1,4 s depois |
+| `fire` | botão | "Jogar no fogo": poça de fogo a 700 °C; o casco passa de 300 °C e explode |
+| `reset` | botão | "Reiniciar": refaz a cena |
+| `blast_scale` | número 0,25 a 3 (padrão 1) | "Força da explosão (multiplicador de jogo)": multiplica energia e raios do botijão a cada novo botijão |
+| `rings` | camada | os anéis de 5 m e 14 m |
+| `gas`, `clock`, `phase` | métricas | gás que resta, relógio desde o gatilho e fase |
+
+Cada fase conta no registro da sala, em pt-BR e en, e vira JSON no registro de comportamento. Depois do estouro o casco voa com rastro de fogo e o fogo residual dura 7 s; 2 s depois o registro diz quem morreu e o que a parede e os móveis perderam.
+
+**Onde ajustar a força:** o multiplicador da bancada é só do teste. No jogo, energia, raios, tempos e gás ficam no arsenal: `createArsenal({ patch: { explosives: { propane_p13: { energy, lethalRadius, injuryRadius, chain: { shot, fire, explosion }, leak: { igniteDelay, liters, hissSeconds }, shell: { launchSpeed, trailSeconds } } } } })` (`ArsenalOptions.patch.explosives`). `createExplosivesTestModule({ blastScale })` muda o ponto de partida da bancada.
+
+Cenários: `explosives_p13_shot`, `explosives_p13_valve`, `explosives_p13_fire`, `explosives_p13_chain`.

package/assets/weapon-svg/generated/propane_p13.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 200" fill="currentColor" fill-rule="evenodd"><path fill-opacity=".6" d="M345 12 455 12 455 188 345 188Z"/></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 200" fill="currentColor" fill-rule="evenodd"><path fill-opacity=".6" d="M366.5 12 433.5 12 436.5 13.5 437.5 18 436 20.5 433 21.5 433 37.5 438 38.5 450 49.5 454 52 460.5 74 460.5 141 457 170.5 454.5 174.5 463.5 174.5 463.5 188 336.5 188 336.5 174.5 345.5 174.5 343 170.5 339.5 141 339.5 74 346 52 350 49.5 362 38.5 367 37.5 367 21.5 364 20.5 362.5 18 363.5 13.5ZM372.5 21.5 372.5 36 382 34 383.5 33 391 33 391 21.5ZM409 21.5 409 33 416.5 33 418 34 427.5 36 427.5 21.5Z"/></svg>

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { HostTool, EffectSink, HostEvent, TestableModule, AreaPlacement, TestableItem, DestructibleSpec, ToolClipSet } from '@adatechnology/game-contracts';
+import { HostTool, EffectSink, HostEvent, HandTargets, TestableModule, AreaPlacement, DestructionEvent, Hit, Vec3 as Vec3$1, ModuleControl, ModuleLayer, ModuleMetric, ModuleHost, TestableItem, DestructibleSpec, ToolClipSet } from '@adatechnology/game-contracts';
 import { CaliberDef, ReloadStageId, WeaponEvent, MountKind, AttachmentDef, FittedAttachment, Arsenal, ExplosiveDef, WeaponDef, CartridgeDims, CaseType, ReloadFamily } from '@adatechnology/game-weapons';
 import { AudioEngine } from '@adatechnology/game-audio';
 import * as THREE_NS from 'three';
@@ -169,6 +169,41 @@ declare const MECHANICAL_SOUNDS: Readonly<Record<MechanicalSoundId, readonly Sou
 /** Which mechanical sound a weapon event asks for, if any (`shot`, `draw` and `reload` start/end have their own handling). */
 declare const mechanicalSoundOf: (event: WeaponEvent) => MechanicalSoundId | undefined;
 
+var profiles = {
+	weight: {
+		light: {
+			pitch: 1.3,
+			gain: 0.85
+		},
+		medium: {
+			pitch: 1,
+			gain: 1
+		},
+		heavy: {
+			pitch: 0.78,
+			gain: 1.2
+		}
+	},
+	material: {
+		steel: {
+			pitch: 1,
+			gain: 1
+		},
+		polymer: {
+			pitch: 0.82,
+			gain: 0.8
+		}
+	}
+};
+var data = {
+	profiles: profiles};
+
+/** How a weapon sounds: the weight of its metal (pitch and level) and what it is made of. */
+interface SoundProfile {
+    readonly weight: keyof typeof data.profiles.weight;
+    readonly material: keyof typeof data.profiles.material;
+}
+
 /** What a shot adds to the energy and the category: where the listener is and how the weapon is set. */
 type ShotExtras = Pick<ShotSoundInput, 'caliber' | 'distance' | 'volume' | 'suppressed' | 'indoors'>;
 interface WeaponAudioOptions extends ShotSoundOptions {
@@ -176,6 +211,8 @@ interface WeaponAudioOptions extends ShotSoundOptions {
     readonly seed?: number;
     /** Replaces or adds mechanical sounds by id. */
     readonly mechanical?: Readonly<Partial<Record<MechanicalSoundId, readonly SoundStep[]>>>;
+    /** Replaces or adds the sounds of the reload clip cues by id (`reload-sounds.json` has the ones the kit ships). */
+    readonly reloadCues?: Readonly<Record<string, readonly SoundStep[]>>;
     /** Where the AudioContext comes from (default: the global one); lets a host or a test lend its own. Not used with `engine`. */
     readonly createContext?: () => AudioContext;
     /**
@@ -195,6 +232,8 @@ interface WeaponAudio {
     click(): void;
     /** A mechanical sound by id: a reload stage, `dry_fire`, `jam`, `safety_on`... */
     mechanical(id: MechanicalSoundId): void;
+    /** A cue of a reload clip (`mag_seat`, `charging_handle_pull`, `pump_back`...) for a weapon's profile (the weight of its metal and what it is made of): played now, where the clip says. */
+    cue(id: string, profile?: SoundProfile): void;
     /** The mechanical sound of a weapon event, if it has one (reload stages, empty, misfire, fault, clear, safety, mode, feed). */
     event(event: WeaponEvent): void;
     /** A sound class of the game by name (`impact`, `flesh`, `glass`...), with the game's distance muffling. */
@@ -339,6 +378,8 @@ interface ModelParts {
     chambers?: THREE_NS.Object3D[];
     barrels?: THREE_NS.Object3D;
     breech?: THREE_NS.Object3D[];
+    /** The pivot of the pistol grip (its y runs along the grip, tilted as the grip is): the right hand holds here. Models without a drawn grip leave it out and the hand is placed from `frames`. */
+    grip?: THREE_NS.Object3D;
     /** The existing selector or safety mesh; the gallery draws it but does not move it. */
     safety?: THREE_NS.Object3D;
     muzzle?: THREE_NS.Object3D;
@@ -463,8 +504,11 @@ interface ModelKit {
     mark(parent: Parent, x: number, y: number, z: number): THREE_NS.Object3D;
     pivot(parent: Parent, x?: number, y?: number, z?: number): THREE_NS.Group;
 }
-/** One kit per three.js namespace: the materials and the geometry cache are shared by every model built with it. */
-declare function modelKit(THREE: Three): ModelKit;
+/**
+ * One kit per three.js namespace: the materials and the geometry cache are shared by every model built with it. The kit's `THREE` is
+ * `shapeGeometries(host)`: box, cylinder, cone, sphere and torus come from game-shapes (the same bytes, the same classes); the rest is the host's.
+ */
+declare function modelKit(host: Three): ModelKit;
 
 type Vec3 = [number, number, number];
 /** The shape of a model that carries its `inner` and `root` as `buildWeaponModelById` makes them. */
@@ -542,6 +586,8 @@ interface WeaponFxOptions {
     audio?: WeaponAudio | null;
     /** Seed of the scatter of the effects of the gallery models. */
     seed?: number;
+    /** The rocket of a launcher flies out of the viewmodel along the barrel (default true). A host that draws the projectile itself (the test room does) sets it to false, so one round flies, not two. */
+    flyRocket?: boolean;
     /** The tool as it is now (barrel heat, fuel burning). */
     tool?: () => HostTool;
     /** Wear of the weapon: `new`, `used`, `worn` or `rusty`. */
@@ -550,10 +596,18 @@ interface WeaponFxOptions {
     layers?: FxLayers;
     /** Metres between the shooter and the listener, for the distance muffling of the shot sound (default 0). */
     soundDistance?: () => number;
+    /** Told at every sound cue of a reload clip, at the moment the clip says it (also with no audio): the weapon, the cue id and the profile it sounds with. */
+    onSound?: (cue: {
+        weapon: string;
+        cue: string;
+        profile: SoundProfile;
+    }) => void;
     /** Builders of accessory models that replace or add to the ones the kit ships (by the `model` of the accessory). */
     attachmentModels?: AttachmentModelRegistry;
     /** How far a laser beam goes from a point along a direction (metres), or null when it hits nothing: the dot lands where it ends. */
     raycast?: LaserRaycast;
+    /** Where the world is (distance from a point along a direction to the first surface, or null): the weapon in the hands comes back from a wall it would go through. */
+    contact?: LaserRaycast;
     /** The host's effects: the muzzle flash, smoke, backblast and flame jet of the gallery models are recipes it plays; without it the viewmodel makes a world of its own for them. */
     effects?: EffectSink;
 }
@@ -565,10 +619,17 @@ interface WeaponFx {
     update(dt: number): void;
     /** Dresses the weapon for its wear (`new`, `used`, `worn`, `rusty`); the gallery models show it in their metal. */
     setCondition(condition: string): void;
+    /** Where the hands take the weapon (world space, read every frame after `update`): the grip and the forend of the model, or the handle of the generic prop; null with nothing in the hands. */
+    handTargets(): HandTargets | null;
     /** What is drawn (casings, magazines, muzzle flash): change a field and the next event follows it. */
     readonly layers: FxLayers;
     /** Weapon shown in the hands, or null. */
     readonly inHand: string | null;
+    /** The clips of the model playing now with the seconds each lasts (scaled to the rule's duration): which reload variant went (`reload` or `reload_empty`...). */
+    readonly clips: ReadonlyArray<{
+        name: string;
+        seconds: number;
+    }>;
     /** Casings and magazines currently on the floor or in the air. */
     readonly casings: number;
     readonly magazines: number;
@@ -595,6 +656,8 @@ interface WeaponsTestModuleOptions {
     attachmentModels?: AttachmentModelRegistry;
     /** Folder (ending with a slash) the weapon thumbnails are served from, relative to the page (default `weapon-svg/`); `false` leaves the items without a thumbnail. */
     thumbnailBase?: string | false;
+    /** The rocket of a launcher flies out of the weapon in the hands (default true). A host that draws the projectile (the test room's `projectileModel`) passes false: one round flies. */
+    flyRocket?: boolean;
 }
 /** Prefix of the item ids of the weapon props (`weapon_pistol_9mm`). */
 declare const WEAPON_ITEM_PREFIX = "weapon_";
@@ -631,12 +694,334 @@ declare const DEFAULT_THUMBNAIL_BASE = "weapon-svg/";
 /** The URL of a weapon's thumbnail under `base` (which ends with a slash), or undefined when it has none. */
 declare function weaponThumbnailUrl(id: string, base?: string): string | undefined;
 
+/** The words of the explosives area (the P13 cylinder bench and its narration), by locale (`en` and `pt-BR`). `{name}` marks a value the module fills in. */
+interface ExplosivesText {
+    group: string;
+    name: string;
+    cylinder: string;
+    actions: Record<'shoot' | 'valve' | 'light' | 'fire' | 'reset', {
+        name: string;
+        hint: string;
+    }>;
+    blastScale: {
+        name: string;
+        hint: string;
+    };
+    layers: Record<'rings', string>;
+    metrics: Record<'gas' | 'clock' | 'phase', string>;
+    phases: Record<'rest' | 'leaking' | 'torch' | 'primed' | 'exploded', string>;
+    rings: {
+        lethal: string;
+        injury: string;
+    };
+    triggers: Record<'shot' | 'fire' | 'explosion', string>;
+    things: Record<string, string>;
+    verdicts: {
+        wall_pieces: string;
+        lost_parts: string;
+        dead: string;
+        hurt: string;
+        unhurt: string;
+        wall_broken: string;
+        wall_cracked: string;
+        wall_intact: string;
+        burning: string;
+        standing: string;
+    };
+    log: {
+        leak_shot: string;
+        leak_valve: string;
+        valve_closed: string;
+        valve_closed_late: string;
+        primed: string;
+        jet_lit: string;
+        jet_lit_by: string;
+        lighter_none: string;
+        lighter_lit: string;
+        fire_set: string;
+        heating: string;
+        explode: string;
+        shell: string;
+        shell_landed: string;
+        residual: string;
+        aftermath_person: string;
+        aftermath_wall: string;
+        aftermath_object: string;
+        reset: string;
+        scale: string;
+        no_room: string;
+        shoot: string;
+        no_vessel: string;
+    };
+    sheet: {
+        kicker: string;
+        title: string;
+        body: string;
+        facts: Record<'energy' | 'lethal' | 'injury' | 'gas' | 'mass' | 'torch' | 'shot_chain' | 'fire_chain', string>;
+        steps: Array<{
+            at: string;
+            text: string;
+        }>;
+        segments: Record<'jet' | 'torch' | 'blast', string>;
+        note: string;
+    };
+    scenarios: {
+        shot: string;
+        shot_leak: string;
+        shot_ignite: string;
+        shot_explode: string;
+        shot_zombie: string;
+        shot_survivor: string;
+        shot_wall: string;
+        valve: string;
+        valve_leak: string;
+        valve_quiet: string;
+        valve_lit: string;
+        valve_explode: string;
+        fire: string;
+        fire_explode: string;
+        chain: string;
+        chain_explode: string;
+        push_p13: string;
+        push_grenade: string;
+        push_found: string;
+        push_told: string;
+        push_outward: string;
+        push_falloff: string;
+        push_person: string;
+        push_heavy: string;
+    };
+}
+declare const EXPLOSIVES_TEXT: Record<string, ExplosivesText>;
+declare const explosivesTextOf: (locale: string) => ExplosivesText;
+
+/** Id of the explosives module (`?area=explosives_area` opens it). */
+declare const EXPLOSIVES_AREA_ID = "explosives_area";
+/** The parts of a part state the bench reads (structural: `PartState` of the destruction world fits). */
+interface PartView {
+    readonly liters?: number;
+    readonly temperature: number;
+    readonly status: string;
+    readonly holes: ReadonlyArray<{
+        readonly diameter: number;
+        readonly through: boolean;
+    }>;
+    readonly cracks: readonly unknown[];
+    readonly burning: boolean;
+}
+/** What the explosives module needs from the room it drives (structural: the `TestRoom` of game-test-room fits). */
+interface ExplosivesRoom {
+    readonly world: {
+        readonly time: number;
+        ids(): string[];
+        on(type: '*', fn: (event: DestructionEvent) => void): () => void;
+        hit(objectId: string, hit: Hit): unknown;
+        vent(objectId: string, partId: string, opening?: {
+            point?: Vec3$1;
+            normal?: Vec3$1;
+            diameter?: number;
+        }): boolean;
+        seal(objectId: string, partId: string): number;
+        part(objectId: string, partId: string): PartView | null;
+        state(objectId: string): {
+            readonly parts: readonly (PartView & {
+                readonly id: string;
+                readonly hp: number;
+                readonly maxHp: number;
+            })[];
+        } | null;
+    };
+    readonly renderer: {
+        impulse(objectId: string, impulse: Vec3$1, point?: Vec3$1): void;
+    };
+    readonly vfx: {
+        spawn(kind: string, point: Vec3$1, velocity: Vec3$1, options?: {
+            color?: number;
+            size?: number;
+            life?: number;
+            alpha?: number;
+        }): void;
+        burst(kind: string, point: Vec3$1, normal: Vec3$1, count: number, speed?: number): void;
+        fire(options: {
+            point: Vec3$1;
+            radius: number;
+            life: number;
+        }): number;
+        stop(handle: number): void;
+    };
+    spawned(): ReadonlyArray<{
+        readonly objectId: string;
+        readonly itemId: string;
+        readonly root: unknown;
+    }>;
+    openArea(group: string): unknown;
+    clear(): void;
+    spawn(itemId: string, position?: Vec3$1, rotationY?: number): {
+        readonly objectId: string;
+        readonly itemId: string;
+        readonly root: unknown;
+    };
+    setTool(weaponId: string): void;
+    waitUntilReady(maxSeconds?: number): number;
+    look(position: Vec3$1, target: Vec3$1): void;
+    use(hold?: number): void;
+    on(type: 'spawn', fn: (data: unknown) => void): () => void;
+}
+/** The bench of the explosives area as the module and its scenarios see it. */
+interface ExplosivesBench {
+    readonly room: ExplosivesRoom | undefined;
+    readonly def: ExplosiveDef;
+    /** The strength multiplier now (the next cylinder laid takes it). */
+    blastScale(): number;
+    /** Called by the module's `area`: the cylinders spawned from now on belong to the area (they get their rings). */
+    areaOpened(): void;
+    controls(): ModuleControl[];
+    layers(): ModuleLayer[];
+    metrics(): ModuleMetric[];
+    attach(host: ModuleHost): () => void;
+    /** The actions of the bench, by the id of their button. Each answers whether it did something. */
+    readonly actions: Readonly<Record<'shoot' | 'valve' | 'light' | 'fire' | 'reset', () => boolean>>;
+    /** The cylinder of the scene (the first one alive), with what the bench knows about it. */
+    vessel(): VesselView | undefined;
+    /** The wall of the scene, the zombie and the survivor, as the aftermath reads them. */
+    /** The last explosion the host told (a part of the world or a thrown explosive): where, how strong and how far; undefined before the first, and after the area is cleared. */
+    lastBlast(): {
+        readonly point: Vec3$1;
+        readonly energy: number;
+        readonly radius: number;
+        readonly cause: string;
+        readonly explosive?: string;
+    } | undefined;
+    witnesses(): Array<{
+        kind: 'person' | 'wall' | 'object';
+        id: string;
+        itemId: string;
+        distance: number;
+        alive?: boolean;
+        vitality?: number;
+        broken?: number;
+        marks?: number;
+        pieces?: number;
+    }>;
+}
+interface VesselView {
+    readonly objectId: string;
+    /** World time of the first leak, of the jet catching fire and of the blast (seconds); undefined until they happen. */
+    readonly leakAt: number | undefined;
+    readonly litAt: number | undefined;
+    readonly explodedAt: number | undefined;
+    readonly cause: 'shot' | 'valve' | undefined;
+    readonly valveOpen: boolean;
+    readonly lit: boolean;
+    readonly exploded: boolean;
+    readonly point: Vec3$1 | undefined;
+}
+interface ExplosivesBenchOptions {
+    readonly locale: string;
+    readonly text: ExplosivesText;
+    readonly def: ExplosiveDef;
+    readonly scene: {
+        readonly cylinder: Vec3$1;
+    };
+    readonly room: ExplosivesRoom | undefined;
+    readonly blastScale: number;
+    readonly profile: {
+        readonly visualRadius?: number;
+        readonly residualFires?: ReadonlyArray<{
+            readonly radius: number;
+            readonly life: number;
+        }>;
+    } | undefined;
+}
+/**
+ * The state and the actions of the explosives area: it follows the world's events of the cylinder (leak, primed, explode), tells each phase in the room's log, plays the torch and the flight
+ * of the shell (the Laboratório de Explosões, `SC.p13`) and drives the destruction world for the bench actions. The module wraps it in a `TestableModule`.
+ */
+declare function createExplosivesBench(options: ExplosivesBenchOptions): ExplosivesBench;
+
+/** Where the things of the scene stand (metres, in the room's world; the brick wall is the room's own at z = -11). The kitchen corner is against the wall; the player looks at it from about 6 m. */
+interface ExplosivesScene {
+    /** Item ids and positions of the kitchen furniture (items of the household module); one that the room does not know is left out. */
+    readonly furniture: ReadonlyArray<{
+        readonly item: string;
+        readonly at: Vec3$1;
+        readonly rotationY?: number;
+    }>;
+    /** The cylinder. */
+    readonly cylinder: Vec3$1;
+    /** The zombie (about 3 m from the cylinder) and the survivor (about 8 m): item ids of the characters module. */
+    readonly zombie: {
+        readonly item: string;
+        readonly at: Vec3$1;
+    };
+    readonly survivor: {
+        readonly item: string;
+        readonly at: Vec3$1;
+    };
+    /** The player's eye (about 6 m from the cylinder: outside the 5 m lethal ring, the lamp rig of the weather module is behind it). */
+    readonly eye: Vec3$1;
+}
+/** The kitchen corner of the default scene: fridge, cabinet, the cylinder and the stove side by side against the wall, a table 2 m away. */
+declare const DEFAULT_EXPLOSIVES_SCENE: ExplosivesScene;
+interface ExplosivesTestModuleOptions {
+    /** `en` or `pt-BR` (default). */
+    locale?: string;
+    /** The arsenal to read the P13 from (default `createArsenal` with the locale). */
+    arsenal?: Arsenal;
+    /** The room the module drives: its destruction world, effects and tools. Without it the module still lays the area and the bench shows, but the actions only say they need the room. */
+    room?: ExplosivesRoom;
+    /** Overrides of the default scene (see `ExplosivesScene`). */
+    scene?: Partial<ExplosivesScene>;
+    /** Strength multiplier the bench starts at (default 1: the arsenal's numbers; a game value, see the README). */
+    blastScale?: number;
+}
+/**
+ * The explosives test area as a `TestableModule`: the P13 cooking gas cylinder in a kitchen corner against a brick wall, with furniture, a zombie at 3 m, a survivor at 8 m and rings on the floor at the
+ * lethal and injury radii. The bench shoots it, opens its valve, lights it with a lighter, throws it in a fire or restarts the scene; every phase is told in the room's log in the locale of the room.
+ * The module reads the sequence (the torch delay, the gas, the flight of the shell) from the arsenal def of `propane_p13` and the blast from its `chain`, so a game changes them with `ArsenalOptions.patch.explosives`.
+ */
+declare function createExplosivesTestModule(options?: ExplosivesTestModuleOptions): TestableModule & {
+    readonly bench: ReturnType<typeof createExplosivesBench>;
+};
+
 /** Prefix of the item ids of the explosives that sit in the world (`world_fuel_barrel`). */
 declare const WORLD_EXPLOSIVE_PREFIX = "world_";
+/** Name of the mesh of the brass valve on the P13 model (the team's `botijao`: the 0xb8913a cylinder on the neck). */
+declare const P13_VALVE_MESH = "valve";
 /** The ids of the explosives of the arsenal that the area puts in the world. */
 declare const WORLD_EXPLOSIVE_IDS: readonly string[];
+/** What the bench (or a game) changes about a world explosive without touching the arsenal: the multiplier of its energy and reach, read each time one is spawned. */
+interface WorldExplosiveOptions {
+    /** Multiplies `energy`, `lethalRadius` and `injuryRadius` of the explosive (default 1: the arsenal's numbers). It is a game value, not a physical table; the arsenal's own place for it is `ArsenalOptions.patch.explosives`. */
+    readonly scale?: () => number;
+}
+/** Where the valve is on a spawned cylinder, in the world (the centre of the brass mesh), or undefined when the object has none. */
+declare const worldExplosiveValve: (THREE: typeof THREE_NS, root: THREE_NS.Object3D) => Vec3$1 | undefined;
+/**
+ * What is left of a world explosive after the blast, as an object to fly: the same model, worn and darkened (the torn shell of the P13 in the Laboratório de Explosões, `SC.p13`),
+ * with no part mapped. Undefined for the explosives that have no model of the team.
+ */
+declare const worldExplosiveShell: (THREE: typeof THREE_NS, defId: string) => THREE_NS.Group | undefined;
 /** An explosive of the arsenal standing in the world: it goes off by a bullet, fire or another blast, after the delay its `chain` gives. */
-declare const worldExplosiveItem: (def: ExplosiveDef, name: string) => TestableItem | undefined;
+declare const worldExplosiveItem: (def: ExplosiveDef, name: string, options?: WorldExplosiveOptions) => TestableItem | undefined;
+
+/** What a host asks for a thrown or set down explosive: the weapon in the hand, the explosive it carries and how it is used (`rocket`, `grenade`, `molotov`, `charge`). */
+interface ProjectileQuery {
+    readonly weapon: string;
+    readonly explosive?: string | undefined;
+    readonly kind: string;
+}
+/** The model of a projectile and the axis along its length. */
+interface ProjectileModel {
+    readonly model: THREE_NS.Object3D;
+    readonly axis: [number, number, number];
+}
+/**
+ * The model of what a weapon throws or fires, drawn by the same code as the weapon itself: the round of a rocket launcher (the RPG-7's PG-7V, the Carl Gustaf's 84 mm round, the rocket of
+ * the disposable tubes), long axis +x. Answers `null` where the gallery has no model: the throwables (grenades, molotovs, dynamite, C4, the Claymore) and the grenade launchers are
+ * still the plain props of `weaponProp`, and a host keeps its primitive for them.
+ */
+declare function projectileModel(THREE: typeof THREE_NS, query: ProjectileQuery): ProjectileModel | null;
 
 /** The effect ids a weapon of a case type shows when it is seen from outside: its muzzle flash and its ejected case (the host's catalogue names them). */
 interface WorldEffectIds {
@@ -754,4 +1139,4 @@ declare function rigUnderbarrel(THREE: typeof THREE_NS, model: WeaponModel, def:
  */
 declare function rigStock(THREE: typeof THREE_NS, model: WeaponModel, def: Pick<WeaponDef, 'stock' | 'dimensions'>): void;
 
-export { ARCHETYPE_MODELS, ATTACHMENT_MODELS, type AttachmentBuildContext, type AttachmentModel, type AttachmentModelBuilder, type AttachmentModelRegistry, type AttachmentRig, BODY_ACTIONS, CLASS_REFERENCE_ENERGY, COUNTER_ITEM_ID, type CartridgeShape, type ClipContext, DEFAULT_ENERGY_CURVE, DEFAULT_THUMBNAIL_BASE, type DistanceCurve, type EnergyCurve, type FitAttachmentOptions, type FxLayers, GAME_DISTANCE_CURVE, GAME_SOUND_CLASSES, type LaserRaycast, MECHANICAL_SOUNDS, MODEL_ENTRIES, MOUNTED_M134_ITEM_ID, type MechanicalSoundId, type ModelEntry, type ModelFamily, type ModelKit, type ModelMaterials, type ModelOptions, type ModelParts, type MountFrame, type ShotExtras, type ShotSound, type ShotSoundClass, type ShotSoundInput, type ShotSoundOptions, type SoundClassDef, type SoundStep, WEAPON_ITEM_PREFIX, WEAPON_THUMBNAILS, WORLD_EFFECTS, WORLD_EXPLOSIVE_IDS, WORLD_EXPLOSIVE_PREFIX, type WeaponAudio, type WeaponAudioOptions, type WeaponFx, type WeaponFxOptions, type WeaponModel, type WeaponProp, type WeaponThumbnailEntry, type WeaponsTestModuleOptions, type WorldEffectIds, type WorldEffectsOptions, applyCondition, buildCartridge, buildCasing, buildProp, buildRound, buildToolClips, buildWeaponModel, buildWeaponModelById, cartridgeShape, computeShotSound, createWeaponAudio, createWeaponFx, createWeaponsTestModule, createWorldEffects, deriveFrames, fitAttachmentModels, hasWeaponModel, mechanicalSoundOf, modelKit, mountFrame, partRegistry, rigStock, rigUnderbarrel, weaponProp, weaponThumbnailCredit, weaponThumbnailUrl, weaponsLayout, worldExplosiveItem };
+export { ARCHETYPE_MODELS, ATTACHMENT_MODELS, type AttachmentBuildContext, type AttachmentModel, type AttachmentModelBuilder, type AttachmentModelRegistry, type AttachmentRig, BODY_ACTIONS, CLASS_REFERENCE_ENERGY, COUNTER_ITEM_ID, type CartridgeShape, type ClipContext, DEFAULT_ENERGY_CURVE, DEFAULT_EXPLOSIVES_SCENE, DEFAULT_THUMBNAIL_BASE, type DistanceCurve, EXPLOSIVES_AREA_ID, EXPLOSIVES_TEXT, type EnergyCurve, type ExplosivesRoom, type ExplosivesScene, type ExplosivesTestModuleOptions, type ExplosivesText, type FitAttachmentOptions, type FxLayers, GAME_DISTANCE_CURVE, GAME_SOUND_CLASSES, type LaserRaycast, MECHANICAL_SOUNDS, MODEL_ENTRIES, MOUNTED_M134_ITEM_ID, type MechanicalSoundId, type ModelEntry, type ModelFamily, type ModelKit, type ModelMaterials, type ModelOptions, type ModelParts, type MountFrame, P13_VALVE_MESH, type ProjectileModel, type ProjectileQuery, type ShotExtras, type ShotSound, type ShotSoundClass, type ShotSoundInput, type ShotSoundOptions, type SoundClassDef, type SoundStep, WEAPON_ITEM_PREFIX, WEAPON_THUMBNAILS, WORLD_EFFECTS, WORLD_EXPLOSIVE_IDS, WORLD_EXPLOSIVE_PREFIX, type WeaponAudio, type WeaponAudioOptions, type WeaponFx, type WeaponFxOptions, type WeaponModel, type WeaponProp, type WeaponThumbnailEntry, type WeaponsTestModuleOptions, type WorldEffectIds, type WorldEffectsOptions, type WorldExplosiveOptions, applyCondition, buildCartridge, buildCasing, buildProp, buildRound, buildToolClips, buildWeaponModel, buildWeaponModelById, cartridgeShape, computeShotSound, createExplosivesTestModule, createWeaponAudio, createWeaponFx, createWeaponsTestModule, createWorldEffects, deriveFrames, explosivesTextOf, fitAttachmentModels, hasWeaponModel, mechanicalSoundOf, modelKit, mountFrame, partRegistry, projectileModel, rigStock, rigUnderbarrel, weaponProp, weaponThumbnailCredit, weaponThumbnailUrl, weaponsLayout, worldExplosiveItem, worldExplosiveShell, worldExplosiveValve };