@adatechnology/game-weapons-three 0.8.0 → 0.9.0

package/README.md

@@ -6,6 +6,8 @@ The muzzle flash, the smoke, the backblast of a launched rocket and the flame je
 
 **Hands.** The weapon in the hands tells the host where the hands go (`host.setHandTargets`, `HandTargets` of `game-contracts`): the right on the pistol grip (the `grip` pivot of the model, else under the receiver), the left on the handguard, on the pump of a pump gun (it moves with the pump), under the right on a handgun, and to the magazine while it is changed; the generic props take the right hand on the `handle` and the left under the `head` of a long gun. Sizes come from the model, the hands shrink with a model drawn small.
 
+**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.
+
 **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.
 
 ## Geometry

package/dist/index.d.ts

@@ -1055,7 +1055,26 @@ declare const BODY_ACTIONS: ReadonlySet<string>;
 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. */
+/** How a weapon is drawn from an item model of game-items-three: the item (default the weapon id), and the turns the laying-down rule gets wrong. */
+interface WeaponItemModel {
+    /** Catalog id of the item model; the weapon id when absent. */
+    readonly item?: string;
+    /** Quarter turns about y after the long axis is laid along x (a crossbow's stock is shorter than its limbs). */
+    readonly turn?: number;
+    /** Turn it end for end after the head is found (the head is the narrow end: a knife's blade, a screwdriver's tip, an extinguisher's nozzle). */
+    readonly flip?: boolean;
+}
+/** Draws a weapon the gallery did not model with an item model of game-items-three (a game adds its own or corrects one; `null` keeps the low-poly prop). */
+declare function registerWeaponItemModel(weaponId: string, model: WeaponItemModel | null): void;
+/** The item model of game-items-three that draws a weapon (`baseball_bat`, `axe`, `fire_extinguisher`...), or undefined when there is none. */
+declare function itemModelOfWeapon(weaponId: string): string | undefined;
+/**
+ * A weapon the gallery did not draw, with the team's item model (Itens do Vale Cinzento: the bat, the axe, the machete, the extinguisher...): its long axis turned
+ * along +x and laid flat, the wider end (the head) at +x unless `registerWeaponItemModel` says otherwise, the origin at the bottom centre, an empty `handle` at the narrow end where the hand closes. Undefined
+ * when game-items-three has no model of it.
+ */
+declare function buildItemWeaponModel(THREE: typeof THREE_NS, def: Pick<WeaponDef, 'id'>): THREE_NS.Group | undefined;
+/** The model of a weapon for the hands or a shelf: the team's item model when the kit has one (`buildItemWeaponModel`), the low-poly prop the counters show otherwise. */
 declare function buildWeaponModel(THREE: typeof THREE_NS, def: Pick<WeaponDef, 'id' | 'category' | 'mass'>): THREE_NS.Group;
 
 /** The shapes the gallery draws: rimfire, straight rimless (`p`), straight rimmed (`rimp`), bottleneck rimless (`r`), bottleneck rimmed (`rr`) and shotgun shell. */
@@ -1139,4 +1158,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_EXPLOSIVES_SCENE, DEFAULT_THUMBNAIL_BASE, type DistanceCurve, EXPLOSIVES_AREA_ID, EXPLOSIVES_TEXT, type EnergyCurve, type ExplosivesRoom, type ExplosivesScene, type ExplosivesTestModuleOptions, type ExplosivesText, 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, P13_VALVE_MESH, type ProjectileModel, type ProjectileQuery, 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, type WorldExplosiveOptions, applyCondition, buildCartridge, buildCasing, buildProp, buildRound, buildToolClips, buildWeaponModel, buildWeaponModelById, cartridgeShape, computeShotSound, createExplosivesTestModule, createWeaponAudio, createWeaponFx, createWeaponsTestModule, createWorldEffects, deriveFrames, explosivesTextOf, fitAttachmentModels, hasWeaponModel, mechanicalSoundOf, modelKit, mountFrame, partRegistry, projectileModel, rigStock, rigUnderbarrel, weaponProp, weaponThumbnailCredit, weaponThumbnailUrl, weaponsLayout, worldExplosiveItem, worldExplosiveShell, worldExplosiveValve };
+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_EXPLOSIVES_SCENE, DEFAULT_THUMBNAIL_BASE, type DistanceCurve, EXPLOSIVES_AREA_ID, EXPLOSIVES_TEXT, type EnergyCurve, type ExplosivesRoom, type ExplosivesScene, type ExplosivesTestModuleOptions, type ExplosivesText, 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, P13_VALVE_MESH, type ProjectileModel, type ProjectileQuery, 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 WeaponItemModel, type WeaponModel, type WeaponProp, type WeaponThumbnailEntry, type WeaponsTestModuleOptions, type WorldEffectIds, type WorldEffectsOptions, type WorldExplosiveOptions, applyCondition, buildCartridge, buildCasing, buildItemWeaponModel, buildProp, buildRound, buildToolClips, buildWeaponModel, buildWeaponModelById, cartridgeShape, computeShotSound, createExplosivesTestModule, createWeaponAudio, createWeaponFx, createWeaponsTestModule, createWorldEffects, deriveFrames, explosivesTextOf, fitAttachmentModels, hasWeaponModel, itemModelOfWeapon, mechanicalSoundOf, modelKit, mountFrame, partRegistry, projectileModel, registerWeaponItemModel, rigStock, rigUnderbarrel, weaponProp, weaponThumbnailCredit, weaponThumbnailUrl, weaponsLayout, worldExplosiveItem, worldExplosiveShell, worldExplosiveValve };