@adatechnology/game-weapons-three 0.11.3 → 0.13.0

package/README.md

@@ -9,7 +9,7 @@ The muzzle flash, the smoke, the backblast of a launched rocket and the flame je
 **On the body.** The weapon is the body's own, at its real size, in first and third person alike (spec 004: no first-person scale-down, no offset in front of the camera). `ModuleHost.holdFrame` lends the pocket of the right shoulder turned to the aim; a host with no body gets the same pocket under the camera's eye (`BODY_HOLD.eyeToPocket`). A shouldered long gun rests its stock in it (a gun with no stock slides forward so its grip is never behind the eye), a handgun or a short two-hand gun goes to mid-chest, a one-hand tool low. The grips of the hands are kept above the bottom of the view (`HAND_IN_VIEW`, up to 0.3 m of lift) and the weapon comes back from a wall (`WALL_PULL`, `contact`, up to 1.2 m); the hands follow it through `avatar.reach`, which also pulls them back from surfaces. The generic props (`box-fx`) ride the body the same way.
 **Safety (destravar).** Turning the safety on or off (the `safety` event, B in the test room) plays `safety_on` / `safety_off` on every model: the weapon cants to the right and rises a little toward the eye, the shooting hand slides up its grip so the thumb reaches the lever (`thumb_safety` in `src/data/hand-work.json`; an AK-style rifle's support hand goes over to the big lever on the right, `lever_right`), the lever flicks (when the model draws one, the `safety` part) and the weapon settles. The seconds and radians are `SAFETY_MOTION` of `src/animation/shot-clips.ts`.
 
-**Weapons the gallery did not model.** The melee weapons and tools with no gallery model (the bat, the axe, the machete, the knife, the hammer, the crowbar, the crossbow, the wrench, the extinguisher, the blowtorch...) are drawn with the team's item model of `@adatechnology/game-items-three` (Itens do Vale Cinzento), on the counters and in the hands: `buildItemWeaponModel` lays it along +x, flat, the head at +x, with an empty `handle` where the hand closes. The item is the one with the weapon's id, or the one `registerWeaponItemModel(weaponId, { item, turn, flip })` names (`wrench` → `adjustable_wrench`); `registerWeaponItemModel(id, null)` keeps the low-poly prop. Only a weapon with neither model falls back to the low-poly boxes of its category (`weaponProp`), and the kit's scene check (`tools/kit-audit/scene.mjs`) lists those as pending.
+**Weapons the gallery did not model.** The melee weapons and tools with no gallery model (the bat, the axe, the machete, the knife, the hammer, the crowbar, the crossbow, the wrench, the extinguisher, the blowtorch...) are drawn with the team's item model of `@adatechnology/game-items-three` (Itens do Vale Cinzento), on the counters and in the hands: `buildItemWeaponModel` lays it along +x, flat, the head at +x, with an empty `handle` where the hand closes. The item is the one with the weapon's id, or the one `registerWeaponItemModel(weaponId, { item, turn, flip })` names (`wrench` → `adjustable_wrench`); `registerWeaponItemModel(id, null)` keeps the low-poly prop. The host lends the item models as `items` (`createWeaponFx`, `createWeaponsTestModule`, `createExplosivesTestModule`, `buildWeaponModel`, `worldExplosiveItem`): pass `itemModels` of `@adatechnology/game-items-three` (the recommended path; the kit's preset does). Without `items` the weapons still draw with `itemModels` of `game-items-three` as before; that default is deprecated and removed in the next major. Only a weapon with neither model falls back to the low-poly boxes of its category (`weaponProp`), and the kit's scene check (`tools/kit-audit/scene.mjs`) lists those as pending.
 
 **Reload sounds.** Each step of a reload makes its noise where the clip says: the clips carry `sound` cues (`cue(t, 'sound', { id })`), so the sound follows the animation and scales with the weapon's reload time (`mag_release`, `mag_out`, `mag_insert`, `mag_seat`, `slide_release`, `charging_handle_pull/release`, `bolt_lift/pull/push/lock`, `shell_insert` once per round, `pump_back/forward`, `lever_open/close`, `cylinder_open/eject/close`, `speedloader`, `barrels_open/close`, `belt_cover_open/close`, `belt_insert`, `rocket_load/seat`, `grenade_load`, `breech_open/close`, `tube_drop/seat`). The recipes are data (`src/data/reload-sounds.json`: layers of the game-audio primitives); a profile (`soundProfileOf`: weight light/medium/heavy from the model family, steel or polymer from a list in the data) changes their pitch and level, and `createWeaponAudio(volume, { reloadCues })` replaces or adds recipes. `createWeaponFx({ onSound })` is told at each cue (the test area logs it as a `sound` entry); `WeaponFx.clips` says which reload variant is playing. `tests/reload-sounds.test.ts` checks the cue order of every weapon and kind, one recipe per cue, and the per-round sounds.
 
@@ -54,3 +54,9 @@ Cada fase conta no registro da sala, em pt-BR e en, e vira JSON no registro de c
 **Onde ajustar a força:** o multiplicador da bancada é só do teste. No jogo, energia, raios, tempos e gás ficam no arsenal: `createArsenal({ patch: { explosives: { propane_p13: { energy, lethalRadius, injuryRadius, chain: { shot, fire, explosion }, leak: { igniteDelay, liters, hissSeconds }, shell: { launchSpeed, trailSeconds } } } } })` (`ArsenalOptions.patch.explosives`). `createExplosivesTestModule({ blastScale })` muda o ponto de partida da bancada.
 
 Cenários: `explosives_p13_shot`, `explosives_p13_valve`, `explosives_p13_fire`, `explosives_p13_chain`.
+
+## Weapon props by instance
+
+`createWeaponProps({ packs, patch, remove })` makes the weapon item model overrides of its own: the shipped ones plus `packs`. `packs` is a list of objects `{ [weaponId]: WeaponItemModel | null }` (`[{ axe: { item: 'hammer' }, baseball_bat: null }]`; `null` keeps the low-poly prop).
+`patch` merges fields by weapon id (`item`, `turn`, `flip`), `remove` lists weapon ids whose override is taken out. `props.buildModel`, `props.buildItemModel` and `props.itemModelOf` read that set; `buildModeledProp`, `buildTripodMountedProp` and `createWeaponsTestModule` take it as `props`.
+The global `registerWeaponItemModel` and the rest are deprecated delegates of `defaultWeaponProps()`.