@adatechnology/game-characters-three 0.4.1 → 0.5.0

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,17 @@ 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; while crouched only a kick takes the legs, so a punch or the guard stays low) 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. After a punch (an `impact` of kind `punch`) the body holds the guard (`guardClip`, default `'fight_guard'`, `false` for none) for
+`guardHold` seconds (default 1.2) while it stands still, so a combo goes guard, punch, guard; the punch blends in over `punchBlend` (default 0.05 s). Walking, running, a weapon or a held item drop the guard.
 
-**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;
@@ -1066,6 +1071,11 @@ type AvatarUpdate = {
     holding?: boolean;
     /** Active scripted item use (`drink`, `sip`, `chug`, `pour`, `open`, `close`, `tilt`). */
     itemUse?: AvatarItemUsePose | null;
+    /** Hands on a piece of furniture: `grip` closes on it with `progress`, `push` walks with it, `strain` strains against what does not give. */
+    push?: {
+        readonly phase: 'grip' | 'push' | 'strain';
+        readonly progress: number;
+    } | null;
 };
 type PlayPoseOptions = {
     onEvent?: (event: AvatarEvent) => void;
@@ -1206,9 +1216,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. */
@@ -1243,6 +1254,10 @@ type RoomAvatarLike = {
         down: boolean;
         armed: boolean;
         pitch: number;
+        push?: {
+            readonly phase: 'grip' | 'push' | 'strain';
+            readonly progress: number;
+        } | null;
         holding?: boolean;
         itemUse?: AvatarItemUsePose | null;
     }): void;
@@ -1263,6 +1278,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;
@@ -1276,12 +1292,19 @@ type ToRoomAvatarOptions = {
     strikeClips?: readonly PoseClip[];
     /** The first-person clips the arms play. Default `FIRST_PERSON_CLIPS` of game-characters-people. */
     firstPersonClips?: readonly FirstPersonClip[];
+    /** The looping clip the body holds between punches (a clip of `strikeClips`), so a combo goes guard, punch, guard instead of dropping the hands each time; `false` for none. Default `'fight_guard'`. */
+    guardClip?: string | false;
+    /** Seconds the guard stays up after a punch ends. Default 1.2. */
+    guardHold?: number;
+    /** Seconds a punch takes to blend in over the walk (or the guard it comes from). Default 0.05: the fist leaves at once. */
+    punchBlend?: number;
 };
 /**
  * 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.
+ * After a punch the body holds the guard (`guardClip`) for `guardHold` seconds while it stands, so the next punch leaves from the guard.
  */
 declare const toRoomAvatar: (avatar: PlayerAvatar, options?: ToRoomAvatarOptions) => RoomAvatarLike;
 

package/dist/index.global.js

