@adatechnology/game-characters-three 0.4.0 → 0.4.2

package/README.md

@@ -29,7 +29,7 @@ time.value += dt
 - `createFluidsBridge({ sink, film })` and `bloodLookOfAge(age)`: a `body` event throws drops of blood into the film, in the fresh and dry colours of the infection age (`ages.json`), `old_blood` for the thin ones.
 
 **Player avatar.** `createPlayerAvatar(THREE, options?)` is the team game's player body: the rich human of the Bestiário/Elenco built from `presets/player-avatar.json`
-(`{ type: 'Lento', human: true, seed: 4242, skin, hs: 'short', hair }`, shirt `0x3d5a73`), overridable with `{ spec, shirtColor, clips, blend, fallSeconds }`.
+(`{ type: 'Lento', human: true, seed: 4242, skin, hs: 'short', hair }`, shirt `0x3d5a73`), overridable with `{ spec, shirtColor, clips, blend, fallSeconds, cascade, clipCascade }` (`clipCascade`, default 5: how many times faster the joints follow while a clip that does not loop plays, so a strike reaches its pose by its impact).
 
 ```ts
 const player = createPlayerAvatar(THREE)
@@ -41,16 +41,16 @@ player.play('grabbed_bitten_human', { onEvent: (event) => event.type === 'impact
 
 Crouch, down and the aimed arms are derived literally from the game's GPU pose code (`BODY_CHUNK`, lines quoted in `src/player/avatar.ts`): crouch is thigh `-0.95`, knee `1.9`, trunk `+0.25`, hip `-0.35`;
 down turns the body about the hip (`±1.5` rad, face up or down by the phase) with the limbs of pose 2; `armed` follows `(pitch + 1) / 3`. `play` overlays a `PoseClip` of `@adatechnology/game-characters`
-(`channels: 'upper'` leaves the legs to the gait) with a 0.12 s blend, and fires its events (`impact`, `phase`) once through `onEvent` and `on('event')`. `hand('R')` is the weapon hand (the puppet's right, at -x).
+(`channels: 'upper'` leaves the legs to the gait) with a 0.12 s blend, and fires its events (`impact`, `phase`) once through `onEvent` and `on('event')`. `hand('R')` is the weapon hand (the puppet's right, at -x). A pose clip's `armL`/`legL` channels move that side (`arms[1]`/`legs[0]`), so `punch_right` and `front_kick` of `ATTACK_CLIPS` drive `armL` and `legL`, the same arm and leg the first-person view shows.
 
 **In the test room.** `room.setAvatar(toRoomAvatar(player))` shows the body at the player's feet (`toRoomAvatar` only flips the pitch: the room counts a look up as positive, the team game a look down) and V switches between the first and the third person of
 `@adatechnology/game-test-room`. `createAvatarTestModule({ avatar, camera, state })` is the module of the area `avatar_area` (`AVATAR_AREA_ID`): bench buttons for the view (1st/3rd person), crouch, stand, fall, get up, armed on/off,
 one button per registered clip (`Tocar: grabbed_bitten_human`, `grab_bite_zombie`, and with `clips: [...POSE_CLIPS, ...ATTACK_CLIPS]` the punch, shove, kick and the recoils; `clipLocales` gives the phase texts) and stop; metrics for the camera, the clip playing, the last clip event and the joints. Every action is a JSON line in the room log (`{"type":"avatar","action":"play_clip","clip":...}`), clip events included, and an `impact` event also gets its own `{"action":"impact","clip":...,"t":...}` line.
 The module takes the body, the view (`camera: { mode, set }`) and the state (`state: { set }`) by option and imports only `@adatechnology/game-contracts`.
 
-`toRoomAvatar` also gives the room the first-person arms (`firstPerson: false` for none) and `strike(clipId)`, which plays the attack clip on the body and the first-person clip of the same id on the arms and answers the seconds to the impact (the same in both views).
+`toRoomAvatar` also gives the room the first-person arms (`firstPerson: false` for none) and `strike(clipId)`, which plays the attack clip on the body and the first-person clip of the same id on the arms and answers the seconds to the impact (the same in both views). `strike(clip, { leg: 'left' })` kicks with the left leg and `strike(clip, { hand: 'left' })` punches with the left hand: the mirror of the clip on the body (`mirrorPoseClip`, id `<clip>_left`) and on the arms.
 
-**First-person arms.** `createFirstPersonArms(THREE, { colors?, rig?, stances?, clips?, blend?, bob? })` builds sleeves (upper arm, forearm, elbow, cuff) and hands of skin (palm, four fingers of three segments, a thumb that close on a grip) drawn in the camera's space, plus the right leg that only shows during a kick. `arms.update(dt, { camera, targets, stance, speed, running, crouch, contact? })`: the `relaxed` and `fists` stances are rest poses (`FIRST_PERSON_STANCES`, from `presets/first-person-arms.json`), `hold` follows the `HandTargets` of `game-contracts` (world space) with a two-bone IK from fixed shoulders, the elbow bending down and out; a target out of reach is clamped (the shoulder moves `reachShift` toward it first). `arms.play('punch_right' | 'shove_two_hands' | 'front_kick')` overlays a `FirstPersonClip` (`FIRST_PERSON_CLIPS` of `game-characters-people`, same durations and impact seconds as the attack clips); `arms.on('event', fn)` gives its `impact`; `arms.handPose(side)` reads where a hand is drawn. `contact(origin, direction, maxDistance)` (optional; distance to the first surface or null) makes the hands and the kick foot stop a few millimetres before a surface along the camera forward (the elbow bends); `arms.play('front_kick', { leg: 'left' })` kicks with the left leg. Hand frame: x wrist to knuckles, y back of the hand, z little-finger side; a left hand is the right one mirrored.
+**First-person arms.** `createFirstPersonArms(THREE, { colors?, rig?, stances?, clips?, blend?, bob? })` builds sleeves (upper arm, forearm, elbow, cuff) and hands of skin (palm, four fingers of three segments, a thumb that close on a grip) drawn in the camera's space, plus the right leg that only shows during a kick. `arms.update(dt, { camera, targets, stance, speed, running, crouch, contact? })`: the `relaxed` and `fists` stances are rest poses (`FIRST_PERSON_STANCES`, from `presets/first-person-arms.json`), `hold` follows the `HandTargets` of `game-contracts` (world space) with a two-bone IK from fixed shoulders, the elbow bending down and out; a target out of reach is clamped (the shoulder moves `reachShift` toward it first). `arms.play('punch_right' | 'shove_two_hands' | 'front_kick')` overlays a `FirstPersonClip` (`FIRST_PERSON_CLIPS` of `game-characters-people`, same durations and impact seconds as the attack clips); `arms.on('event', fn)` gives its `impact`; `arms.handPose(side)` reads where a hand is drawn. `contact(origin, direction, maxDistance)` (optional; distance to the first surface or null) makes the hands and the kick foot stop a few millimetres before a surface along the camera forward (the elbow bends); `arms.play('front_kick', { leg: 'left' })` kicks with the left leg and `arms.play('punch_right', { hand: 'left' })` punches with the left hand (the hands of the clip in a mirror). Hand frame: x wrist to knuckles, y back of the hand, z little-finger side; a left hand is the right one mirrored.
 
 ## Geometry
 

package/dist/index.d.ts

@@ -1040,6 +1040,11 @@ type PlayerAvatarOptions = {
     readonly fallSeconds?: number;
     /** Smooth the joints with the Bestiário cascade (default true). */
     readonly cascade?: boolean;
+    /**
+     * How many times faster the cascade follows while a clip that does not loop plays: a strike is over in a third of a second, and at the walk's pace the joints would
+     * still be on their way when it ends (a punch that never reaches the shoulder). 1 keeps the walk's pace. Default 5.
+     */
+    readonly clipCascade?: number;
 };
 type AvatarEvent = PoseClipEvent & {
     clip: string;
@@ -1206,9 +1211,10 @@ type FirstPersonArms = {
     /** Add it to the scene: it follows the camera by itself. */
     root: THREE_NS.Group;
     /** Starts a clip; false when no registered clip has that id. The previous clip is dropped. */
-    /** `leg: 'left'` plays the foot of the clip (the right foot) as the left one, in a mirror. */
+    /** `leg: 'left'` plays the foot of the clip (the right foot) as the left one, in a mirror; `hand: 'left'` plays the hands in a mirror (the right hand's punch thrown by the left). */
     play(clip: string, options?: {
         leg?: 'left' | 'right';
+        hand?: 'left' | 'right';
     }): boolean;
     stop(): void;
     /** The clip being played, or null. */
@@ -1263,6 +1269,7 @@ type RoomAvatarLike = {
     /** Plays a strike on the body and the arms and answers the seconds to its impact (`RoomAvatar.strike`). */
     strike(clipId: string, options?: {
         leg?: 'left' | 'right';
+        hand?: 'left' | 'right';
     }): number | null;
     /** The avatar it wraps. */
     readonly avatar: PlayerAvatar;
@@ -1281,7 +1288,7 @@ type ToRoomAvatarOptions = {
  * Fits the player's body to the test room's `RoomAvatar` (`room.setAvatar(toRoomAvatar(createPlayerAvatar(THREE)))`). It changes the sign of the pitch: the room
  * counts a look up as positive, the team game's `view.pitch` (what `AvatarUpdate.pitch` reads) counts a look down as positive. It also gives the room the first-person arms, dressed in the
  * colours of the body (`firstPerson: false` for none), and `strike(clipId)`: the strike plays on the body (the attack clips) and on the arms (the first-person clips), and answers the seconds to its
- * impact, which are the same in both views.
+ * impact, which are the same in both views. A kick with the left leg (`leg: 'left'`) or a punch with the left hand (`hand: 'left'`) plays the mirror of the clip written for the right.
  */
 declare const toRoomAvatar: (avatar: PlayerAvatar, options?: ToRoomAvatarOptions) => RoomAvatarLike;
 

package/dist/index.global.js

@@ -8640,6 +8640,7 @@ var GameCharactersThree = (() => {
   var TWO_PI2 = Math.PI * 2;
   var MAX_GAIT = 1.4;
   var CLIP_BLEND = 0.12;
+  var CLIP_CASCADE = 5;
   var FALL_SECONDS2 = 0.3;
   var HIP_HEIGHT = 0.95;
   var WALK_ARM = 0.28;
@@ -8679,6 +8680,7 @@ var GameCharactersThree = (() => {
     const blendDefault = options.blend ?? CLIP_BLEND;
     const fallSeconds = options.fallSeconds ?? FALL_SECONDS2;
     const smooth = options.cascade ?? true;
+    const clipCascade = options.clipCascade ?? CLIP_CASCADE;
     const root = new THREE.Group();
     const tilt = new THREE.Group();
     tilt.add(body);
@@ -8969,14 +8971,14 @@ var GameCharactersThree = (() => {
         }
         placeBody(fall);
         stepClip(dt, down);
-        if (smooth) animator.cascade(rig, dt);
+        if (smooth) animator.cascade(rig, run && !run.clip.loop ? dt * clipCascade : dt);
         const clipId = run ? run.clip.id : null;
         const ph = cycles * TWO_PI2;
         hands.forEach((hand) => {
           const isRight = hand.side < 0;
           const holdRight = isRight && (!!state.holding || !!state.itemUse);
           const holdLeft = !isRight && (state.itemUse?.id === "open" || state.itemUse?.id === "close");
-          const grip = clipId === "punch_right" ? 1.4 : clipId === "shove_two_hands" ? 0.15 : state.armed || holdRight || holdLeft ? 1.22 : running ? 0.85 : 0.12;
+          const grip = clipId?.startsWith("punch_") ? 1.4 : clipId === "shove_two_hands" ? 0.15 : state.armed || holdRight || holdLeft ? 1.22 : running ? 0.85 : 0.12;
           const wristSwing = holdRight || state.armed || running ? 0 : -Math.min(1, gait) * Math.sin(ph - 0.6) * 0.12 * hand.side;
           setHandGrip(hand, grip, wristSwing);
         });
@@ -9022,9 +9024,9 @@ var GameCharactersThree = (() => {
         channels: "upper",
         keys: [
           { t: 0, pose: { lean: 0, twist: 0, side: 0, headX: 0, headY: 0, headZ: 0, armR: 0.05, armL: -0.1, elbR: -0.2, elbL: -0.2, armRz: 0, armLz: 0 } },
-          { t: 0.1, pose: { lean: 0.04, twist: -0.35, side: 0, headX: 0, headY: 0.28, headZ: 0, armR: 0.45, armL: -0.7, elbR: -1.9, elbL: -1.6, armRz: 0, armLz: 0.1 } },
-          { t: 0.16, pose: { lean: 0.2, twist: 0.5, side: 0, headX: 0, headY: -0.38, headZ: 0, armR: -1.5, armL: -0.6, elbR: -0.1, elbL: -1.7, armRz: -0.1, armLz: 0.1 } },
-          { t: 0.22, pose: { lean: 0.16, twist: 0.4, side: 0, headX: 0, headY: -0.3, headZ: 0, armR: -1.35, armL: -0.6, elbR: -0.25, elbL: -1.6, armRz: -0.08, armLz: 0.08 } },
+          { t: 0.1, pose: { lean: 0.04, twist: 0.3, side: 0, headX: 0, headY: -0.24, headZ: 0, armR: -0.9, armL: -0.35, elbR: -1.9, elbL: -2.1, armRz: -0.2, armLz: 0.15 } },
+          { t: 0.16, pose: { lean: 0.16, twist: -0.35, side: 0, headX: 0, headY: 0.3, headZ: 0, armR: -0.95, armL: -1.55, elbR: -1.95, elbL: -0.05, armRz: -0.25, armLz: 0.3 } },
+          { t: 0.22, pose: { lean: 0.13, twist: -0.3, side: 0, headX: 0, headY: 0.25, headZ: 0, armR: -0.9, armL: -1.45, elbR: -1.9, elbL: -0.2, armRz: -0.22, armLz: 0.26 } },
           { t: 0.35, pose: { lean: 0, twist: 0, side: 0, headX: 0, headY: 0, headZ: 0, armR: 0.05, armL: -0.1, elbR: -0.2, elbL: -0.2, armRz: 0, armLz: 0 } }
         ],
         events: [
@@ -9062,9 +9064,9 @@ var GameCharactersThree = (() => {
         channels: "full",
         keys: [
           { t: 0, pose: { lean: 0, twist: 0, side: 0, drop: 0, headX: 0, headY: 0, headZ: 0, armR: 0.05, armL: -0.1, elbR: -0.2, elbL: -0.2, armRz: 0, armLz: 0, legL: -0.05, legR: 0.05, kneeL: 0.05, kneeR: 0.05 } },
-          { t: 0.18, pose: { lean: -0.1, twist: 0, side: 0.04, drop: -0.05, headX: 0.05, headY: 0, headZ: 0, armR: -0.5, armL: 0.4, elbR: -0.5, elbL: -0.4, armRz: -0.1, armLz: 0.1, legL: 0.1, legR: -1.1, kneeL: 0.35, kneeR: 1.8 } },
-          { t: 0.32, pose: { lean: -0.22, twist: 0, side: 0.04, drop: -0.06, headX: 0.1, headY: 0, headZ: 0, armR: -0.7, armL: 0.7, elbR: -0.6, elbL: -0.3, armRz: -0.15, armLz: 0.15, legL: 0.12, legR: -1.45, kneeL: 0.2, kneeR: 0.1 } },
-          { t: 0.42, pose: { lean: -0.18, twist: 0, side: 0.03, drop: -0.05, headX: 0.08, headY: 0, headZ: 0, armR: -0.5, armL: 0.5, elbR: -0.5, elbL: -0.3, armRz: -0.1, armLz: 0.1, legL: 0.1, legR: -1.2, kneeL: 0.3, kneeR: 1.2 } },
+          { t: 0.18, pose: { lean: -0.1, twist: 0, side: -0.04, drop: -0.05, headX: 0.05, headY: 0, headZ: 0, armR: 0.4, armL: -0.5, elbR: -0.4, elbL: -0.5, armRz: -0.1, armLz: 0.1, legL: -1.1, legR: 0.1, kneeL: 1.8, kneeR: 0.35 } },
+          { t: 0.32, pose: { lean: -0.22, twist: 0, side: -0.04, drop: -0.06, headX: 0.1, headY: 0, headZ: 0, armR: 0.7, armL: -0.7, elbR: -0.3, elbL: -0.6, armRz: -0.15, armLz: 0.15, legL: -1.45, legR: 0.12, kneeL: 0.1, kneeR: 0.2 } },
+          { t: 0.42, pose: { lean: -0.18, twist: 0, side: -0.03, drop: -0.05, headX: 0.08, headY: 0, headZ: 0, armR: 0.5, armL: -0.5, elbR: -0.3, elbL: -0.5, armRz: -0.1, armLz: 0.1, legL: -1.2, legR: 0.1, kneeL: 1.2, kneeR: 0.3 } },
           { t: 0.6, pose: { lean: 0, twist: 0, side: 0, drop: 0, headX: 0, headY: 0, headZ: 0, armR: 0.05, armL: -0.1, elbR: -0.2, elbL: -0.2, armRz: 0, armLz: 0, legL: -0.05, legR: 0.05, kneeL: 0.05, kneeR: 0.05 } }
         ],
         events: [
@@ -9670,10 +9672,11 @@ var GameCharactersThree = (() => {
     const palmAt = new THREE.Vector3();
     const fingers = new THREE.Vector3();
     const towards = new THREE.Vector3();
-    const fromChannel = (channel, side, base, out) => {
+    const fromChannel = (channel, side, base, out, from = side) => {
       out.p.set(...channel.p);
       out.q.copy(quaternionOf(channel.r));
-      if (channel.mirror && side === "L") {
+      const rightNumbers = from === "R" || channel.mirror;
+      if (rightNumbers !== (side === "R")) {
         out.p.x = -out.p.x;
         out.q.copy(mirrorQuaternion(THREE, out.q));
       }
@@ -9738,7 +9741,7 @@ var GameCharactersThree = (() => {
       play(id, options2) {
         const clip = clips.get(id);
         if (!clip) return false;
-        run = { clip, time: 0, left: options2?.leg === "left" };
+        run = { clip, time: 0, left: options2?.leg === "left", swap: options2?.hand === "left" };
         fire(clip, -1e-9, 0);
         return true;
       },
@@ -9786,10 +9789,11 @@ var GameCharactersThree = (() => {
           arm.blend = blendSeconds <= 0 ? 1 : Math.min(1, arm.blend + dt / blendSeconds);
           if (arm.blend >= 1) copyPose(arm.shown, desired);
           else mixPose(THREE, arm.shown, arm.from, desired, ease2(arm.blend));
-          const channel = sample?.[side];
+          const from = run?.swap ? side === "R" ? "L" : "R" : side;
+          const channel = sample?.[from];
           let pose;
           if (channel && channel.w > 0) {
-            fromChannel(channel, side, arm.shown, channelPose);
+            fromChannel(channel, side, arm.shown, channelPose, from);
             mixPose(THREE, mixed, arm.shown, channelPose, channel.w);
             pose = mode === "target" ? mixed : keepOutside(mixed, handReach(mixed));
           } else pose = mode === "target" ? arm.shown : keepOutside(arm.shown, handReach(arm.shown));
@@ -9878,9 +9882,9 @@ var GameCharactersThree = (() => {
       strike: (clipId, strikeOptions) => {
         const clip = strikes.get(clipId);
         if (!clip) return null;
-        const left = strikeOptions?.leg === "left";
+        const left = strikeOptions?.leg === "left" || strikeOptions?.hand === "left";
         avatar.play(left ? leftOf(clip) : clip);
-        arms?.play(clipId, left ? { leg: "left" } : void 0);
+        arms?.play(clipId, strikeOptions?.leg === "left" ? { leg: "left" } : strikeOptions?.hand === "left" ? { hand: "left" } : void 0);
         return impactOf(clip);
       }
     };