@adatechnology/game-weapons-three 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,13 +1,175 @@
-import { HostEvent, HostTool, TestableModule, AreaPlacement, DestructibleSpec } from '@adatechnology/game-contracts';
-import { Arsenal, WeaponDef } from '@adatechnology/game-weapons';
+import { HostTool, HostEvent, TestableModule, AreaPlacement, TestableItem, DestructibleSpec, ToolClipSet } from '@adatechnology/game-contracts';
+import { CaliberDef, ReloadStageId, WeaponEvent, Arsenal, ExplosiveDef, WeaponDef, CartridgeDims, CaseType, ReloadFamily } from '@adatechnology/game-weapons';
 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). */
+type SoundClassDef = readonly [cutoff: number, gain: number, seconds: number];
+/** The game names are pistola, escopeta, fuzil, rifle, impacto, carne, passo, vidro, madeira, recarga, vazio and explosao. */
+declare const GAME_SOUND_CLASSES: {
+    readonly pistol: readonly [1800, 0.9, 0.18];
+    readonly shotgun: readonly [900, 1.2, 0.35];
+    readonly rifle: readonly [1400, 1.1, 0.28];
+    readonly long_rifle: readonly [1100, 1.3, 0.45];
+    readonly impact: readonly [2500, 0.25, 0.05];
+    readonly flesh: readonly [600, 0.35, 0.08];
+    readonly step: readonly [400, 0.08, 0.05];
+    readonly glass: readonly [5000, 0.5, 0.3];
+    readonly wood: readonly [700, 0.5, 0.2];
+    readonly reload: readonly [3000, 0.15, 0.06];
+    readonly empty: readonly [4000, 0.12, 0.03];
+    readonly explosion: readonly [200, 1.6, 1.4];
+};
+/** The four classes a shot can have: the game picks one by calibre (jogo.js L68697). */
+type ShotSoundClass = 'pistol' | 'shotgun' | 'rifle' | 'long_rifle';
+/** Distance muffling of the game (jogo.js L62092, L62105): `gain / (1 + d² × gainFalloff)`, `cutoff / (1 + d × cutoffFalloff)`, silent under `minGain`. */
+type DistanceCurve = {
+    readonly gainFalloff: number;
+    readonly cutoffFalloff: number;
+    readonly minGain: number;
+};
+declare const GAME_DISTANCE_CURVE: DistanceCurve;
+/**
+ * The calibre energy (joules) scales loudness, length and brightness around the class: each factor is `base + span × k`, where k goes from 0 (50 J)
+ * to 1 (50 J × 10^spanDecades) on a log scale, divided by the same factor at the class reference energy. So the game calibres sound exactly as in
+ * the game, and a lighter or heavier calibre of the same class is quieter and brighter, or louder and duller.
+ */
+type EnergyCurve = {
+    readonly floorJ: number;
+    readonly spanDecades: number;
+    readonly gain: readonly [base: number, span: number];
+    readonly duration: readonly [base: number, span: number];
+    readonly cutoff: readonly [base: number, span: number];
+    /** The muzzle crack (high noise) and the body (low thump) follow the energy alone. */
+    readonly crackGain: readonly [base: number, span: number];
+    readonly bodyGain: readonly [base: number, span: number];
+    readonly bodyDuration: readonly [base: number, span: number];
+    readonly bodyFrequency: readonly [base: number, span: number];
+};
+declare const DEFAULT_ENERGY_CURVE: EnergyCurve;
+/** Muzzle energy of the game calibres in the SDK (9x19, 12ga_00buck × pellets, 7_62x39, 7_62x51): where a class sounds exactly as in the game. */
+declare const CLASS_REFERENCE_ENERGY: Readonly<Record<ShotSoundClass, number>>;
+type ShotSoundOptions = {
+    /** Replaces or adds sound classes (the game table is the default). */
+    readonly classes?: Readonly<Record<string, SoundClassDef>>;
+    readonly distance?: Partial<DistanceCurve>;
+    readonly energy?: Partial<EnergyCurve>;
+    readonly referenceEnergy?: Partial<Record<ShotSoundClass, number>>;
+    /** Picks the class of a shot; the default follows the game (shotgun by shell, handguns by category, then by energy). */
+    readonly classOf?: (input: ShotSoundInput, energyJ: number) => ShotSoundClass;
+    /** Class bands by energy (J): below `handgunBelowJ` a pistol, below `rifleBelowJ` a rifle, above that a long rifle. */
+    readonly bands?: {
+        readonly handgunBelowJ: number;
+        readonly rifleBelowJ: number;
+    };
+    readonly suppressor?: {
+        readonly gain: number;
+        readonly cutoff: number;
+        readonly crack: number;
+        readonly body: number;
+    };
+    readonly indoors?: {
+        readonly duration: number;
+        readonly cutoff: number;
+    };
+};
+type ShotSoundInput = {
+    /** The calibre; its energy (× pellets) is used unless `energyJ` is given. */
+    readonly caliber?: CaliberDef;
+    readonly energyJ?: number;
+    readonly category?: string;
+    /** Metres from the listener, default 0. */
+    readonly distance?: number;
+    /** Master gain of the game `sfx` (its `vol`), default 1. */
+    readonly volume?: number;
+    readonly suppressed?: boolean;
+    readonly indoors?: boolean;
+};
+type ShotSound = {
+    readonly soundClass: ShotSoundClass;
+    readonly energyJ: number;
+    /** False when the shot is under the game's `minGain` at this distance: nothing is played. */
+    readonly audible: boolean;
+    /** The main noise burst: lowpass cutoff Hz, starting gain and the seconds of the exponential tail (to 0.001). */
+    readonly cutoff: number;
+    readonly gain: number;
+    readonly duration: number;
+    /** High noise burst of the muzzle. */
+    readonly crack: {
+        readonly gain: number;
+        readonly cutoff: number;
+        readonly duration: number;
+    };
+    /** Low thump that sweeps from `frequency` to `to`. */
+    readonly body: {
+        readonly gain: number;
+        readonly frequency: number;
+        readonly to: number;
+        readonly duration: number;
+    };
+};
+/**
+ * The parameters of a gunshot, without WebAudio: the sound class and the distance muffling of the game (S2) with the calibre energy of the SDK.
+ * Pure and deterministic; the playback layer only turns it into nodes.
+ */
+declare const computeShotSound: (input: ShotSoundInput, options?: ShotSoundOptions) => ShotSound;
+
+/** One layer of a mechanical sound; `at` is seconds after the start. */
+type SoundStep = 
+/** Metal click: a short high noise plus a square tone at 0.6 × the frequency (the SDK synth, as before). */
+{
+    readonly layer: 'metal';
+    readonly at: number;
+    readonly frequency: number;
+    readonly gain: number;
+}
+/** A sound class of the game (`recarga`, `vazio`...) played at a volume. */
+ | {
+    readonly layer: 'class';
+    readonly at: number;
+    readonly soundClass: keyof typeof GAME_SOUND_CLASSES;
+    readonly volume: number;
+}
+/** Dull landing: lowpass noise. */
+ | {
+    readonly layer: 'thud';
+    readonly at: number;
+    readonly gain: number;
+    readonly frequency: number;
+};
+type MechanicalSoundId = ReloadStageId | 'dry_fire' | 'misfire' | 'feed' | 'cycle' | 'mode' | 'safety_on' | 'safety_off' | 'jam' | 'clear_start' | 'clear_end';
+/**
+ * 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).
+ */
+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). */
+declare const mechanicalSoundOf: (event: WeaponEvent) => MechanicalSoundId | undefined;
+
+/** 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 {
+    /** Seed of the noise buffer, of the start point in it and of the casing pitch: same seed, same sound. Default 1. */
+    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. */
+    readonly createContext?: () => AudioContext;
+}
 /** Sounds the weapon presentation plays. */
 interface WeaponAudio {
-    /** A shot: louder and longer the more muzzle energy (joules). */
-    shot(energyJ: number, category: string): void;
+    /** A shot: class and distance muffling of the game, loudness and body from the muzzle energy (joules). */
+    shot(energyJ: number, category: string, extras?: ShotExtras): void;
+    /** The parameters `shot` would play (pure). */
+    shotSound(input: ShotSoundInput): ShotSound;
     /** Dry click of an empty weapon. */
     click(): void;
+    /** A mechanical sound by id: a reload stage, `dry_fire`, `jam`, `safety_on`... */
+    mechanical(id: MechanicalSoundId): 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. */
+    play(soundClass: string, volume?: number, distance?: number): void;
     /** Magazine out, or the first shell in. */
     reloadStart(category: string): void;
     /** Magazine seated and the action racked. */
@@ -22,7 +184,14 @@ interface WeaponAudio {
     setVolume(volume: number): void;
     dispose(): void;
 }
-declare function createWeaponAudio(volume?: number): WeaponAudio;
+declare function createWeaponAudio(volume?: number, options?: WeaponAudioOptions): WeaponAudio;
+
+/** What the bench turns on or off in the presentation of the weapon: the ejected casings, the dropped magazines and the muzzle flash. */
+interface FxLayers {
+    casings: boolean;
+    magazines: boolean;
+    muzzleFlash: boolean;
+}
 
 interface WeaponFxOptions {
     THREE: typeof THREE_NS;
@@ -33,12 +202,27 @@ interface WeaponFxOptions {
     groundAt: (x: number, z: number) => number;
     /** Sounds (`createWeaponAudio`); null or absent: silent. */
     audio?: WeaponAudio | null;
+    /** Seed of the scatter of the effects of the gallery models. */
+    seed?: number;
+    /** The tool as it is now (barrel heat, fuel burning). */
+    tool?: () => HostTool;
+    /** Wear of the weapon: `new`, `used`, `worn` or `rusty`. */
+    condition?: string;
+    /** What is drawn: read at the moment of each event, so the bench can change it live. */
+    layers?: FxLayers;
+    /** Metres between the shooter and the listener, for the distance muffling of the shot sound (default 0). */
+    soundDistance?: () => number;
 }
+
 /** The weapon in the hands, its fire and reload motion, ejected casings and dropped magazines, and their sounds. */
 interface WeaponFx {
     /** Feed every tool event of the host, with the tool as it is after the event. */
     handle(event: HostEvent, tool: HostTool): void;
     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;
+    /** 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;
     /** Casings and magazines currently on the floor or in the air. */
@@ -46,6 +230,10 @@ interface WeaponFx {
     readonly magazines: number;
     dispose(): void;
 }
+/**
+ * The presentation of the tool in the hands. The weapons the gallery drew (`MODEL_ENTRIES`) get their model and the clips the rule's events call for
+ * (fire, cycle, jam, clear, safety, the seven reloads); the generic archetypes keep their low-poly prop.
+ */
 declare function createWeaponFx(options: WeaponFxOptions): WeaponFx;
 
 interface WeaponsTestModuleOptions {
@@ -55,14 +243,18 @@ interface WeaponsTestModuleOptions {
     arsenal?: Arsenal;
     /** Play sounds (default true; silent anyway where there is no AudioContext). */
     sound?: boolean;
+    /** Wear of the weapon in the hands, which the gallery models show in their metal: `new` (default), `used`, `worn` or `rusty`. */
+    condition?: string;
+    /** Seed of the scatter of casings and smoke (default 1). */
+    seed?: number;
 }
 /** Prefix of the item ids of the weapon props (`weapon_pistol_9mm`). */
 declare const WEAPON_ITEM_PREFIX = "weapon_";
 declare const COUNTER_ITEM_ID = "counter_weapons";
-/** Where the counters go and where each weapon lies on them: three counters on the free left side of the room, props across them. */
-declare function weaponsLayout(weaponItemIds: string[]): AreaPlacement[];
+/** Where the counters go and where each weapon lies on them: weapons side by side across the counters in order, each taking its strip, until the counter is full. */
+declare function weaponsLayout(weaponItemIds: string[], pitchOf?: (itemId: string) => number): AreaPlacement[];
 /**
- * The weapons test area as a `TestableModule` of @adatechnology/game-contracts: one prop per weapon of the arsenal on counters (aim at one and
+ * The weapons test area as a `TestableModule` of @adatechnology/game-contracts: every weapon of the arsenal on counters, the real model of each one the gallery drew (aim at one and
  * press H to equip it), targets at shooting distance, and, through `attach`, the weapon in the hands with its fire and reload motion,
  * ejected casings, dropped magazines and sounds, driven by the host's tool events.
  */
@@ -71,6 +263,13 @@ declare function createWeaponsTestModule(options?: WeaponsTestModuleOptions): Te
     readonly fx: WeaponFx | null;
 };
 
+/** Prefix of the item ids of the explosives that sit in the world (`world_fuel_barrel`). */
+declare const WORLD_EXPLOSIVE_PREFIX = "world_";
+/** The ids of the explosives of the arsenal that the area puts in the world. */
+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;
+
 /** A low-poly prop: its destruction spec (box parts only) and one colour per part. */
 interface WeaponProp {
     spec: DestructibleSpec;
@@ -85,4 +284,243 @@ declare function buildProp(THREE: typeof THREE_NS, prop: WeaponProp): THREE_NS.G
 /** The model of a weapon for the hands or a shelf: the same prop the counters show. */
 declare function buildWeaponModel(THREE: typeof THREE_NS, def: Pick<WeaponDef, 'id' | 'category' | 'mass'>): THREE_NS.Group;
 
-export { BODY_ACTIONS, COUNTER_ITEM_ID, WEAPON_ITEM_PREFIX, type WeaponAudio, type WeaponFx, type WeaponFxOptions, type WeaponProp, type WeaponsTestModuleOptions, buildProp, buildWeaponModel, createWeaponAudio, createWeaponFx, createWeaponsTestModule, weaponProp, weaponsLayout };
+/** How the gallery builders describe a weapon: the short keys of `data/models.json` (the page's own option names), all optional. */
+interface ModelOptions {
+    /** Total length and barrel length in mm, and the calibre text, as the weapons table gives them. */
+    L?: number;
+    B?: number;
+    cal?: string;
+    /** Pistol style (`glock`, `taurus`, `g2c`, `beretta`, `pt100`, `sig`, `cz`, `m1911`, `makarov`, `fiveseven`, `deagle`), slide height, grip length. */
+    st?: string;
+    h?: number;
+    gl?: number;
+    deagle?: number;
+    /** Metal and furniture finish. */
+    steel?: number;
+    stain?: number;
+    wood?: number;
+    olive?: number;
+    tan?: number;
+    /** Selector or safety mark, cyclic rate (rpm), rounds in a burst, how unreliable (`rel`). */
+    sel?: number;
+    rpm?: number;
+    burst?: number;
+    rel?: number;
+    /** Rifle layout. */
+    stock?: string;
+    stockLen?: number;
+    hg?: string;
+    hgFrac?: number;
+    hR?: number;
+    wR?: number;
+    br?: number;
+    grip?: string;
+    gripAt?: number;
+    mag?: string;
+    magLen?: number;
+    magAt?: number;
+    magMat?: string;
+    curve?: number;
+    fore?: number;
+    tubeLen?: number;
+    scope?: number;
+    brake?: number;
+    ejectBack?: number;
+    round?: number;
+    ar?: number;
+    ak?: number;
+    g3?: number;
+    charge?: number;
+    rail?: number;
+    jacket?: number;
+    gas?: number;
+    noFH?: number;
+    carry?: number;
+    bipod?: number;
+    bolt?: number;
+    lever?: number;
+    tube?: number;
+    pump?: number;
+    heat?: number;
+    /** Chambers of the revolver cylinder (default 6): the capacity of the weapon. */
+    chambers?: number;
+    bayo?: number;
+    rod?: number;
+    bands?: number;
+    shot?: number;
+    /** Launcher type: `rpg`, `m72`, `at4`, `carl`, `flame`, `flameDIY`. */
+    lt?: string;
+}
+/** The moving mechanism of a model, which picks its fire, reload and clear motion. */
+type ModelFamily = 'pistol' | 'revolver' | 'rifle' | 'semiint' | 'semi12' | 'p90' | 'belt' | 'pump' | 'lever' | 'bolt' | 'boltmag' | 'break' | 'rocket' | 'flame';
+/** The named parts a model exposes to the animation: pivots and marks inside the model, never copies. */
+interface ModelParts {
+    family: ModelFamily;
+    /** Recoil strength of the model (the page's `kick`). */
+    kick?: number;
+    /** How far the slide or bolt travels back, in metres. */
+    stroke?: number;
+    slide?: THREE_NS.Object3D;
+    bolt?: THREE_NS.Object3D;
+    boltHandle?: THREE_NS.Object3D;
+    boltHandleRest?: number;
+    mag?: THREE_NS.Object3D | null;
+    /** How far a magazine drops, and `1` for one that goes up. */
+    magDrop?: number;
+    magDir?: number;
+    trigger?: THREE_NS.Object3D;
+    hammer?: THREE_NS.Object3D;
+    lever?: THREE_NS.Object3D;
+    pump?: THREE_NS.Object3D;
+    belt?: THREE_NS.Object3D;
+    cover?: THREE_NS.Object3D;
+    crane?: THREE_NS.Object3D;
+    cylinder?: THREE_NS.Object3D;
+    chambers?: THREE_NS.Object3D[];
+    barrels?: THREE_NS.Object3D;
+    breech?: 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;
+    eject?: THREE_NS.Object3D;
+    loadPort?: THREE_NS.Object3D;
+    topLoad?: THREE_NS.Object3D;
+    /** Parts that glow with barrel heat; each owns a clone of its material. */
+    glow: THREE_NS.Mesh[];
+    /** Launchers. */
+    launcherType?: string;
+    disposable?: boolean;
+    rear?: THREE_NS.Object3D;
+    round?: THREE_NS.Object3D;
+    roundRest?: number;
+    makeRound?: () => THREE_NS.Object3D;
+    gauge?: THREE_NS.Object3D;
+}
+
+/** One weapon of the gallery as `data/models.json` keeps it: the builder, the measures in mm and the builder's options. */
+interface ModelEntry {
+    readonly builder: 'pistol' | 'revolver' | 'rifle' | 'bullpup' | 'p90' | 'break' | 'm2' | 'launcher';
+    readonly caliber: string;
+    readonly length: number;
+    readonly barrel: number;
+    readonly options: ModelOptions;
+    readonly variantOf?: string;
+}
+declare const MODEL_ENTRIES: Readonly<Record<string, ModelEntry>>;
+/**
+ * The model each generic archetype wears: the one of the first brand weapon (lowest id) that points to it with `archetype` and fires the same way (a rocket launcher that points to
+ * `shotgun_pump_12` does not lend its tube to the shotgun). An archetype nothing points to, the melee weapons and the bow keep their simple prop.
+ */
+declare const ARCHETYPE_MODELS: Readonly<Record<string, string>>;
+/** A weapon model: `root` (the page's `wr`) holds `inner` (what the builder made, fitted to the real length); `parts` are pivots and marks inside `inner`. */
+interface WeaponModel {
+    readonly id: string;
+    readonly root: THREE_NS.Group;
+    readonly inner: THREE_NS.Group;
+    readonly parts: ModelParts;
+}
+declare const hasWeaponModel: (id: string) => boolean;
+/** The gallery model of a weapon (or of the brand weapon an archetype wears, see `ARCHETYPE_MODELS`), long axis along +x, rear at the origin; undefined for melee, throwables and what nothing drew. */
+declare function buildWeaponModelById(THREE: typeof THREE_NS, id: string): WeaponModel | undefined;
+
+type Three = typeof THREE_NS;
+type Material = THREE_NS.Material;
+type Parent = THREE_NS.Object3D;
+declare const createMaterials: (THREE: Three) => {
+    metal: THREE_NS.MeshStandardMaterial;
+    steel: THREE_NS.MeshStandardMaterial;
+    steelL: THREE_NS.MeshStandardMaterial;
+    dark: THREE_NS.MeshStandardMaterial;
+    poly: THREE_NS.MeshStandardMaterial;
+    olive: THREE_NS.MeshStandardMaterial;
+    tan: THREE_NS.MeshStandardMaterial;
+    wood: THREE_NS.MeshStandardMaterial;
+    woodL: THREE_NS.MeshStandardMaterial;
+    brass: THREE_NS.MeshStandardMaterial;
+    copper: THREE_NS.MeshStandardMaterial;
+    lead: THREE_NS.MeshStandardMaterial;
+    shell: THREE_NS.MeshStandardMaterial;
+    glass: THREE_NS.MeshStandardMaterial;
+    lens: THREE_NS.MeshStandardMaterial;
+    rubber: THREE_NS.MeshStandardMaterial;
+    white: THREE_NS.MeshStandardMaterial;
+    hole: THREE_NS.MeshStandardMaterial;
+    bake: THREE_NS.MeshStandardMaterial;
+    rust: THREE_NS.MeshStandardMaterial;
+    rustD: THREE_NS.MeshStandardMaterial;
+    worn: THREE_NS.MeshStandardMaterial;
+    fire: THREE_NS.MeshBasicMaterial;
+    fire2: THREE_NS.MeshBasicMaterial;
+    flashA: THREE_NS.MeshBasicMaterial;
+    flashB: THREE_NS.MeshBasicMaterial;
+    smokeP: THREE_NS.MeshStandardMaterial;
+    /** Launcher paints. */
+    yellow: THREE_NS.MeshStandardMaterial;
+    red: THREE_NS.MeshStandardMaterial;
+    redPaint: THREE_NS.MeshStandardMaterial;
+    tape: THREE_NS.MeshStandardMaterial;
+    pipe: THREE_NS.MeshStandardMaterial;
+    green: THREE_NS.MeshStandardMaterial;
+    /** Magazine finishes named by the options. */
+    bakelite: THREE_NS.MeshStandardMaterial;
+    polyMag: THREE_NS.MeshStandardMaterial;
+};
+type ModelMaterials = ReturnType<typeof createMaterials>;
+/**
+ * The gallery's primitives on the host's three.js. Each takes the parent first and the position last as the page does (`box(parent, w, h, d, material, x, y, z, rz, ry, rx)`),
+ * so that the builders read like the originals. `roundness` is the page's `RF`: how round the next boxes are, `null` for the default.
+ */
+interface ModelKit {
+    readonly THREE: Three;
+    readonly M: ModelMaterials;
+    roundness: number | null;
+    group(): THREE_NS.Group;
+    box(parent: Parent, w: number, h: number, d: number, material: Material, x: number, y: number, z: number, rz?: number, ry?: number, rx?: number): THREE_NS.Mesh;
+    /** Cylinders along x, y and z. `radiusEnd` makes a cone. */
+    cylinderX(parent: Parent, radius: number, length: number, material: Material, x: number, y: number, z: number, segments?: number, radiusEnd?: number): THREE_NS.Mesh;
+    cylinderY(parent: Parent, radius: number, height: number, material: Material, x: number, y: number, z: number, segments?: number, radiusEnd?: number): THREE_NS.Mesh;
+    cylinderZ(parent: Parent, radius: number, length: number, material: Material, x: number, y: number, z: number, segments?: number): THREE_NS.Mesh;
+    sphere(parent: Parent, radius: number, material: Material, x: number, y: number, z: number, detail?: number): THREE_NS.Mesh;
+    torus(parent: Parent, geometry: THREE_NS.TorusGeometry, material: Material, x: number, y: number, z: number): THREE_NS.Mesh;
+    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;
+
+/** The shapes the gallery draws: rimfire, straight rimless (`p`), straight rimmed (`rimp`), bottleneck rimless (`r`), bottleneck rimmed (`rr`) and shotgun shell. */
+type CartridgeShape = 'shell' | 'rim' | 'p' | 'rimp' | 'r' | 'rr';
+/** The gallery's cartridge type of a calibre, from its case type, rim and dimensions. */
+declare function cartridgeShape(caliber: Pick<CaliberDef, 'caseType' | 'rim'>, dims: CartridgeDims): CartridgeShape;
+/** Port of the gallery's `cartridge`: the round standing on its base, in millimetres (the gallery shows it enlarged), brass case and copper or lead bullet. */
+declare function buildCartridge(kit: ModelKit, dims: CartridgeDims, shape: CartridgeShape): THREE_NS.Group;
+/** An empty case in metres, lying along x with the base at the origin: the brass the weapon throws out. */
+declare function buildCasing(kit: ModelKit, dims: CartridgeDims, shape: CartridgeShape): {
+    group: THREE_NS.Group;
+    radius: number;
+    length: number;
+};
+/** A live round in metres, lying along x with the base at the origin: what is loaded into a weapon and what a clear throws out. */
+declare function buildRound(kit: ModelKit, dims: CartridgeDims, shape: CartridgeShape): {
+    group: THREE_NS.Group;
+    radius: number;
+};
+
+/** Dresses the model for how worn the weapon is. The first call keeps the finish each mesh came with, so any condition can be put back. */
+declare function applyCondition(kit: ModelKit, model: WeaponModel, condition: string): void;
+
+/** The parts of a model by the id the clips use: `slide`, `mag`, `trigger`..., `breech_0`, `chamber_3`. */
+declare function partRegistry(parts: ModelParts): Map<string, THREE_NS.Object3D>;
+
+/** What the clips of a weapon are written from: its model (parts and mechanism), its calibre's case and how its rule reloads it. */
+interface ClipContext {
+    readonly parts: ModelParts;
+    readonly family: ModelFamily;
+    readonly caseType: CaseType;
+    readonly reloadFamily: ReloadFamily | undefined;
+}
+
+/** Every clip a weapon model brings, by the ids `toolAnimationStep` asks for (`shot`, `cycle`, `reload`, `reload_empty`, `fault_<id>`, `clear_<id>`...). */
+declare function buildToolClips(context: ClipContext): ToolClipSet;
+
+export { ARCHETYPE_MODELS, BODY_ACTIONS, CLASS_REFERENCE_ENERGY, COUNTER_ITEM_ID, type CartridgeShape, type ClipContext, DEFAULT_ENERGY_CURVE, type DistanceCurve, type EnergyCurve, type FxLayers, GAME_DISTANCE_CURVE, GAME_SOUND_CLASSES, MECHANICAL_SOUNDS, MODEL_ENTRIES, type MechanicalSoundId, type ModelEntry, type ModelFamily, type ModelKit, type ModelMaterials, type ModelOptions, type ModelParts, type ShotExtras, type ShotSound, type ShotSoundClass, type ShotSoundInput, type ShotSoundOptions, type SoundClassDef, type SoundStep, WEAPON_ITEM_PREFIX, WORLD_EXPLOSIVE_IDS, WORLD_EXPLOSIVE_PREFIX, type WeaponAudio, type WeaponAudioOptions, type WeaponFx, type WeaponFxOptions, type WeaponModel, type WeaponProp, type WeaponsTestModuleOptions, applyCondition, buildCartridge, buildCasing, buildProp, buildRound, buildToolClips, buildWeaponModel, buildWeaponModelById, cartridgeShape, computeShotSound, createWeaponAudio, createWeaponFx, createWeaponsTestModule, hasWeaponModel, mechanicalSoundOf, modelKit, partRegistry, weaponProp, weaponsLayout, worldExplosiveItem };