@adatechnology/game-weapons-three 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @adatechnology/game-weapons-three
 
-three.js presentation for `@adatechnology/game-weapons`: the real models of the arsenal, the weapon in the hands, ejected casings, sounds and the weapons test area.
+three.js presentation for `@adatechnology/game-weapons`: the real models of the arsenal, the weapon in the hands, ejected casings, sounds (recipes on `@adatechnology/game-audio`; `createWeaponAudio(volume, { engine })` plays on a shared engine) and the weapons test area.
 
 ## Licenses
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { HostTool, HostEvent, TestableModule, AreaPlacement, TestableItem, EffectSink, 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';
 
 /** One sound of the game: [lowpass cutoff Hz, gain, seconds]. Literal from the `P` table of `sfx` in the game (jogo.js L62101-L62104). */
@@ -135,12 +136,34 @@ type SoundStep =
     readonly at: number;
     readonly gain: number;
     readonly frequency: number;
+}
+/** The art scene's `sTone` (cena L1324): a tone sliding from `f` to `f2` (default `f`) in `d` seconds, at `vol`, `at` seconds after the start. */
+ | {
+    readonly layer: 'scene_tone';
+    readonly at: number;
+    readonly wave: 'sine' | 'square';
+    readonly f: number;
+    readonly f2?: number;
+    readonly d: number;
+    readonly vol: number;
+}
+/** The art scene's `sNoise` (cena L1323): filtered noise, the filter sliding to `f2` when given, `d` seconds, at `vol`. */
+ | {
+    readonly layer: 'scene_noise';
+    readonly at: number;
+    readonly type: 'lowpass' | 'highpass' | 'bandpass';
+    readonly f: number;
+    readonly f2?: number;
+    readonly q: number;
+    readonly d: number;
+    readonly vol: number;
 };
 type MechanicalSoundId = ReloadStageId | 'dry_fire' | 'misfire' | 'feed' | 'cycle' | 'mode' | 'safety_on' | 'safety_off' | 'jam' | 'clear_start' | 'clear_end' | 'stock_fold' | 'light_click' | 'attach';
 /**
  * Sounds keyed by the rule: the `reload_stage` ids of `RELOAD_STAGES`, plus the other weapon events. The click of an empty weapon and the generic
- * reload tick are the game's `vazio` and `recarga` classes (jogo.js L62101-L62104; played at L68644-L68662); the gallery (sources/armas-itens__galeria-3d-arsenal.js)
- * has no sound, so the metal layers are the SDK synth (the same `metal` used since the first version).
+ * reload tick are the game's `vazio` and `recarga` classes (jogo.js L62101-L62104; played at L68644-L68662). The Cena de Arte delivered the reload sounds
+ * (`empty` -> dry_fire, `magOut` -> magazine_out, `magIn` -> magazine_in, `bolt` -> charge, `shell` -> round_in; cena L1339-L1343), so those use them; the gallery
+ * (sources/armas-itens__galeria-3d-arsenal.js) has no sound, and the other metal layers are the SDK synth (the same `metal` used since the first version).
  */
 declare const MECHANICAL_SOUNDS: Readonly<Record<MechanicalSoundId, readonly SoundStep[]>>;
 /** Which mechanical sound a weapon event asks for, if any (`shot`, `draw` and `reload` start/end have their own handling). */
@@ -153,8 +176,14 @@ interface WeaponAudioOptions extends ShotSoundOptions {
     readonly seed?: number;
     /** Replaces or adds mechanical sounds by id. */
     readonly mechanical?: Readonly<Partial<Record<MechanicalSoundId, readonly SoundStep[]>>>;
-    /** Where the AudioContext comes from (default: the global one); lets a host or a test lend its own. */
+    /** 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;
+    /**
+     * A sound engine the host already has (one shared engine mixes, limits and pans every module the same way). The weapon sounds are registered in it
+     * and play on its `weapons` bus; `seed` gives them their own random stream, the master volume and the context stay the engine's. Without it the
+     * weapon audio makes its own engine with the game mix, no voice limit, and the master at `volume`.
+     */
+    readonly engine?: AudioEngine;
 }
 /** Sounds the weapon presentation plays. */
 interface WeaponAudio {