@adatechnology/game-weapons 0.0.0-stage → 0.1.1

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/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @adatechnology/game-weapons
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Engine-agnostic weapons and ammunition. Real calibres as data (muzzle energy from `0.5 × m × v²`), generic real-world weapon archetypes (no brands),
+and a tiny deterministic runtime: magazines, fire modes, reload, spread and bloom, shotgun pellets, recoil, noise, plus melee, flame, heat, throwables,
+tools and a fire extinguisher. A trigger pull returns plain-data `Shot`s and `Use`s, so any damage model can consume them. It knows nothing about any game.
+
+Units: metres, seconds, joules, mm (calibre diameter), grams (bullet mass), m/s, degrees, °C. Every random choice comes from a seeded generator, so the
+same seed gives the same shots on every machine.
+
+Contracts live in [`@adatechnology/game-contracts`](../game-contracts); the types are re-exported here, so existing imports keep working.
+
+## Install
+
+```sh
+pnpm add @adatechnology/game-weapons
+```
+
+A plain `<script src=".../dist/index.global.js">` exposes the `GameWeapons` global. No runtime dependencies.
+
+## Usage
+
+```ts
+import { createArsenal, DEFAULT_LOADOUT } from '@adatechnology/game-weapons'
+
+const arsenal = createArsenal({ seed: 42, locale: 'pt-BR' })
+const gun = arsenal.create('shotgun_pump_12', { reserve: 24 })
+arsenal.name('shotgun_pump_12') // "espingarda de repetição calibre 12"
+
+// every frame
+gun.update(dt)
+if (mouseDown) {
+  const r = gun.trigger(cameraPos, cameraDir, dt, mouseHeldSinceLastFrame)
+  for (const shot of r.shots) {
+    // feed the shots to @adatechnology/game-destruction
+    world.shoot(shot.origin, shot.direction, shot.energy, shot.caliber)
+  }
+  for (const use of r.uses) handleUse(use) // melee swing, flame tick, throw, tool...
+  camera.kick(...r.recoil)
+  horde.hear(cameraPos, r.noise)
+} else gun.release()
+if (reloadKey) gun.reload()
+```
+
+Semi / single / pump / bolt weapons fire once per pull: call `trigger(..., held = true)` while the button stays down and they fire only the first
+time (status `cooldown` afterwards) until `release()`, or pass `held = false` for every new click. `auto` fires at the cyclic rpm while held (several
+shots per `dt` if needed). `burst` emits its rounds together in one call. Reloading is never automatic: the host calls `reload()`; a tube-fed weapon
+loads one round per `reload` seconds and the trigger interrupts it. `trigger(dt)` and `update(dt)` can both be called in the same frame without
+counting `dt` twice.
+
+Non-firearms: `flame`/`heat` drain `fuelPerSecond × dt` of fuel (`no_fuel` when dry), `tool` ticks with `duration: dt`, `extinguisher` spends its
+charge in seconds, `throwable` throws once per pull (`velocity = direction × throwSpeed` plus a small upward arc, three by default), `melee` swings at
+its rpm, `hand` produces one `hand` use per pull.
+
+## Data
+
+`CALIBERS` (`src/data/calibers.json`): `22lr`, `9x19`, `38spl`, `357mag`, `40sw`, `45acp`, `380acp`, `5_56x45`, `7_62x39`, `7_62x51`, `338lapua`, `50bmg`,
+`12ga_00buck` (9 pellets), `12ga_slug`, `12ga_birdshot` (90 pellets), `20ga_buck`, `arrow`, `crossbow_bolt`. Muzzle energy is per projectile (per pellet
+for shotguns), e.g. 9×19 ~500 J, 5.56 ~1750 J, .308 ~3500 J, .50 BMG ~18 kJ, 00 buck ~300 J per pellet.
+
+`WEAPONS` (`src/data/weapons.json`):
+
+| Category | Ids |
+|---|---|
+| Firearms | `pistol_9mm`, `pistol_45`, `pistol_22`, `revolver_357`, `revolver_38`, `smg_9mm`, `carbine_22`, `rifle_5_56`, `rifle_7_62x39`, `rifle_bolt_308`, `sniper_338`, `anti_materiel_50`, `shotgun_pump_12`, `shotgun_double_12`, `shotgun_semi_12`, `bow_compound`, `crossbow` |
+| Melee | `hammer`, `sledgehammer`, `baseball_bat`, `crowbar`, `machete`, `axe`, `knife`, `fists` |
+| Fire and heat | `lighter`, `flamethrower`, `cutting_torch`, `blowtorch`, `molotov` |
+| Explosives | `frag_grenade`, `pipe_bomb` |
+| Tools | `screwdriver`, `wrench`, `pry_bar`, `hacksaw`, `utility_knife`, `claw_hammer`, `extinguisher`, `hand` |
+
+`DEFAULT_LOADOUT` lists a starter kit of 19 ids. Pass `calibers` / `weapons` to `createArsenal` to add or override entries by id.
+
+## API
+
+- `createArsenal(options?)` returns an `Arsenal`: `calibers`, `weapons` (maps), `create(id, { seed?, reserve? })` (unknown id throws), `muzzleEnergy(caliberId, barrel?)`,
+  `name(id)` (weapon, fire mode or category, translated), `list(category?)`.
+- `WeaponState`: `def`, `caliber`, `ammo`, `capacity`, `reserve`, `mode`, `reloading`, `spread`, `trigger(origin, direction, dt, held?, source?)`, `release()`,
+  `reload()`, `cycleMode()`, `update(dt)`, `refill()`.
+- `Shot`: `origin`, `direction`, `energy` (J), `caliber` (mm), `caliberId`, `speed`, `energyAt(distance)` (energy × speed factor², drag per 100 m), `pellet`, `weapon`, `source`.
+- `Use`: `melee`, `flame`, `heat`, `throw`, `tool`, `extinguish`, `hand`. `TriggerResult`: `shots`, `uses`, `status` (`ok`, `empty`, `reloading`, `cooldown`, `no_fuel`, `safe`), `recoil`, `noise`.
+- `muzzleEnergy(caliber, barrel?)`, `CALIBERS`, `WEAPONS`, `DEFAULT_LOADOUT`, `locales`, `resolveStrings`.
+
+Locales: `en` and `pt-BR` (`locale` option; unknown falls back to `en`). Calibre labels are technical names and are not translated.
+
+## Português
+
+Armas e munição independentes de engine: calibres reais como dados (energia de boca = `0,5 × m × v²`), arquétipos genéricos de armas (sem marcas) e um
+runtime determinístico (carregador, modos de tiro, recarga, dispersão, chumbos de espingarda, recuo, ruído), além de corpo a corpo, chama, calor,
+arremessáveis, ferramentas e extintor. Cada disparo vira um `Shot` (energia em joules, calibre em mm, direção) que se passa direto para
+`world.shoot(origem, direção, shot.energy, shot.caliber)` do `@adatechnology/game-destruction`. Use `createArsenal({ locale: 'pt-BR' })` para os nomes
+em português (`arsenal.name('rifle_5_56')` devolve "fuzil 5,56"). A recarga nunca é automática; o jogo chama `reload()`.

