@adatechnology/game-weapons-three 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+import { HostEvent, HostTool, TestableModule, AreaPlacement, DestructibleSpec } from '@adatechnology/game-contracts';
+import { Arsenal, WeaponDef } from '@adatechnology/game-weapons';
+import * as THREE_NS from 'three';
+
+/** Sounds the weapon presentation plays. */
+interface WeaponAudio {
+    /** A shot: louder and longer the more muzzle energy (joules). */
+    shot(energyJ: number, category: string): void;
+    /** Dry click of an empty weapon. */
+    click(): void;
+    /** Magazine out, or the first shell in. */
+    reloadStart(category: string): void;
+    /** Magazine seated and the action racked. */
+    reloadEnd(category: string): void;
+    /** The pump or lever cycling after a shot. */
+    cycle(): void;
+    /** A casing bouncing on the floor. */
+    clink(): void;
+    /** A magazine landing on the floor. */
+    thud(): void;
+    /** Master volume, 0 to 1. */
+    setVolume(volume: number): void;
+    dispose(): void;
+}
+declare function createWeaponAudio(volume?: number): WeaponAudio;
+
+interface WeaponFxOptions {
+    THREE: typeof THREE_NS;
+    scene: THREE_NS.Scene;
+    camera: THREE_NS.Camera;
+    arsenal: Arsenal;
+    /** Height things rest on at (x, z): casings and magazines land there. */
+    groundAt: (x: number, z: number) => number;
+    /** Sounds (`createWeaponAudio`); null or absent: silent. */
+    audio?: WeaponAudio | null;
+}
+/** 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;
+    /** Weapon shown in the hands, or null. */
+    readonly inHand: string | null;
+    /** Casings and magazines currently on the floor or in the air. */
+    readonly casings: number;
+    readonly magazines: number;
+    dispose(): void;
+}
+declare function createWeaponFx(options: WeaponFxOptions): WeaponFx;
+
+interface WeaponsTestModuleOptions {
+    /** `en` or `pt-BR` (default). */
+    locale?: string;
+    /** The arsenal to lay out (default `createArsenal` with the locale). */
+    arsenal?: Arsenal;
+    /** Play sounds (default true; silent anyway where there is no AudioContext). */
+    sound?: boolean;
+}
+/** 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[];
+/**
+ * The weapons test area as a `TestableModule` of @adatechnology/game-contracts: one prop per weapon of the arsenal on counters (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.
+ */
+declare function createWeaponsTestModule(options?: WeaponsTestModuleOptions): TestableModule & {
+    readonly audio: WeaponAudio | null;
+    readonly fx: WeaponFx | null;
+};
+
+/** A low-poly prop: its destruction spec (box parts only) and one colour per part. */
+interface WeaponProp {
+    spec: DestructibleSpec;
+    colors: Record<string, number>;
+}
+/** Body actions of the arsenal: nothing to hold or lay on a counter. */
+declare const BODY_ACTIONS: ReadonlySet<string>;
+/** The prop of a weapon: low-poly parts by category, the real mass of the weapon spread over them. */
+declare function weaponProp(def: Pick<WeaponDef, 'id' | 'category' | 'mass'>, name?: string): WeaponProp;
+/** One mesh per box part, named after the part (what destruction renderers bind to), in a group with its origin on the floor. */
+declare function buildProp(THREE: typeof THREE_NS, prop: WeaponProp): THREE_NS.Group;
+/** 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 };