@adatechnology/game-weapons-three 0.10.4 → 0.11.1

package/README.md

@@ -4,8 +4,9 @@ three.js presentation for `@adatechnology/game-weapons`: the real models of the
 
 The muzzle flash, the smoke, the backblast of a launched rocket and the flame jet of the weapon in the hands are not built here: they are recipes of `@adatechnology/game-vfx` (`viewmodel_muzzle_flash`, `weapon_smoke_puff`, `launcher_backblast`, `flame_jet`) that draw them as the gallery does, as solids (an open cone, four small cones and a core for 55 ms growing from 0.6 to 1.5 times their size, a light of `4 k` that holds, spheres of smoke that rise and grow, icosahedra of fire), with the gallery's numbers and the barrel's whole turn (`orientation`, pitch and roll included). `createWeaponFx({ effects })` plays them through the host's effect sink (the test area passes `host.effects`); with no sink the viewer makes a world of effects of its own, stepped and drawn with the weapon. Casings, magazines, the rocket itself and the burning droplets stay meshes of this package.
 
-**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.
+**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.
 
+**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.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { HostTool, EffectSink, HostEvent, HandTargets, TestableModule, AreaPlacement, DestructionEvent, Hit, Vec3 as Vec3$1, ModuleControl, ModuleLayer, ModuleMetric, ModuleHost, TestableItem, DestructibleSpec, ToolClipSet } from '@adatechnology/game-contracts';
+import { HostTool, HandPose, EffectSink, HostEvent, HandTargets, TestableModule, AreaPlacement, DestructionEvent, Hit, Vec3 as Vec3$1, ModuleControl, ModuleLayer, ModuleMetric, ModuleHost, TestableItem, DestructibleSpec, ToolClipSet } from '@adatechnology/game-contracts';
 import { CaliberDef, ReloadStageId, WeaponEvent, MountKind, AttachmentDef, FittedAttachment, Arsenal, ExplosiveDef, WeaponDef, CartridgeDims, CaseType, ReloadFamily } from '@adatechnology/game-weapons';
 import { AudioEngine } from '@adatechnology/game-audio';
 import * as THREE_NS from 'three';
@@ -608,6 +608,8 @@ interface WeaponFxOptions {
     raycast?: LaserRaycast;
     /** Where the world is (distance from a point along a direction to the first surface, or null): the weapon in the hands comes back from a wall it would go through. */
     contact?: LaserRaycast;
+    /** Where the body holds the tool (`ModuleHost.holdFrame`): third person draws it there at its real size. */
+    bodyHold?: () => HandPose | null;
     /** The host's effects: the muzzle flash, smoke, backblast and flame jet of the gallery models are recipes it plays; without it the viewmodel makes a world of its own for them. */
     effects?: EffectSink;
 }