@@ -8479,6 +8479,7 @@ var GameCharactersThree = (() => {
     return {
       id: CHARACTERS_AREA_ID,
       name: text.name,
+      ground: { surface: "concrete_slab" },
       group: text.group,
       get entries() {
         return entries;
@@ -8640,6 +8641,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 +8681,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);
@@ -8778,6 +8781,24 @@ var GameCharactersThree = (() => {
       });
       return { armR: shoulder, armL: shoulder, armRz: AIMED.zRight, armLz: AIMED.zLeft, elbR: AIMED.elbowRight, elbL: AIMED.elbowLeft };
     };
+    const pushingPose = (push) => {
+      const on = push.phase === "grip" ? Math.min(1, push.progress * 2.2) : 1;
+      const strain = push.phase === "strain" ? 1 : 0;
+      const shake = strain * Math.sin(time * 40) * 0.025;
+      const raise = -1.5 * on;
+      const elbow = -0.9 + 0.72 * (push.phase === "grip" ? push.progress : 1) + strain * 0.12;
+      return {
+        lean: (0.2 + 0.2 * strain) * on,
+        headX: (0.05 + 0.08 * strain) * on,
+        armR: raise + shake,
+        armL: raise - shake,
+        armRz: -0.08 * on,
+        armLz: 0.08 * on,
+        elbR: elbow,
+        elbL: elbow,
+        ...strain ? { legL: -0.5, legR: 0.4, kneeL: 0.55, kneeR: 0.08, drop: -0.05 } : {}
+      };
+    };
     const holdingPose = (gait, itemUse) => {
       const bob = Math.sin(cycles * TWO_PI2) * 0.05 * gait;
       if (!itemUse) {
@@ -8905,7 +8926,7 @@ var GameCharactersThree = (() => {
     const fireClipEvents = (r, from, to) => {
       for (const event of clipEventsBetween(r.clip, from, to)) emit({ ...event, clip: r.clip.id }, r.onEvent);
     };
-    const stepClip = (dt, down) => {
+    const stepClip = (dt, down, crouch) => {
       if (!run) return;
       const r = run;
       const from = r.time;
@@ -8925,7 +8946,9 @@ var GameCharactersThree = (() => {
         return;
       }
       if (down) return;
-      const sampled = filterPoseChannels(samplePoseClip(r.clip, Math.min(r.time, duration)), r.clip.channels ?? "full");
+      const keepsCrouch = crouch && !r.clip.events?.some((event) => event.data?.kind === "kick");
+      const channels = r.clip.channels ?? "full";
+      const sampled = filterPoseChannels(filterPoseChannels(samplePoseClip(r.clip, Math.min(r.time, duration)), channels), keepsCrouch ? "upper" : "full");
       const current = readPose();
       const blended = {};
       for (const [name, value] of Object.entries(sampled)) if (name in current) blended[name] = current[name] + (value - current[name]) * r.weight;
@@ -8956,7 +8979,8 @@ var GameCharactersThree = (() => {
         else {
           if (running) animator.setPose(rig, runningPose(gait, Boolean(state.armed || state.holding || state.itemUse)));
           if (state.crouch) animator.setPose(rig, crouchPose(gait));
-          if (state.armed) animator.setPose(rig, armed(state.pitch ?? 0, gait, state.hip ?? 0));
+          if (state.push) animator.setPose(rig, pushingPose(state.push));
+          else if (state.armed) animator.setPose(rig, armed(state.pitch ?? 0, gait, state.hip ?? 0));
           else if (state.holding || state.itemUse) animator.setPose(rig, holdingPose(gait, state.itemUse));
           else if (!running) {
             animator.setPose(rig, {
@@ -8968,15 +8992,15 @@ var GameCharactersThree = (() => {
           }
         }
         placeBody(fall);
-        stepClip(dt, down);
-        if (smooth) animator.cascade(rig, dt);
-        const clipId = run ? run.clip.id : null;
+        stepClip(dt, down, Boolean(state.crouch));
+        if (smooth) animator.cascade(rig, run && !run.clip.loop ? dt * clipCascade : dt);
+        const blow = run?.clip.events?.find((event) => (event.type === "impact" || event.type === "grip") && event.data?.kind)?.data?.kind;
         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 = blow === "punch" ? 1.4 : blow === "shove" ? 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);
         });
@@ -9016,22 +9040,97 @@ var GameCharactersThree = (() => {
     clips: [
       {
         id: "punch_right",
-        source: { authored: "game-kit", note: "authored in the kit; replace with the Elenco team's clip when delivered" },
-        duration: 0.35,
+        source: { authored: "game-kit", note: "authored in the kit from boxing technique (guard, hip and shoulder turn, full extension, weight over the front knee, back to the guard); the right hand's straight punch (the cross; the left plays its mirror); replace with the Elenco team's clip when delivered" },
+        duration: 0.38,
         loop: false,
-        channels: "upper",
+        channels: "full",
         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.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 } }
+          { t: 0, pose: { lean: 0.12, twist: -0.3, side: 0, drop: -0.06, headX: 0.18, headY: 0.28, headZ: 0, armR: -0.85, elbR: -1.95, armRz: -0.5, armL: -0.75, elbL: -2, armLz: 0.55, legL: 0.25, kneeL: 0.3, legR: -0.3, kneeR: 0.3 } },
+          { t: 0.06, pose: { lean: 0.12, twist: -0.42, side: 0, drop: -0.09, headX: 0.18, headY: 0.34, headZ: 0, armR: -0.85, elbR: -1.95, armRz: -0.5, armL: -0.7, elbL: -2.1, armLz: 0.55, legL: 0.25, kneeL: 0.42, legR: -0.3, kneeR: 0.3 } },
+          { t: 0.14, pose: { lean: 0.22, twist: 0.5, side: 0, drop: -0.08, headX: 0.18, headY: -0.3, headZ: 0, armR: -0.8, elbR: -2.05, armRz: -0.3, armL: -1.75, elbL: -0.05, armLz: 0.12, legL: 0.35, kneeL: 0.12, legR: -0.3, kneeR: 0.45 } },
+          { t: 0.2, pose: { lean: 0.2, twist: 0.42, side: 0, drop: -0.08, headX: 0.18, headY: -0.26, headZ: 0, armR: -0.8, elbR: -2.05, armRz: -0.3, armL: -1.6, elbL: -0.3, armLz: 0.15, legL: 0.33, kneeL: 0.15, legR: -0.3, kneeR: 0.42 } },
+          { t: 0.38, pose: { lean: 0.12, twist: -0.3, side: 0, drop: -0.06, headX: 0.18, headY: 0.28, headZ: 0, armR: -0.85, elbR: -1.95, armRz: -0.5, armL: -0.75, elbL: -2, armLz: 0.55, legL: 0.25, kneeL: 0.3, legR: -0.3, kneeR: 0.3 } }
         ],
         events: [
           { t: 0, type: "phase", data: { label: "attack_clip.phase.windup" } },
-          { t: 0.1, type: "phase", data: { label: "attack_clip.phase.strike" } },
-          { t: 0.16, type: "impact", data: { kind: "punch" } },
-          { t: 0.22, type: "phase", data: { label: "attack_clip.phase.recover" } }
+          { t: 0.06, type: "phase", data: { label: "attack_clip.phase.strike" } },
+          { t: 0.14, type: "impact", data: { kind: "punch" } },
+          { t: 0.2, type: "phase", data: { label: "attack_clip.phase.recover" } }
+        ]
+      },
+      {
+        id: "jab",
+        source: { authored: "game-kit", note: "authored in the kit from boxing technique (guard, hip and shoulder turn, full extension, weight over the front knee, back to the guard); the lead hand's jab, written for the right hand (the left plays its mirror, from the orthodox guard); one step of the punch combo; replace with the Elenco team's clip when delivered" },
+        duration: 0.3,
+        loop: false,
+        channels: "full",
+        keys: [
+          { t: 0, pose: { lean: 0.12, twist: 0.3, side: 0, drop: -0.06, headX: 0.18, headY: -0.28, headZ: 0, armL: -0.85, elbL: -1.95, armLz: 0.5, armR: -0.75, elbR: -2, armRz: -0.55, legR: 0.25, kneeR: 0.3, legL: -0.3, kneeL: 0.3 } },
+          { t: 0.04, pose: { lean: 0.12, twist: 0.34, side: 0, drop: -0.08, headX: 0.18, headY: -0.28, headZ: 0, armL: -0.85, elbL: -1.75, armLz: 0.5, armR: -0.75, elbR: -2, armRz: -0.55, legR: 0.25, kneeR: 0.3, legL: -0.3, kneeL: 0.36 } },
+          { t: 0.11, pose: { lean: 0.16, twist: 0.55, side: 0, drop: -0.08, headX: 0.18, headY: -0.35, headZ: 0, armL: -1.75, elbL: -0.05, armLz: 0.08, armR: -0.75, elbR: -2, armRz: -0.55, legR: 0.25, kneeR: 0.22, legL: -0.38, kneeL: 0.38 } },
+          { t: 0.16, pose: { lean: 0.15, twist: 0.5, side: 0, drop: -0.08, headX: 0.18, headY: -0.33, headZ: 0, armL: -1.62, elbL: -0.35, armLz: 0.12, armR: -0.75, elbR: -2, armRz: -0.55, legR: 0.25, kneeR: 0.3, legL: -0.36, kneeL: 0.36 } },
+          { t: 0.3, pose: { lean: 0.12, twist: 0.3, side: 0, drop: -0.06, headX: 0.18, headY: -0.28, headZ: 0, armL: -0.85, elbL: -1.95, armLz: 0.5, armR: -0.75, elbR: -2, armRz: -0.55, legR: 0.25, kneeR: 0.3, legL: -0.3, kneeL: 0.3 } }
+        ],
+        events: [
+          { t: 0, type: "phase", data: { label: "attack_clip.phase.windup" } },
+          { t: 0.04, type: "phase", data: { label: "attack_clip.phase.strike" } },
+          { t: 0.11, type: "impact", data: { kind: "punch" } },
+          { t: 0.16, type: "phase", data: { label: "attack_clip.phase.recover" } }
+        ]
+      },
+      {
+        id: "hook",
+        source: { authored: "game-kit", note: "authored in the kit from boxing technique (guard, hip and shoulder turn, full extension, weight over the front knee, back to the guard); the lead hand's hook, written for the right hand (the left plays its mirror, from the orthodox guard); one step of the punch combo; replace with the Elenco team's clip when delivered" },
+        duration: 0.42,
+        loop: false,
+        channels: "full",
+        keys: [
+          { t: 0, pose: { lean: 0.12, twist: 0.3, side: 0, drop: -0.06, headX: 0.18, headY: -0.28, headZ: 0, armL: -0.85, elbL: -1.95, armLz: 0.5, armR: -0.75, elbR: -2, armRz: -0.55, legR: 0.25, kneeR: 0.3, legL: -0.3, kneeL: 0.3 } },
+          { t: 0.08, pose: { lean: 0.12, twist: 0.12, side: 0, drop: -0.1, headX: 0.18, headY: -0.15, headZ: 0, armL: -0.45, elbL: -1.9, armLz: -0.85, armR: -0.75, elbR: -2, armRz: -0.55, legR: 0.25, kneeR: 0.3, legL: -0.3, kneeL: 0.5 } },
+          { t: 0.18, pose: { lean: 0.14, twist: 0.85, side: 0, drop: -0.08, headX: 0.18, headY: -0.48, headZ: 0, armL: 0, elbL: -1.6, armLz: -1.62, armR: -0.75, elbR: -2, armRz: -0.55, legR: 0.25, kneeR: 0.38, legL: -0.3, kneeL: 0.36 } },
+          { t: 0.25, pose: { lean: 0.13, twist: 0.95, side: 0, drop: -0.08, headX: 0.18, headY: -0.5, headZ: 0, armL: 0, elbL: -1.7, armLz: -1.5, armR: -0.75, elbR: -2, armRz: -0.55, legR: 0.25, kneeR: 0.38, legL: -0.3, kneeL: 0.36 } },
+          { t: 0.42, pose: { lean: 0.12, twist: 0.3, side: 0, drop: -0.06, headX: 0.18, headY: -0.28, headZ: 0, armL: -0.85, elbL: -1.95, armLz: 0.5, armR: -0.75, elbR: -2, armRz: -0.55, legR: 0.25, kneeR: 0.3, legL: -0.3, kneeL: 0.3 } }
+        ],
+        events: [
+          { t: 0, type: "phase", data: { label: "attack_clip.phase.windup" } },
+          { t: 0.08, type: "phase", data: { label: "attack_clip.phase.strike" } },
+          { t: 0.18, type: "impact", data: { kind: "punch" } },
+          { t: 0.25, type: "phase", data: { label: "attack_clip.phase.recover" } }
+        ]
+      },
+      {
+        id: "uppercut",
+        source: { authored: "game-kit", note: "authored in the kit from boxing technique (guard, hip and shoulder turn, full extension, weight over the front knee, back to the guard); the rear hand's uppercut; one step of the punch combo; replace with the Elenco team's clip when delivered" },
+        duration: 0.42,
+        loop: false,
+        channels: "full",
+        keys: [
+          { t: 0, pose: { lean: 0.12, twist: -0.3, side: 0, drop: -0.06, headX: 0.18, headY: 0.28, headZ: 0, armR: -0.85, elbR: -1.95, armRz: -0.5, armL: -0.75, elbL: -2, armLz: 0.55, legL: 0.25, kneeL: 0.3, legR: -0.3, kneeR: 0.3 } },
+          { t: 0.09, pose: { lean: 0.25, twist: -0.12, side: 0, drop: -0.15, headX: 0.18, headY: 0.3, headZ: 0, armR: -0.85, elbR: -1.95, armRz: -0.5, armL: -0.15, elbL: -1.75, armLz: 0.1, legL: 0.25, kneeL: 0.65, legR: -0.3, kneeR: 0.55 } },
+          { t: 0.19, pose: { lean: -0.04, twist: 0.45, side: 0, drop: -0.02, headX: 0.08, headY: -0.25, headZ: 0, armR: -0.8, elbR: -2.05, armRz: -0.5, armL: -0.95, elbL: -2, armLz: 0.6, legL: 0.25, kneeL: 0.12, legR: -0.3, kneeR: 0.25 } },
+          { t: 0.26, pose: { lean: -0.02, twist: 0.4, side: 0, drop: -0.03, headX: 0.1, headY: -0.22, headZ: 0, armR: -0.8, elbR: -2.05, armRz: -0.5, armL: -1, elbL: -2.05, armLz: 0.55, legL: 0.25, kneeL: 0.15, legR: -0.3, kneeR: 0.28 } },
+          { t: 0.42, pose: { lean: 0.12, twist: -0.3, side: 0, drop: -0.06, headX: 0.18, headY: 0.28, headZ: 0, armR: -0.85, elbR: -1.95, armRz: -0.5, armL: -0.75, elbL: -2, armLz: 0.55, legL: 0.25, kneeL: 0.3, legR: -0.3, kneeR: 0.3 } }
+        ],
+        events: [
+          { t: 0, type: "phase", data: { label: "attack_clip.phase.windup" } },
+          { t: 0.09, type: "phase", data: { label: "attack_clip.phase.strike" } },
+          { t: 0.19, type: "impact", data: { kind: "punch" } },
+          { t: 0.26, type: "phase", data: { label: "attack_clip.phase.recover" } }
+        ]
+      },
+      {
+        id: "fight_guard",
+        source: { authored: "game-kit", note: "authored in the kit from boxing technique (guard, hip and shoulder turn, full extension, weight over the front knee, back to the guard); the guard a punch comes from and goes back to (orthodox: left foot and left fist forward, chin down); replace with the Elenco team's clip when delivered" },
+        duration: 1.2,
+        loop: true,
+        channels: "full",
+        keys: [
+          { t: 0, pose: { lean: 0.12, twist: -0.3, side: 0, drop: -0.06, headX: 0.18, headY: 0.28, headZ: 0, armR: -0.85, elbR: -1.95, armRz: -0.5, armL: -0.75, elbL: -2, armLz: 0.55, legL: 0.25, kneeL: 0.3, legR: -0.3, kneeR: 0.3 } },
+          { t: 0.6, pose: { lean: 0.13, twist: -0.3, side: 0, drop: -0.075, headX: 0.2, headY: 0.28, headZ: 0, armR: -0.85, elbR: -1.95, armRz: -0.5, armL: -0.75, elbL: -2, armLz: 0.55, legL: 0.25, kneeL: 0.3, legR: -0.3, kneeR: 0.3 } },
+          { t: 1.2, pose: { lean: 0.12, twist: -0.3, side: 0, drop: -0.06, headX: 0.18, headY: 0.28, headZ: 0, armR: -0.85, elbR: -1.95, armRz: -0.5, armL: -0.75, elbL: -2, armLz: 0.55, legL: 0.25, kneeL: 0.3, legR: -0.3, kneeR: 0.3 } }
+        ],
+        events: [
+          { t: 0, type: "grip", data: { kind: "punch" } }
         ]
       },
       {
@@ -9062,9 +9161,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: [
@@ -9127,19 +9226,73 @@ var GameCharactersThree = (() => {
       {
         id: "punch_right",
         source: { authored: "game-kit", note: "first-person counterpart of attack-clips.json (same duration, same events); authored in the kit, replace with the Elenco team's clips when delivered" },
-        duration: 0.35,
+        duration: 0.38,
+        keys: [
+          { t: 0, R: { p: [0.15, -0.12, -0.4], r: [0, 1.5, 0.15], grip: 1, w: 0 } },
+          { t: 0.06, R: { p: [0.21, -0.15, -0.29], r: [0.1, 1.45, 0.2], grip: 1 } },
+          { t: 0.14, R: { p: [0.06, -0.09, -0.62], r: [0, 1.5708, -0.05], grip: 1 } },
+          { t: 0.2, R: { p: [0.07, -0.1, -0.56], r: [0, 1.5708, -0.05], grip: 1 } },
+          { t: 0.38, R: { p: [0.15, -0.12, -0.4], r: [0, 1.5, 0.15], grip: 1, w: 0 } }
+        ],
+        events: [
+          { t: 0, type: "phase", data: { label: "attack_clip.phase.windup" } },
+          { t: 0.06, type: "phase", data: { label: "attack_clip.phase.strike" } },
+          { t: 0.14, type: "impact", data: { kind: "punch" } },
+          { t: 0.2, type: "phase", data: { label: "attack_clip.phase.recover" } }
+        ]
+      },
+      {
+        id: "jab",
+        source: { authored: "game-kit", note: "first-person counterpart of attack-clips.json (same duration, same events), for the right hand (the left plays its mirror); authored in the kit, replace with the Elenco team's clips when delivered" },
+        duration: 0.3,
+        keys: [
+          { t: 0, R: { p: [0.15, -0.12, -0.4], r: [0, 1.5, 0.15], grip: 1, w: 0 } },
+          { t: 0.04, R: { p: [0.17, -0.13, -0.34], r: [0.1, 1.45, 0.2], grip: 1 } },
+          { t: 0.11, R: { p: [0.08, -0.08, -0.62], r: [0, 1.5708, -0.05], grip: 1 } },
+          { t: 0.16, R: { p: [0.09, -0.09, -0.57], r: [0, 1.5708, -0.05], grip: 1 } },
+          { t: 0.3, R: { p: [0.15, -0.12, -0.4], r: [0, 1.5, 0.15], grip: 1, w: 0 } }
+        ],
+        events: [
+          { t: 0, type: "phase", data: { label: "attack_clip.phase.windup" } },
+          { t: 0.04, type: "phase", data: { label: "attack_clip.phase.strike" } },
+          { t: 0.11, type: "impact", data: { kind: "punch" } },
+          { t: 0.16, type: "phase", data: { label: "attack_clip.phase.recover" } }
+        ]
+      },
+      {
+        id: "hook",
+        source: { authored: "game-kit", note: "first-person counterpart of attack-clips.json (same duration, same events), for the right hand (the left plays its mirror); authored in the kit, replace with the Elenco team's clips when delivered" },
+        duration: 0.42,
+        keys: [
+          { t: 0, R: { p: [0.15, -0.12, -0.4], r: [0, 1.5, 0.15], grip: 1, w: 0 } },
+          { t: 0.08, R: { p: [0.3, -0.12, -0.4], r: [0, 1.5, 0.6], grip: 1 } },
+          { t: 0.18, R: { p: [0.02, -0.06, -0.5], r: [0, 2.5, 1.3], grip: 1 } },
+          { t: 0.25, R: { p: [0, -0.07, -0.47], r: [0, 2.5, 1.3], grip: 1 } },
+          { t: 0.42, R: { p: [0.15, -0.12, -0.4], r: [0, 1.5, 0.15], grip: 1, w: 0 } }
+        ],
+        events: [
+          { t: 0, type: "phase", data: { label: "attack_clip.phase.windup" } },
+          { t: 0.08, type: "phase", data: { label: "attack_clip.phase.strike" } },
+          { t: 0.18, type: "impact", data: { kind: "punch" } },
+          { t: 0.25, type: "phase", data: { label: "attack_clip.phase.recover" } }
+        ]
+      },
+      {
+        id: "uppercut",
+        source: { authored: "game-kit", note: "first-person counterpart of attack-clips.json (same duration, same events), for the right hand (the left plays its mirror); authored in the kit, replace with the Elenco team's clips when delivered" },
+        duration: 0.42,
         keys: [
           { t: 0, R: { p: [0.15, -0.12, -0.4], r: [0, 1.5, 0.15], grip: 1, w: 0 } },
-          { t: 0.1, R: { p: [0.21, -0.15, -0.29], r: [0.1, 1.45, 0.2], grip: 1 } },
-          { t: 0.16, R: { p: [0.06, -0.09, -0.62], r: [0, 1.5708, -0.05], grip: 1 } },
-          { t: 0.22, R: { p: [0.07, -0.1, -0.56], r: [0, 1.5708, -0.05], grip: 1 } },
-          { t: 0.35, R: { p: [0.15, -0.12, -0.4], r: [0, 1.5, 0.15], grip: 1, w: 0 } }
+          { t: 0.09, R: { p: [0.12, -0.3, -0.34], r: [0, -1.5708, 1.3], grip: 1 } },
+          { t: 0.19, R: { p: [0.05, -0.02, -0.5], r: [0, -1.5708, 1.45], grip: 1 } },
+          { t: 0.26, R: { p: [0.06, -0.04, -0.48], r: [0, -1.5708, 1.45], grip: 1 } },
+          { t: 0.42, R: { p: [0.15, -0.12, -0.4], r: [0, 1.5, 0.15], grip: 1, w: 0 } }
         ],
         events: [
           { t: 0, type: "phase", data: { label: "attack_clip.phase.windup" } },
-          { t: 0.1, type: "phase", data: { label: "attack_clip.phase.strike" } },
-          { t: 0.16, type: "impact", data: { kind: "punch" } },
-          { t: 0.22, type: "phase", data: { label: "attack_clip.phase.recover" } }
+          { t: 0.09, type: "phase", data: { label: "attack_clip.phase.strike" } },
+          { t: 0.19, type: "impact", data: { kind: "punch" } },
+          { t: 0.26, type: "phase", data: { label: "attack_clip.phase.recover" } }
         ]
       },
       {
@@ -9670,10 +9823,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 +9892,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 +9940,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));
@@ -9845,6 +10000,8 @@ var GameCharactersThree = (() => {
 
   // src/player/room-avatar.ts
   var impactOf = (clip) => clip.events?.find((event) => event.type === "impact")?.t ?? null;
+  var isPunch = (clip) => clip.events?.some((event) => event.type === "impact" && event.data?.kind === "punch") ?? false;
+  var GUARD_SPEED = 0.3;
   var toRoomAvatar = (avatar, options = {}) => {
     const arms = options.firstPerson === false ? null : createFirstPersonArms(avatar.three, {
       colors: { skin: avatar.colors.skin, sleeve: avatar.colors.longSleeves ? avatar.colors.shirt : avatar.colors.skin, trouser: avatar.colors.trousers, shoe: avatar.colors.shoes, ...options.firstPerson?.colors },
@@ -9859,28 +10016,59 @@ var GameCharactersThree = (() => {
       if (!found) mirrored.set(clip.id, found = mirrorPoseClip(clip, `${clip.id}_left`));
       return found;
     };
+    const guard = options.guardClip === false ? void 0 : strikes.get(options.guardClip ?? "fight_guard");
+    const guardHold = options.guardHold ?? 1.2;
+    const punchBlend = options.punchBlend ?? 0.05;
+    let strikeLeft = 0;
+    let guardLeft = 0;
+    let guarding = false;
+    const stepGuard = (dt, state) => {
+      if (!guard) return;
+      const free = state.speed < GUARD_SPEED && !state.down && !state.armed && !state.holding && !state.push && !state.itemUse && !state.running;
+      if (strikeLeft > 0) {
+        strikeLeft -= dt;
+        if (strikeLeft <= 0 && guardLeft > 0 && free) {
+          avatar.play(guard);
+          guarding = true;
+        }
+        return;
+      }
+      guardLeft = Math.max(0, guardLeft - dt);
+      if (guarding && (guardLeft <= 0 || !free || avatar.playing !== guard.id)) {
+        if (avatar.playing === guard.id) avatar.stop();
+        guarding = false;
+      }
+    };
     return {
       root: avatar.root,
       avatar,
       arms,
       ...arms ? { firstPerson: { root: arms.root, update: (dt, state) => arms.update(dt, state) } } : {},
-      update: (dt, state) => avatar.update(dt, {
-        speed: state.speed,
-        running: state.running,
-        crouch: state.crouch,
-        down: state.down,
-        armed: state.armed,
-        pitch: -state.pitch,
-        ...state.holding !== void 0 ? { holding: state.holding } : {},
-        ...state.itemUse !== void 0 ? { itemUse: state.itemUse } : {}
-      }),
+      update: (dt, state) => {
+        stepGuard(dt, state);
+        avatar.update(dt, {
+          speed: state.speed,
+          running: state.running,
+          crouch: state.crouch,
+          down: state.down,
+          armed: state.armed,
+          pitch: -state.pitch,
+          ...state.holding !== void 0 ? { holding: state.holding } : {},
+          ...state.itemUse !== void 0 ? { itemUse: state.itemUse } : {},
+          ...state.push !== void 0 ? { push: state.push } : {}
+        });
+      },
       hand: (side) => avatar.hand(side),
       strike: (clipId, strikeOptions) => {
         const clip = strikes.get(clipId);
         if (!clip) return null;
-        const left = strikeOptions?.leg === "left";
-        avatar.play(left ? leftOf(clip) : clip);
-        arms?.play(clipId, left ? { leg: "left" } : void 0);
+        const left = strikeOptions?.leg === "left" || strikeOptions?.hand === "left";
+        const punch = guard !== void 0 && isPunch(clip);
+        avatar.play(left ? leftOf(clip) : clip, punch ? { blend: punchBlend } : void 0);
+        strikeLeft = punch ? clip.duration : 0;
+        guardLeft = punch ? guardHold : 0;
+        guarding = false;
+        arms?.play(clipId, strikeOptions?.leg === "left" ? { leg: "left" } : strikeOptions?.hand === "left" ? { hand: "left" } : void 0);
         return impactOf(clip);
       }
     };
@@ -9992,6 +10180,7 @@ var GameCharactersThree = (() => {
     return {
       id: AVATAR_AREA_ID,
       name: textOf().name,
+      ground: { surface: "concrete_slab" },
       group: textOf().group,
       state,
       items: () => [],