@adatechnology/game-characters-three 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1017,6 +1017,9 @@ declare const registerBodyMaterial: (world: {
     readonly materials: Map<string, unknown>;
 }) => void;
 
+/** The person builder's spec for a profession of the people pack (look and gear as numbers; the builder draws the rest). */
+declare const personSpecOf: (profession: ProfessionCard) => Record<string, any>;
+
 /** The voice limiter group of the undead (`undead_voice`: five at once, one every 0.25 s, nearer than 40 m). */
 declare const UNDEAD_VOICE_GROUP = "undead_voice";
 /** The sounds of the game and of the art scene for the bodies, in one bank. */
@@ -1041,6 +1044,11 @@ type PlayerAvatarOptions = {
 type AvatarEvent = PoseClipEvent & {
     clip: string;
 };
+type AvatarItemUsePose = {
+    readonly id: string;
+    readonly position: readonly [number, number, number];
+    readonly rotation: readonly [number, number, number];
+};
 type AvatarUpdate = {
     /** Ground speed, m/s. Ties cadence and swing to the ground (the game's `walkCad` and `walkGait`). */
     speed?: number;
@@ -1054,6 +1062,10 @@ type AvatarUpdate = {
     pitch?: number;
     /** Leg yaw toward the step while armed (the game's `P.hip`, radians). */
     hip?: number;
+    /** Whether the player is carrying an item in the right hand. */
+    holding?: boolean;
+    /** Active scripted item use (`drink`, `sip`, `chug`, `pour`, `open`, `close`, `tilt`). */
+    itemUse?: AvatarItemUsePose | null;
 };
 type PlayPoseOptions = {
     onEvent?: (event: AvatarEvent) => void;
@@ -1169,6 +1181,8 @@ type FirstPersonArmsOptions = {
     clips?: readonly FirstPersonClip[];
     /** Seconds to move from one stance (or from a held tool to the rest) to the next. Default 0.18. */
     blend?: number;
+    /** In the `relaxed` stance with no clip playing (walking, standing, nothing in the hands) the hands drop out of the view and are not drawn; a strike, a shove, a held tool or `fists` bring them back. Default false. */
+    hideWhenIdle?: boolean;
     bob?: Partial<FirstPersonBob>;
 };
 type FirstPersonArmsState = {
@@ -1229,6 +1243,8 @@ type RoomAvatarLike = {
         down: boolean;
         armed: boolean;
         pitch: number;
+        holding?: boolean;
+        itemUse?: AvatarItemUsePose | null;
     }): void;
     hand(side: 'R' | 'L'): THREE_NS.Object3D;
     /** The arms of the first-person view (`RoomAvatar.firstPerson`); absent when `toRoomAvatar` was told to make none. */
@@ -1341,4 +1357,4 @@ type TwoBone = {
  */
 declare const solveTwoBone: (root: THREE_NS.Vector3, target: THREE_NS.Vector3, upper: number, lower: number, pole: THREE_NS.Vector3, out: TwoBone) => TwoBone;
 
-export { AVATAR_AREA_ID, type AreaContext, type AvatarEvent, type AvatarTestOptions, type AvatarUpdate, BAKE_NEUTRAL_POSE, BODY_CHUNK, BODY_MATERIAL_DEF, BODY_SOUNDS, type BakeBuilders, type BakeSpec, type BakedBody, type BestBuilder, type BestBuilderOptions, type BestTypeCard, type BloodAge, type BloodLook, type BloodLookOptions, type BloodSink, type BodyBatch, type BodyBatchOptions, type BodyChunkOptions, type BodyInstance, type BodyJoints, type BodyMaterialParams, type BodySoundRule, type BodyVariant, type BuildInstancedBodyParams, CHARACTERS_AREA_ID, CHARACTER_SOUNDS, CHARACTER_SOUND_BANK, type CharacterSound, type CharacterSoundOptions, type CharacterSoundSink, type CharacterSoundStyle, type CharactersTestOptions, EXTRAS, type EyeOptions, type Eyes, FACE_FEATURES, FIRST_PERSON_BOB, FIRST_PERSON_COLORS, FIRST_PERSON_RIG, FIRST_PERSON_STANCES, type FilmSink, type FirstPersonArms, type FirstPersonArmsOptions, type FirstPersonArmsState, type FirstPersonBob, type FirstPersonColors, type FirstPersonEvent, type FirstPersonRig, type FluidsBridge, type FluidsBridgeOptions, type FlyingLimb, type FlyingLimbs, type FlyingLimbsOptions, type FlyingPiece, type FlyingPieces, type FlyingPiecesOptions, HAND_ITEMS, HATS, HIT_PRESETS, type HitPreset, LOD_BAKE, LOD_BATCH_CAPACITY, LOD_CASTS_SHADOW, LOD_DISTANCES, LOD_SEGMENTS, type LimbEffects, type LimbLaunch, PENDULUM, PERSON_ITEM_PREFIX, PLAYER_SOUNDS, type Pendulum, type PersonBuilder, type PersonBuilderOptions, type PlayPoseOptions, type PlayerAvatar, type PlayerAvatarColors, type PlayerAvatarOptions, type PlayerAvatarSpec, type PoseTargets, type ProfessionCard, type RestPose, type RichRig, type RigAnimator, type RigAnimatorOptions, type RoomAvatarLike, type StanceDef, type Three, type ToRoomAvatarOptions, type TwoBone, UNDEAD_VOICES, UNDEAD_VOICE_GROUP, UNDEAD_VOICE_SOURCES, type UndeadCard, type UndeadLike, type UndeadVoice, type VariantType, type VoiceMoment, type VoiceStep, type WoundBody, type WoundMaterials, type WoundNode, type WoundSpray, type Wounds, type WoundsOptions, ZOMBIE_ITEM_PREFIX, bakeBody, bakeVariants, blobGeometry, blobRadii, bloodLookOfAge, buildInstancedBody, createAvatarTestModule, createBestBuilder, createBodyBatch, createBodyChunk, createBodyMaterial, createCharacterSound, createCharactersTestModule, createEye, createFirstPersonArms, createFluidsBridge, createFlyingLimbs, createFlyingPieces, createGlowTexture, createPendulum, createPersonBuilder, createPlayerAvatar, createRigAnimator, createVariantBatches, createWoundMaterials, createWounds, exitWound, explodeChunks, findEyes, gouge, jointsOf, lodAt, makeCut, makeStump, registerBodyMaterial, ringWound, solveTwoBone, starGeometry, stepPendulum, toRoomAvatar, woundBodyOf, woundDecal };
+export { AVATAR_AREA_ID, type AreaContext, type AvatarEvent, type AvatarItemUsePose, type AvatarTestOptions, type AvatarUpdate, BAKE_NEUTRAL_POSE, BODY_CHUNK, BODY_MATERIAL_DEF, BODY_SOUNDS, type BakeBuilders, type BakeSpec, type BakedBody, type BestBuilder, type BestBuilderOptions, type BestTypeCard, type BloodAge, type BloodLook, type BloodLookOptions, type BloodSink, type BodyBatch, type BodyBatchOptions, type BodyChunkOptions, type BodyInstance, type BodyJoints, type BodyMaterialParams, type BodySoundRule, type BodyVariant, type BuildInstancedBodyParams, CHARACTERS_AREA_ID, CHARACTER_SOUNDS, CHARACTER_SOUND_BANK, type CharacterSound, type CharacterSoundOptions, type CharacterSoundSink, type CharacterSoundStyle, type CharactersTestOptions, EXTRAS, type EyeOptions, type Eyes, FACE_FEATURES, FIRST_PERSON_BOB, FIRST_PERSON_COLORS, FIRST_PERSON_RIG, FIRST_PERSON_STANCES, type FilmSink, type FirstPersonArms, type FirstPersonArmsOptions, type FirstPersonArmsState, type FirstPersonBob, type FirstPersonColors, type FirstPersonEvent, type FirstPersonRig, type FluidsBridge, type FluidsBridgeOptions, type FlyingLimb, type FlyingLimbs, type FlyingLimbsOptions, type FlyingPiece, type FlyingPieces, type FlyingPiecesOptions, HAND_ITEMS, HATS, HIT_PRESETS, type HitPreset, LOD_BAKE, LOD_BATCH_CAPACITY, LOD_CASTS_SHADOW, LOD_DISTANCES, LOD_SEGMENTS, type LimbEffects, type LimbLaunch, PENDULUM, PERSON_ITEM_PREFIX, PLAYER_SOUNDS, type Pendulum, type PersonBuilder, type PersonBuilderOptions, type PlayPoseOptions, type PlayerAvatar, type PlayerAvatarColors, type PlayerAvatarOptions, type PlayerAvatarSpec, type PoseTargets, type ProfessionCard, type RestPose, type RichRig, type RigAnimator, type RigAnimatorOptions, type RoomAvatarLike, type StanceDef, type Three, type ToRoomAvatarOptions, type TwoBone, UNDEAD_VOICES, UNDEAD_VOICE_GROUP, UNDEAD_VOICE_SOURCES, type UndeadCard, type UndeadLike, type UndeadVoice, type VariantType, type VoiceMoment, type VoiceStep, type WoundBody, type WoundMaterials, type WoundNode, type WoundSpray, type Wounds, type WoundsOptions, ZOMBIE_ITEM_PREFIX, bakeBody, bakeVariants, blobGeometry, blobRadii, bloodLookOfAge, buildInstancedBody, createAvatarTestModule, createBestBuilder, createBodyBatch, createBodyChunk, createBodyMaterial, createCharacterSound, createCharactersTestModule, createEye, createFirstPersonArms, createFluidsBridge, createFlyingLimbs, createFlyingPieces, createGlowTexture, createPendulum, createPersonBuilder, createPlayerAvatar, createRigAnimator, createVariantBatches, createWoundMaterials, createWounds, exitWound, explodeChunks, findEyes, gouge, jointsOf, lodAt, makeCut, makeStump, personSpecOf, registerBodyMaterial, ringWound, solveTwoBone, starGeometry, stepPendulum, toRoomAvatar, woundBodyOf, woundDecal };

package/dist/index.global.js

@@ -84,6 +84,7 @@ var GameCharactersThree = (() => {
     lodAt: () => lodAt,
     makeCut: () => makeCut,
     makeStump: () => makeStump,
+    personSpecOf: () => personSpecOf,
     registerBodyMaterial: () => registerBodyMaterial,
     ringWound: () => ringWound,
     solveTwoBone: () => solveTwoBone,
@@ -1716,6 +1717,13 @@ var GameCharactersThree = (() => {
     legRBroken: 256,
     jaw: 512
   };
+  var KIT_ORIGIN_KEY = "kitOrigin";
+  function markKitOrigin(object2, origin) {
+    const node = object2;
+    node.userData = node.userData ?? {};
+    node.userData[KIT_ORIGIN_KEY] = { ...origin };
+    return object2;
+  }
 
   // ../game-characters/dist/index.js
   var __defProp2 = Object.defineProperty;
@@ -5430,7 +5438,8 @@ var GameCharactersThree = (() => {
       root.userData.rig = rig;
       return root;
     }
-    return { build, TYPES, setLOD(k) {
+    const marked = (...args) => markKitOrigin(build(...args), { owner: "game-characters-three", kind: "person" });
+    return { build: marked, TYPES, setLOD(k) {
       LK = k;
       SEG = Math.max(5, Math.round(16 * k));
     }, topM: () => topM_ref };
@@ -6656,7 +6665,11 @@ var GameCharactersThree = (() => {
       chars.forEach((c) => pose(c, c.z, 0, 0));
       return { root, chars };
     }
-    return { build, pose, zombify, buildPerson };
+    const mark = (c) => {
+      markKitOrigin(c.root, { owner: "game-characters-three", kind: "person" });
+      return c;
+    };
+    return { build: (sp, idx) => mark(build(sp, idx)), pose, zombify, buildPerson: (p2, zed) => mark(buildPerson(p2, zed)) };
   };
 
   // src/eyes.ts
@@ -8608,7 +8621,17 @@ var GameCharactersThree = (() => {
       fem: false,
       life: 1,
       hs: "short",
-      hair: "2a1e16"
+      hair: "2a1e16",
+      pose: {
+        armL: 0,
+        armR: 0,
+        elbL: -0.12,
+        elbR: -0.12,
+        armOut: 0.11,
+        lean: 0.04,
+        headX: 0,
+        headZ: 0
+      }
     },
     shirtColor: "3d5a73"
   };
@@ -8619,9 +8642,12 @@ var GameCharactersThree = (() => {
   var CLIP_BLEND = 0.12;
   var FALL_SECONDS2 = 0.3;
   var HIP_HEIGHT = 0.95;
-  var WALK_ARM = 0.45;
+  var WALK_ARM = 0.28;
   var WALK_BOB = 0.035;
   var WALK_LEAN = 0.04;
+  var RUN_LEAN = 0.16;
+  var RUN_BOB = 0.05;
+  var REST_ARM_Z = 0.18;
   var CROUCH = { thigh: -0.95, thighWalk: 0.3, shin: 1.9, lean: 0.25, drop: -0.35 };
   var AIMED = { shoulder: -1.42, perAim: 0.85, swing: 0.02, zRight: -0.54, zLeft: 0.36, elbowRight: -0.04, elbowLeft: -0.12 };
   var DOWN = { thighWalk: 0.5, shinSwing: 0.85, shinBend: 1.3, armHigh: -2.8, armLow: -0.35, armWave: 0.3, armZ: 0.5, armZWave: 0.3, tilt: 1.5, roll: 0.3, hipY: 0.16, hipZ: 0.6, hipZFlip: 1.2 };
@@ -8630,7 +8656,18 @@ var GameCharactersThree = (() => {
   var clamp = (value, min, max) => Math.min(max, Math.max(min, value));
   var fract = (value) => value - Math.floor(value);
   var createPlayerAvatar = (THREE, options = {}) => {
-    const spec = { ...player_avatar_default.spec, ...options.spec };
+    const pose = {
+      armL: 0,
+      armR: 0,
+      elbL: -0.08,
+      elbR: -0.08,
+      lean: 0.04,
+      headX: 0,
+      headZ: 0,
+      ...player_avatar_default.spec.pose,
+      ...options.spec?.pose
+    };
+    const spec = { ...player_avatar_default.spec, ...options.spec, pose };
     for (const key of ["skin", "hair"]) if (typeof spec[key] === "string") spec[key] = hexOf(spec[key]);
     const best = createBestBuilder(THREE, { types: [{ name: String(spec.type), eye: 0 }], random: createRng(Number(spec.seed ?? 1)) });
     const body = best.build(spec);
@@ -8665,6 +8702,41 @@ var GameCharactersThree = (() => {
       sockets[side].position.set(HAND_OFFSET.x, HAND_OFFSET.y, HAND_OFFSET.z);
       armOf[side].el.add(sockets[side]);
     }
+    const addMesh = (parent, geometry, material, x = 0, y = 0, z = 0, rx = 0, ry = 0, rz = 0) => {
+      const mesh2 = new THREE.Mesh(geometry, material);
+      mesh2.position.set(x, y, z);
+      if (rx || ry || rz) mesh2.rotation.set(rx, ry, rz);
+      mesh2.castShadow = true;
+      mesh2.receiveShadow = true;
+      parent.add(mesh2);
+      return mesh2;
+    };
+    const hands = [];
+    rig.arms.forEach((arm, index) => {
+      const el = arm.el;
+      const side = index === 0 ? 1 : -1;
+      const oldHand = meshesOf(el).find((mesh2) => Math.abs(mesh2.position.y + 0.33) < 0.025);
+      const handMaterial = oldHand?.material ?? new THREE.MeshLambertMaterial({ color: colors.skin });
+      if (oldHand) {
+        oldHand.geometry?.dispose();
+        el.remove(oldHand);
+      }
+      const hg = new THREE.Group();
+      hg.name = side > 0 ? "hand_group_L" : "hand_group_R";
+      hg.position.set(side * 0.02, -0.3, 0.01);
+      el.add(hg);
+      const palm = addMesh(hg, new THREE.SphereGeometry(0.048, 14, 10), handMaterial, 0, -0.035, 0);
+      palm.scale.set(0.6, 1.05, 1);
+      const built = buildHand({ THREE, add: addMesh, hg, handM: handMaterial, s: side, detailed: true });
+      hands.push({ side, hg, fingers: built.fingers, th: built.th });
+    });
+    const setHandGrip = (hand, grip, wristX = 0) => {
+      hand.fingers.forEach((finger, j) => {
+        finger.rotation.z = -hand.side * grip * (j % 2 ? 1.1 : 0.9);
+      });
+      if (hand.th) hand.th.rotation.z = -hand.side * (0.32 + grip * 0.25);
+      hand.hg.rotation.x = wristX;
+    };
     const legRestX = rig.legs.map((leg) => leg.g.position.x);
     const legSide = (index) => index === 0 ? 1 : -1;
     let cycles = 0;
@@ -8706,6 +8778,42 @@ var GameCharactersThree = (() => {
       });
       return { armR: shoulder, armL: shoulder, armRz: AIMED.zRight, armLz: AIMED.zLeft, elbR: AIMED.elbowRight, elbL: AIMED.elbowLeft };
     };
+    const holdingPose = (gait, itemUse) => {
+      const bob = Math.sin(cycles * TWO_PI2) * 0.05 * gait;
+      if (!itemUse) {
+        return { armL: -0.45 + bob, armLz: 0.22, elbL: -1.05 };
+      }
+      const { id, position, rotation } = itemUse;
+      if (id === "drink" || id === "sip" || id === "chug") {
+        const raise2 = clamp((position[1] + 0.2) / 0.22, 0, 1);
+        const tilt3 = clamp(Math.abs(rotation[0]) / 1.22, 0, 1.15);
+        return {
+          armL: -0.45 - 0.95 * raise2 - 0.22 * tilt3,
+          armLz: 0.22 + 0.44 * raise2,
+          elbL: -1.05 - 0.85 * raise2 + 0.12 * tilt3,
+          headX: -0.26 * tilt3
+        };
+      }
+      if (id === "open" || id === "close") {
+        const reach = clamp((0.22 - position[0]) / 0.12, 0, 1);
+        return {
+          armL: -0.45 - 0.35 * reach,
+          armLz: 0.22 + 0.28 * reach,
+          elbL: -1.05 - 0.25 * reach,
+          armR: -0.78 * reach,
+          armRz: -0.48 * reach,
+          elbR: -1.25 * reach
+        };
+      }
+      const raise = clamp((position[1] + 0.2) / 0.25, 0, 1);
+      const tilt2 = clamp(Math.abs(rotation[0]) / 1.75, 0, 1.2);
+      const ext = Math.max(raise, tilt2 * 0.75);
+      return {
+        armL: -0.45 - 0.48 * ext,
+        armLz: 0.22 + 0.08 * ext,
+        elbL: -1.05 + 0.38 * ext
+      };
+    };
     const resetLegYaw = () => {
       rig.legs.forEach((leg, index) => {
         leg.g.rotation.y = 0;
@@ -8713,6 +8821,32 @@ var GameCharactersThree = (() => {
         leg.g.position.z = 0;
       });
     };
+    const runningPose = (gait, busyHands = false) => {
+      const ph = cycles * TWO_PI2;
+      const sine = Math.sin(ph);
+      const cosine = Math.cos(ph);
+      const legL = sine * 0.65 * gait;
+      const legR = -sine * 0.65 * gait;
+      const kneeL = Math.max(0, -cosine) * 1.15 * gait;
+      const kneeR = Math.max(0, cosine) * 1.15 * gait;
+      const targets = {
+        lean: RUN_LEAN * Math.min(1, gait),
+        drop: Math.abs(cosine) * RUN_BOB * gait,
+        legL,
+        legR,
+        kneeL,
+        kneeR
+      };
+      if (!busyHands) {
+        targets.armR = -0.32 - sine * 0.65 * gait;
+        targets.armL = -0.32 + sine * 0.65 * gait;
+        targets.elbR = -1.25 + Math.max(0, sine) * 0.3 * gait;
+        targets.elbL = -1.25 + Math.max(0, -sine) * 0.3 * gait;
+        targets.armRz = 0.22;
+        targets.armLz = -0.22;
+      }
+      return targets;
+    };
     const crouchPose = (gait) => {
       const swing = (leg) => {
         const legS = legSide(leg);
@@ -8808,23 +8942,44 @@ var GameCharactersThree = (() => {
       update(dt, state = {}) {
         const speed = state.speed ?? 0;
         const moving = speed >= 0.05;
-        if (moving) cycles += dt * walkCadence(speed);
+        const down = !!state.down;
+        const running = Boolean(state.running && moving && !down && !state.crouch);
+        if (moving) cycles += dt * (running ? walkCadence(speed) * 1.3 : walkCadence(speed));
         const gait = Math.min(MAX_GAIT, walkGait(speed));
-        profile.arm = WALK_ARM * gait;
-        profile.bob = WALK_BOB * gait;
-        time = cycles / walkCadence(Math.max(speed, 0));
+        profile.arm = (running ? 0.55 : WALK_ARM) * gait;
+        profile.bob = (running ? RUN_BOB : WALK_BOB) * gait;
+        time = cycles / (walkCadence(Math.max(speed, 0)) * (running ? 1.3 : 1));
         animator.animate(body, time, { speed });
-        const down = !!state.down;
         fall = fallSeconds <= 0 ? down ? 1 : 0 : clamp(fall + (down ? dt : -dt) / fallSeconds, 0, 1);
         resetLegYaw();
         if (down) animator.setPose(rig, downPose());
         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));
+          else if (state.holding || state.itemUse) animator.setPose(rig, holdingPose(gait, state.itemUse));
+          else if (!running) {
+            animator.setPose(rig, {
+              armRz: REST_ARM_Z,
+              armLz: -REST_ARM_Z,
+              elbR: -0.12,
+              elbL: -0.12
+            });
+          }
         }
         placeBody(fall);
         stepClip(dt, down);
         if (smooth) animator.cascade(rig, 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 wristSwing = holdRight || state.armed || running ? 0 : -Math.min(1, gait) * Math.sin(ph - 0.6) * 0.12 * hand.side;
+          setHandGrip(hand, grip, wristSwing);
+        });
       },
       play(clip, playOptions = {}) {
         const found = typeof clip === "string" ? clips.get(clip) : clip;
@@ -9152,7 +9307,7 @@ var GameCharactersThree = (() => {
     },
     stances: {
       relaxed: {
-        R: { p: [0.2, -0.2, -0.36], r: [0.2, 1.45, -0.4], grip: 0.35 },
+        R: { p: [0.2, -0.22, -0.36], r: [0.05, 1.57, -0.05], grip: 0.2 },
         L: "mirror"
       },
       fists: {
@@ -9296,6 +9451,10 @@ var GameCharactersThree = (() => {
   var CONTACT_PALM = 0.03;
   var FOOT_LENGTH = 0.24;
   var FOOT_SHOWN = 1e-3;
+  var AWAY_DROP = 0.55;
+  var AWAY_OUT = 7;
+  var AWAY_IN = 20;
+  var AWAY_HIDDEN = 0.97;
   var FILL = 0.3;
   var FIRST_PERSON_STANCES = first_person_arms_default.stances;
   var FIRST_PERSON_RIG = first_person_arms_default.rig;
@@ -9354,7 +9513,7 @@ var GameCharactersThree = (() => {
     const bob = { ...FIRST_PERSON_BOB, ...options.bob };
     const blendSeconds = options.blend ?? DEFAULT_BLEND;
     const clips = new Map((options.clips ?? []).map((clip) => [clip.id, clip]));
-    const root = new THREE.Group();
+    const root = markKitOrigin(new THREE.Group(), { owner: "game-characters-three", kind: "person", id: "first-person-arms" });
     root.name = "first-person-arms";
     root.userData.viewmodel = true;
     const lit = (color2) => new THREE.MeshLambertMaterial({ color: color2, emissive: scaleHex(color2, FILL) });
@@ -9409,7 +9568,7 @@ var GameCharactersThree = (() => {
       const cuff = limb2(root, rig.radius.cuff, rig.radius.cuff, 0.03, materials.cuff);
       const elbow = ball(root, rig.radius.elbow * 1.02, materials.sleeve);
       elbow.name = `first-person-elbow-${side}`;
-      arms[side] = { side, sign: sign2, hand, anchor, upper, fore, cuff, elbow, shown: newPose(THREE), from: newPose(THREE), mode: null, blend: 1, drawn: newPose(THREE), joints: { shoulder: new THREE.Vector3(), elbow: new THREE.Vector3(), wrist: new THREE.Vector3() } };
+      arms[side] = { side, sign: sign2, hand, anchor, upper, fore, cuff, elbow, shown: newPose(THREE), from: newPose(THREE), mode: null, blend: 1, drawn: newPose(THREE), joints: { shoulder: new THREE.Vector3(), elbow: new THREE.Vector3(), wrist: new THREE.Vector3() }, away: options.hideWhenIdle ? 1 : 0 };
     }
     const leg = new THREE.Group();
     leg.name = "first-person-leg";
@@ -9503,6 +9662,7 @@ var GameCharactersThree = (() => {
     const desired = newPose(THREE);
     const channelPose = newPose(THREE);
     const mixed = newPose(THREE);
+    const dropped = newPose(THREE);
     let indexCurl;
     const bone = createTwoBone(THREE);
     const shoulder = new THREE.Vector3();
@@ -9627,11 +9787,22 @@ var GameCharactersThree = (() => {
           if (arm.blend >= 1) copyPose(arm.shown, desired);
           else mixPose(THREE, arm.shown, arm.from, desired, ease2(arm.blend));
           const channel = sample?.[side];
+          let pose;
           if (channel && channel.w > 0) {
             fromChannel(channel, side, arm.shown, channelPose);
             mixPose(THREE, mixed, arm.shown, channelPose, channel.w);
-            drawArm(arm, mode === "target" ? mixed : keepOutside(mixed, handReach(mixed)));
-          } else drawArm(arm, mode === "target" ? arm.shown : keepOutside(arm.shown, handReach(arm.shown)));
+            pose = mode === "target" ? mixed : keepOutside(mixed, handReach(mixed));
+          } else pose = mode === "target" ? arm.shown : keepOutside(arm.shown, handReach(arm.shown));
+          const idle = options.hideWhenIdle === true && mode === "rest:relaxed" && !(channel && channel.w > 0);
+          arm.away = options.hideWhenIdle ? Math.min(1, Math.max(0, arm.away + ((idle ? 1 : 0) - arm.away) * Math.min(1, dt * (idle ? AWAY_OUT : AWAY_IN)))) : 0;
+          if (arm.away > 0) {
+            copyPose(dropped, pose);
+            dropped.p.y -= AWAY_DROP * ease2(arm.away);
+            pose = dropped;
+          }
+          drawArm(arm, pose);
+          const shown = arm.away < AWAY_HIDDEN;
+          for (const part of [arm.anchor, arm.upper, arm.fore, arm.cuff, arm.elbow]) part.visible = shown;
         }
         const foot = sample?.F;
         leg.visible = !!foot && foot.w > FOOT_SHOWN;
@@ -9678,6 +9849,7 @@ var GameCharactersThree = (() => {
     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 },
       clips: options.firstPersonClips ?? FIRST_PERSON_CLIPS,
+      hideWhenIdle: true,
       ...options.firstPerson
     });
     const strikes = new Map((options.strikeClips ?? ATTACK_CLIPS).map((clip) => [clip.id, clip]));
@@ -9692,7 +9864,16 @@ var GameCharactersThree = (() => {
       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 }),
+      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 } : {}
+      }),
       hand: (side) => avatar.hand(side),
       strike: (clipId, strikeOptions) => {
         const clip = strikes.get(clipId);