@adatechnology/game-weapons-three 0.4.1 → 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, DestructibleSpec, ToolClipSet } from '@adatechnology/game-contracts';
+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 {
@@ -607,6 +636,27 @@ declare const WORLD_EXPLOSIVE_IDS: readonly string[];
 /** 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;
 
+/** 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 {
+    readonly muzzle: string;
+    readonly casing: string;
+}
+declare const WORLD_EFFECTS: Readonly<Record<string, WorldEffectIds>>;
+interface WorldEffectsOptions {
+    readonly arsenal: Arsenal;
+    /** The case type of a weapon (`pistol`, `rifle`, `shell`, `big`, `tiny`); default from its caliber. */
+    readonly caseTypeOf?: (weapon: string) => string | undefined;
+    /** The ids by case type; default `WORLD_EFFECTS`. A game adds or changes entries. */
+    readonly ids?: Readonly<Record<string, WorldEffectIds>>;
+}
+/**
+ * The shooter's flash and ejected case for a shot the viewer sees from outside (a `shot` event that carries `origin`), played through the host's
+ * effect sink. The player's own first-person shot has no `origin` and is drawn by the weapon in the hands, so nothing doubles.
+ */
+declare function createWorldEffects(options: WorldEffectsOptions): {
+    handle(event: HostEvent, sink: EffectSink | undefined): number;
+};
+
 /** A low-poly prop: its destruction spec (box parts only) and one colour per part. */
 interface WeaponProp {
     spec: DestructibleSpec;
@@ -702,4 +752,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_EXPLOSIVE_IDS, WORLD_EXPLOSIVE_PREFIX, type WeaponAudio, type WeaponAudioOptions, type WeaponFx, type WeaponFxOptions, type WeaponModel, type WeaponProp, type WeaponThumbnailEntry, type WeaponsTestModuleOptions, applyCondition, buildCartridge, buildCasing, buildProp, buildRound, buildToolClips, buildWeaponModel, buildWeaponModelById, cartridgeShape, computeShotSound, createWeaponAudio, createWeaponFx, createWeaponsTestModule, 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_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 };