package/dist/index.d.ts

@@ -0,0 +1,214 @@
+import { Vec3, Shot, Use } from '@adatechnology/game-contracts';
+export { Shot, Use, Vec3 } from '@adatechnology/game-contracts';
+
+/**
+ * Public types of @adatechnology/game-weapons.
+ *
+ * Weapons and ammunition as data plus a tiny runtime: a `WeaponState` holds the magazine, chamber, fire mode, heat and recoil; `trigger()` turns
+ * a trigger pull into `Shot`s (one per pellet) with muzzle energy, calibre, direction with spread, and range falloff. Shots are plain data, so
+ * any damage model can consume them (@adatechnology/game-destruction takes `energy` and `caliber` as is). Melee, flame, heat, throwables and
+ * tools use the same shape so a test room or a game can treat every tool in the hand the same way.
+ *
+ * Units: metres, seconds, joules, millimetres for calibres, grams for bullets, metres per second for speeds, °C.
+ * Every random choice (spread) comes from the state's seed: same inputs, same shots on every machine.
+ */
+
+/** snake_case calibre id, e.g. `9x19`, `5_56x45`, `12ga_00buck`. */
+type CaliberId = string;
+/** snake_case weapon id. */
+type WeaponId = string;
+interface CaliberDef {
+    id: CaliberId;
+    /** Display label, e.g. `9×19 mm`, `12 ga 00 buck`. Not translated (it is a technical name). */
+    label: string;
+    /** Bullet (or each pellet) diameter in mm. */
+    diameter: number;
+    /** Bullet or pellet mass in grams. */
+    bulletGrams: number;
+    /** Typical muzzle speed from a reference barrel, m/s. Muzzle energy = 0.5 × mass × speed². */
+    muzzleSpeed: number;
+    /** Pellets per shell (shotgun), default 1. */
+    pellets?: number;
+    /** Speed lost per 100 m as a fraction (default 0.1 rifle, 0.2 pistol, 0.45 buckshot). */
+    dragPer100m?: number;
+    /** Armour-piercing or hollow-point flavour (a damage model may use it). */
+    kind?: 'fmj' | 'hp' | 'ap' | 'buck' | 'slug' | 'birdshot' | 'rimfire' | 'arrow' | 'bolt';
+    tags?: string[];
+}
+type FireMode = 'single' | 'semi' | 'burst' | 'auto' | 'pump' | 'bolt' | 'lever' | 'break';
+type WeaponCategory = 'pistol' | 'revolver' | 'smg' | 'rifle' | 'carbine' | 'sniper' | 'shotgun' | 'bow' | 'crossbow' | 'melee_blunt' | 'melee_blade' | 'flame' | 'heat' | 'throwable' | 'tool' | 'extinguisher' | 'hand';
+/** What using the item does. Firearms produce ballistic shots; the rest produce one `Use` of their kind. */
+type WeaponAction = {
+    kind: 'firearm';
+    caliber: CaliberId;
+    /** Rounds per minute (cyclic for auto, practical for the rest). */
+    rpm: number;
+    modes: FireMode[];
+    /** Rounds in the burst mode (default 3). */
+    burst?: number;
+    magazine: number;
+    /** Seconds to reload a full magazine (tube-fed: per round, see `perRound`). */
+    reload: number;
+    perRound?: boolean;
+    /** Barrel speed factor vs. the calibre reference (short barrel 0.9, long 1.05), default 1. */
+    barrel?: number;
+    /** Base spread in degrees (cone half-angle) and extra degrees per consecutive shot (bloom), with recovery per second. */
+    spreadDeg: number;
+    bloomDeg?: number;
+    recoveryDegPerS?: number;
+    /** Pellet spread for shotguns in degrees (default 3). */
+    pelletSpreadDeg?: number;
+    /** Camera kick per shot in degrees (pitch, yaw jitter). */
+    recoil: [number, number];
+    /** Effective range in metres (shots past it keep going with drag; the host may cut them). */
+    range: number;
+    /** Audible distance in metres (a horde game uses it to attract zombies). */
+    noise: number;
+} | {
+    kind: 'melee';
+    damage: 'blunt' | 'slash';
+    energy: number;
+    radius: number;
+    reach: number;
+    rpm: number;
+    noise: number;
+    stamina?: number;
+} | {
+    kind: 'flame';
+    temperature: number;
+    radius: number;
+    range: number;
+    fuelPerSecond: number;
+    fuel: number;
+    cone?: boolean;
+    noise: number;
+} | {
+    kind: 'heat';
+    temperature: number;
+    radius: number;
+    range: number;
+    fuelPerSecond: number;
+    fuel: number;
+    noise: number;
+} | {
+    kind: 'throwable'; /** Throwables carried (default 3). */
+    count?: number;
+    energy: number;
+    radius: number;
+    fuse: number;
+    throwSpeed: number;
+    fire?: {
+        temperature: number;
+        radius: number;
+        seconds: number;
+    };
+    noise: number;
+} | {
+    kind: 'tool';
+    tool: 'screwdriver' | 'wrench' | 'pry_bar' | 'saw' | 'cutting_torch' | 'knife' | 'hammer';
+    reach: number;
+    noise: number;
+} | {
+    kind: 'extinguisher';
+    range: number;
+    coolC: number;
+    charge: number;
+    noise: number;
+} | {
+    kind: 'hand';
+    reach: number;
+};
+interface WeaponDef {
+    id: WeaponId;
+    /** Generic real-world description used as the default name, e.g. `9 mm service pistol`. Hosts translate with the locale or rename. */
+    name?: string;
+    category: WeaponCategory;
+    action: WeaponAction;
+    /** Mass in kg (carry weight, and thrown melee weapons). */
+    mass: number;
+    tags?: string[];
+}
+interface TriggerResult {
+    /** Shots fired this call (firearms). */
+    shots: Shot[];
+    /** Uses this call (everything else). */
+    uses: Use[];
+    /** `ok`, or why nothing happened. */
+    status: 'ok' | 'empty' | 'reloading' | 'cooldown' | 'no_fuel' | 'safe';
+    /** Camera kick to apply, degrees [pitch, yaw]. */
+    recoil: [number, number];
+    /** Audible radius of what happened, metres (0 when nothing). */
+    noise: number;
+}
+interface WeaponState {
+    readonly def: WeaponDef;
+    readonly caliber: CaliberDef | null;
+    /** Rounds in the magazine, fuel or charge left. */
+    readonly ammo: number;
+    readonly capacity: number;
+    /** Rounds in reserve (the host fills it from the inventory). */
+    reserve: number;
+    mode: FireMode;
+    readonly reloading: boolean;
+    /** Current spread in degrees (base + bloom). */
+    readonly spread: number;
+    /**
+     * Pull or hold the trigger for `dt` seconds from `origin` towards `direction`. `held` = the trigger stays down (auto fire, continuous
+     * flame); a new pull with `held: false` fires semi/single once.
+     */
+    trigger(origin: Vec3, direction: Vec3, dt: number, held?: boolean, source?: string): TriggerResult;
+    release(): void;
+    reload(): boolean;
+    cycleMode(): FireMode;
+    /** Advance reload, cooldown and spread recovery. */
+    update(dt: number): void;
+    /** Fill the magazine and reserve (test rooms). */
+    refill(): void;
+}
+interface ArsenalOptions {
+    /** Extra or overriding calibres and weapons (merged by id over `CALIBERS` and `WEAPONS`). */
+    calibers?: CaliberDef[];
+    weapons?: WeaponDef[];
+    seed?: number;
+    locale?: string;
+}
+interface Arsenal {
+    readonly calibers: ReadonlyMap<CaliberId, CaliberDef>;
+    readonly weapons: ReadonlyMap<WeaponId, WeaponDef>;
+    /** Make a runtime state for a weapon (each holder gets its own). Unknown id throws. */
+    create(id: WeaponId, options?: {
+        seed?: number;
+        reserve?: number;
+    }): WeaponState;
+    /** Muzzle energy of a calibre (optionally with a barrel factor). */
+    muzzleEnergy(caliber: CaliberId, barrel?: number): number;
+    /** Translated name of a weapon / calibre category / fire mode. */
+    name(id: WeaponId): string;
+    list(category?: WeaponCategory): WeaponDef[];
+}
+
+/** Muzzle energy in joules of ONE projectile (a bullet, or one pellet): 0.5 × mass × speed², speed scaled by the barrel factor. */
+declare const muzzleEnergy: (caliber: CaliberDef, barrel?: number) => number;
+
+declare const CALIBERS: CaliberDef[];
+declare const WEAPONS: WeaponDef[];
+/** A reasonable starting kit for a test room or a sandbox. */
+declare const DEFAULT_LOADOUT: WeaponId[];
+
+/** Create an arsenal: the built-in calibres and weapons merged (by id) with the ones in `options`. */
+declare const createArsenal: (options?: ArsenalOptions) => Arsenal;
+
+/** Locales shipped with the package. Unknown locales fall back to `en`. */
+type WeaponsLocale = 'en' | 'pt-BR';
+interface WeaponsStrings {
+    /** Display name of each weapon id. */
+    weapons: Record<string, string>;
+    /** Display name of each fire mode. */
+    modes: Record<string, string>;
+    /** Display name of each weapon category. */
+    categories: Record<string, string>;
+}
+declare const locales: Record<WeaponsLocale, WeaponsStrings>;
+declare const resolveStrings: (locale: string | undefined) => WeaponsStrings;
+
+export { type Arsenal, type ArsenalOptions, CALIBERS, type CaliberDef, type CaliberId, DEFAULT_LOADOUT, type FireMode, type TriggerResult, WEAPONS, type WeaponAction, type WeaponCategory, type WeaponDef, type WeaponId, type WeaponState, type WeaponsLocale, type WeaponsStrings, createArsenal, locales, muzzleEnergy, resolveStrings };