@adatechnology/game-characters-three 0.5.1 → 0.7.0

package/dist/index.js

@@ -993,7 +993,7 @@ var createBestBuilder = (host, { types, random = Math.random }) => {
       });
     }
     const neckLen = 0.14 + Math.max(0, P.neck);
-    if (!cut.head) add(U, CYL(0.058, 0.068, neckLen, SEG), skinM, 0, 1.63 + Math.max(0, P.neck) / 2, 0);
+    const neck = cut.head ? void 0 : add(U, CYL(0.058, 0.068, neckLen, SEG), skinM, 0, 1.63 + Math.max(0, P.neck) / 2, 0);
     const headG = new THREE.Group();
     headG.position.set(0, 1.64 + P.neck, P.headFwd || 0);
     headG.rotation.x = P.headX;
@@ -1200,6 +1200,7 @@ var createBestBuilder = (host, { types, random = Math.random }) => {
       if (o.userData.flap) flaps.push(o);
     });
     const rig = { flaps, dangles: arms.filter((a) => a.el.userData.dangle), type: spec.type || "Lento", fig, upper, headG, arms, legs, P, ph: spec.phase ?? options.random() * 6, dropBase: fig.position.y, leanBase: P.lean, hxBase: P.headX };
+    if (neck) Object.defineProperty(rig, "neck", { value: neck });
     if (spec.lying) {
       root.rotation.x = -PI / 2;
       root.position.set(0, 0.16 * P.s, 0.9 * P.s);
@@ -3751,7 +3752,8 @@ function createCharactersTestModule(options = {}) {
   const makeKit = () => options.createKit ? options.createKit({ penetration: settings.penetration, deathRule: settings.deathRule }) : createCharacters({ ...options.packs ? { packs: options.packs } : {}, penetration: settings.penetration, damage: { deathRule: settings.deathRule } });
   let kit = makeKit();
   let undead = options.createUndead ? options.createUndead(kit) : null;
-  const random = createRng3(options.seed ?? 1);
+  let stream = createRng3(options.seed ?? 1);
+  const random = () => stream();
   let seedCounter = 100;
   let host = null;
   let three = null;
@@ -4131,6 +4133,14 @@ function createCharactersTestModule(options = {}) {
       wounds = createWounds(lent.THREE, { random, scene: scene2, groundAt: (x, z) => lent.groundAt(x, z), ...bridge ? { bridge } : {}, ...sound ? { sound } : {} });
       for (const entry of entries.values()) trackEntry(entry);
       const stopChange = lent.bench?.onChange(onChange);
+      const stopReset = lent.onReset?.(() => {
+        stream = createRng3(options.seed ?? 1);
+        seedCounter = 100;
+        time = 0;
+        selected = null;
+        lastCrossed = 0;
+        lastEnergy = 1;
+      });
       const stopEvents = lent.on((event) => {
         if (event.type !== "explosion") return;
         for (const entry of entries.values()) {
@@ -4155,6 +4165,7 @@ function createCharactersTestModule(options = {}) {
       });
       return () => {
         stopChange?.();
+        stopReset?.();
         stopEvents();
         stopFrame();
         clearOverlays();
@@ -4201,6 +4212,7 @@ import {
   filterPoseChannels,
   samplePoseClip,
   walkCadence,
+  stepCascade as stepCascade2,
   walkGait
 } from "@adatechnology/game-characters";
 
@@ -4235,12 +4247,272 @@ var player_avatar_default = {
   shirtColor: "3d5a73"
 };
 
+// src/first-person/ik.ts
+var solveTwoBone = (root, target, upper, lower, pole, out) => {
+  const line = out.line.copy(target).sub(root);
+  let distance2 = line.length();
+  if (distance2 < 1e-6) line.set(0, 0, -1);
+  else line.divideScalar(distance2);
+  const min = Math.abs(upper - lower) + 1e-4;
+  const max = upper + lower - 1e-4;
+  out.clamped = distance2 > max || distance2 < min;
+  distance2 = Math.min(max, Math.max(min, distance2));
+  const along = (distance2 * distance2 + upper * upper - lower * lower) / (2 * distance2);
+  const across = Math.sqrt(Math.max(0, upper * upper - along * along));
+  const side = out.side.copy(pole);
+  side.addScaledVector(line, -side.dot(line));
+  if (side.lengthSq() < 1e-8) side.set(0, 1, 0).addScaledVector(line, -line.y);
+  if (side.lengthSq() < 1e-8) side.set(1, 0, 0);
+  side.normalize();
+  out.joint.copy(root).addScaledVector(line, along).addScaledVector(side, across);
+  out.end.copy(root).addScaledVector(line, distance2);
+  return out;
+};
+var createTwoBone = (THREE) => ({ joint: new THREE.Vector3(), end: new THREE.Vector3(), clamped: false, line: new THREE.Vector3(), side: new THREE.Vector3() });
+
+// src/player/arm-reach.ts
+var ARM_REACH = {
+  /** The elbow never straightens past this bend (a locked elbow reads as a stick). */
+  elbowMin: 0.12,
+  /** Full flexion of the elbow. */
+  elbowMax: 2.5,
+  /** The wrist bends (flexion, extension, deviation) up to this angle from the line of the forearm (flexion reaches about 80 degrees). */
+  wristBend: 1.3,
+  /** The forearm turns (pronation and supination) up to this angle about its own axis. */
+  wristTwist: 1.6,
+  /** The most the chest turns to bring the support shoulder toward a far hand. */
+  chestTurn: 0.6,
+  /** The most a shoulder blade slides toward a far hand (protraction and elevation together). */
+  protraction: 0.11,
+  /** A hand is within reach below this fraction of the arm's length. */
+  slack: 0.96,
+  /** Where the elbow points: down and out from the body, a little back (body space, x outward). */
+  elbowPole: [0.55, -1, -0.25],
+  /** The support arm's elbow: under the gun, hardly out of the body (the first-person arms' `elbowPoleLeft`), so the forearm meets the handguard nearer the aim's line. */
+  elbowPoleSupport: [0.1, -1, -0.2],
+  /** From the wrist joint to the middle of the palm, metres of the body. */
+  palm: 0.042,
+  /** In a view the elbow keeps at least this interior bend where a hand is out of reach, right then left (the first-person arms' numbers). */
+  viewBend: [1.35, 0.95],
+  /** In a view a hand stays this far before a surface, metres. */
+  contactMargin: 5e-3,
+  /** In a view a hand is never nearer than this to the eye, metres. */
+  contactNearest: 0.12,
+  /** How far in front of the eye a surface is looked for, metres. */
+  contactProbe: 1.4,
+  /** How far a hand reaches forward of its middle at least (the thickness of the palm), and per metre of fingers pointing ahead. */
+  contactPalm: 0.03,
+  /** From the middle of the palm to the fingertips. */
+  contactFingers: 0.085
+};
+var createArmReach = (THREE, rig, hands) => {
+  const arms = {
+    R: { g: rig.arms[1].g, el: rig.arms[1].el, hand: hands.R, outward: -1 },
+    L: { g: rig.arms[0].g, el: rig.arms[0].el, hand: hands.L, outward: 1 }
+  };
+  const upper = rig.upper;
+  const handBasis = {
+    R: new THREE.Quaternion().setFromRotationMatrix(new THREE.Matrix4().makeBasis(new THREE.Vector3(0, -1, 0), new THREE.Vector3(-1, 0, 0), new THREE.Vector3(0, 0, -1))).invert(),
+    L: new THREE.Quaternion().setFromRotationMatrix(new THREE.Matrix4().makeBasis(new THREE.Vector3(0, -1, 0), new THREE.Vector3(1, 0, 0), new THREE.Vector3(0, 0, 1))).invert()
+  };
+  const saved = {
+    twist: 0,
+    arms: { R: { position: new THREE.Vector3(), g: new THREE.Quaternion(), el: new THREE.Quaternion(), hand: new THREE.Quaternion() }, L: { position: new THREE.Vector3(), g: new THREE.Quaternion(), el: new THREE.Quaternion(), hand: new THREE.Quaternion() } }
+  };
+  let applied = false;
+  const bone = createTwoBone(THREE);
+  const v = { shoulder: new THREE.Vector3(), elbow: new THREE.Vector3(), wrist: new THREE.Vector3(), palm: new THREE.Vector3(), target: new THREE.Vector3(), pole: new THREE.Vector3(), a: new THREE.Vector3(), b: new THREE.Vector3(), c: new THREE.Vector3() };
+  const q = { hand: new THREE.Quaternion(), parent: new THREE.Quaternion(), body: new THREE.Quaternion(), local: new THREE.Quaternion(), swing: new THREE.Quaternion(), twist: new THREE.Quaternion(), rest: new THREE.Quaternion() };
+  const basis = new THREE.Matrix4();
+  const camera = { position: new THREE.Vector3(), quaternion: new THREE.Quaternion(), inverse: new THREE.Quaternion(), probe: new THREE.Vector3(), forward: new THREE.Vector3(), fingers: new THREE.Vector3(), hand: new THREE.Quaternion() };
+  let bendLimit = null;
+  const yAxis = new THREE.Vector3(0, 1, 0);
+  const lengthsOf = (arm) => {
+    const scale = arm.g.getWorldScale(v.a).y;
+    return { upper: arm.el.position.length() * scale, fore: arm.hand.position.length() * scale, palm: ARM_REACH.palm * scale };
+  };
+  const limitOf = (side, upperLength, fore) => {
+    if (!bendLimit) return (upperLength + fore) * ARM_REACH.slack;
+    return Math.sqrt(upperLength * upperLength + fore * fore + 2 * upperLength * fore * Math.cos(bendLimit[side === "R" ? 0 : 1]));
+  };
+  const wristOf = (side, pose, palm) => {
+    q.hand.set(...pose.quaternion).multiply(handBasis[side]);
+    v.palm.set(...pose.position);
+    v.wrist.copy(v.palm).addScaledVector(v.a.set(0, -1, 0).applyQuaternion(q.hand), -palm);
+  };
+  const turnChest = (pose) => {
+    const { upper: up, fore, palm } = lengthsOf(arms.L);
+    wristOf("L", pose, palm);
+    const excess = arms.L.g.getWorldPosition(v.shoulder).distanceTo(v.wrist) - limitOf("L", up, fore);
+    if (excess <= 0) return;
+    const chestRadius = Math.hypot(arms.L.g.position.x, arms.L.g.position.z) * arms.L.g.getWorldScale(v.a).y;
+    upper.rotation.y -= Math.min(ARM_REACH.chestTurn, excess / Math.max(0.05, chestRadius));
+    upper.updateMatrixWorld(true);
+  };
+  const protract = (arm, limit) => {
+    const excess = arm.g.getWorldPosition(v.shoulder).distanceTo(v.wrist) - limit;
+    if (excess <= 0) return;
+    const parent = arm.g.parent;
+    v.b.copy(v.wrist).sub(v.shoulder).normalize().multiplyScalar(Math.min(excess, ARM_REACH.protraction)).add(v.shoulder);
+    arm.g.position.copy(parent.worldToLocal(v.b));
+    arm.g.updateMatrixWorld(true);
+  };
+  const limitWrist = (local) => {
+    const projection = v.c.set(local.x, local.y, local.z).projectOnVector(yAxis);
+    q.twist.set(projection.x, projection.y, projection.z, local.w).normalize();
+    const twistAngle = 2 * Math.atan2(q.twist.y, q.twist.w);
+    const swing = q.swing.copy(local).multiply(q.twist.invert());
+    const swingAngle = 2 * Math.acos(Math.min(1, Math.abs(swing.w)));
+    if (swingAngle > ARM_REACH.wristBend) swing.slerp(q.rest.identity(), 1 - ARM_REACH.wristBend / swingAngle);
+    const clampedTwist = Math.max(-ARM_REACH.wristTwist, Math.min(ARM_REACH.wristTwist, Math.atan2(Math.sin(twistAngle), Math.cos(twistAngle))));
+    return local.copy(swing).multiply(q.twist.setFromAxisAngle(yAxis, clampedTwist));
+  };
+  const reach = (side, pose) => {
+    const arm = arms[side];
+    const { upper: up, fore, palm } = lengthsOf(arm);
+    wristOf(side, pose, palm);
+    protract(arm, limitOf(side, up, fore));
+    arm.g.getWorldPosition(v.shoulder);
+    upper.getWorldQuaternion(q.body);
+    const pole = side === "L" ? ARM_REACH.elbowPoleSupport : ARM_REACH.elbowPole;
+    v.pole.set(pole[0] * arm.outward, pole[1], pole[2]).applyQuaternion(q.body);
+    const lockLimit = Math.sqrt(up * up + fore * fore + 2 * up * fore * Math.cos(ARM_REACH.elbowMin));
+    const most = bendLimit ? Math.min(lockLimit, limitOf(side, up, fore)) : lockLimit;
+    const least = Math.sqrt(up * up + fore * fore + 2 * up * fore * Math.cos(ARM_REACH.elbowMax));
+    const line = v.c.copy(v.wrist).sub(v.shoulder);
+    const distance2 = Math.min(most, Math.max(least, line.length()));
+    v.target.copy(v.shoulder).addScaledVector(line.normalize(), distance2);
+    solveTwoBone(v.shoulder, v.target, up, fore, v.pole, bone);
+    const along = v.a.copy(bone.joint).sub(v.shoulder).normalize();
+    const forearm = v.b.copy(bone.end).sub(bone.joint).normalize();
+    const fold = v.c.copy(forearm).addScaledVector(along, -forearm.dot(along));
+    if (fold.lengthSq() < 1e-8) fold.copy(v.pole).addScaledVector(along, -v.pole.dot(along)).negate();
+    fold.normalize();
+    const yWorld = v.elbow.copy(along).negate();
+    basis.makeBasis(v.pole.crossVectors(yWorld, fold), yWorld, fold);
+    arm.g.parent.getWorldQuaternion(q.parent);
+    arm.g.quaternion.setFromRotationMatrix(basis).premultiply(q.parent.invert());
+    arm.el.rotation.set(-Math.acos(Math.max(-1, Math.min(1, along.dot(forearm)))), 0, 0);
+    arm.g.updateMatrixWorld(true);
+    const reached = arm.hand.getWorldPosition(v.a).sub(v.shoulder).normalize();
+    q.swing.setFromUnitVectors(reached, v.b.copy(v.target).sub(v.shoulder).normalize());
+    arm.g.parent.getWorldQuaternion(q.parent);
+    arm.g.quaternion.premultiply(q.parent).premultiply(q.swing).premultiply(q.parent.invert());
+    arm.g.updateMatrixWorld(true);
+    arm.el.getWorldQuaternion(q.parent);
+    arm.hand.quaternion.copy(limitWrist(q.local.copy(q.parent.invert()).multiply(q.hand)));
+  };
+  const keepOutside = (pose, outside) => {
+    const place = v.a.set(...pose.position).sub(camera.position).applyQuaternion(camera.inverse);
+    camera.probe.set(place.x, place.y, 0).applyQuaternion(camera.quaternion).add(camera.position);
+    camera.forward.set(0, 0, -1).applyQuaternion(camera.quaternion);
+    const distance2 = outside.contact([camera.probe.x, camera.probe.y, camera.probe.z], [camera.forward.x, camera.forward.y, camera.forward.z], ARM_REACH.contactProbe);
+    if (distance2 === null) return pose;
+    camera.hand.set(...pose.quaternion).premultiply(camera.inverse);
+    const ahead = Math.max(ARM_REACH.contactPalm, -camera.fingers.set(1, 0, 0).applyQuaternion(camera.hand).z * ARM_REACH.contactFingers);
+    const limit = Math.max(outside.nearest ?? ARM_REACH.contactNearest, distance2 - ahead - (outside.margin ?? ARM_REACH.contactMargin));
+    if (-place.z <= limit) return pose;
+    place.z = -limit;
+    place.applyQuaternion(camera.quaternion).add(camera.position);
+    return { ...pose, position: [place.x, place.y, place.z] };
+  };
+  const save = () => {
+    saved.twist = upper.rotation.y;
+    for (const side of ["R", "L"]) {
+      const arm = arms[side];
+      const into = saved.arms[side];
+      into.position.copy(arm.g.position);
+      into.g.copy(arm.g.quaternion);
+      into.el.copy(arm.el.quaternion);
+      into.hand.copy(arm.hand.quaternion);
+    }
+  };
+  return {
+    apply(targets, view) {
+      if (!targets || !targets.R && !targets.L) return;
+      save();
+      applied = true;
+      upper.updateWorldMatrix(true, true);
+      let { R, L } = targets;
+      bendLimit = view ? view.reachBend ?? ARM_REACH.viewBend : null;
+      if (view?.keepOutside) {
+        view.camera.updateWorldMatrix(true, false);
+        view.camera.matrixWorld.decompose(camera.position, camera.quaternion, v.a);
+        camera.inverse.copy(camera.quaternion).invert();
+        if (R) R = keepOutside(R, view.keepOutside);
+        if (L) L = keepOutside(L, view.keepOutside);
+      }
+      if (L && R) turnChest(L);
+      if (R) reach("R", R);
+      if (L) reach("L", L);
+      bendLimit = null;
+    },
+    restore() {
+      if (!applied) return;
+      applied = false;
+      upper.rotation.y = saved.twist;
+      for (const side of ["R", "L"]) {
+        const arm = arms[side];
+        const from = saved.arms[side];
+        arm.g.position.copy(from.position);
+        arm.g.quaternion.copy(from.g);
+        arm.el.quaternion.copy(from.el);
+        arm.hand.quaternion.copy(from.hand);
+      }
+    }
+  };
+};
+
+// src/player/head-hiding.ts
+var isDrawable = (object) => {
+  const flagged = object;
+  return Boolean(flagged.isMesh || flagged.isSprite || flagged.isPoints);
+};
+var createHeadHider = (roots) => {
+  let isHiding = false;
+  let viewCamera = null;
+  const drawables = [];
+  for (const root of roots) root.traverse((object) => isDrawable(object) && drawables.push(object));
+  for (const drawable of drawables) {
+    const previousBefore = drawable.onBeforeRender;
+    const previousAfter = drawable.onAfterRender;
+    let saved = [];
+    drawable.onBeforeRender = (renderer, scene2, camera, geometry, material, group) => {
+      previousBefore.call(drawable, renderer, scene2, camera, geometry, material, group);
+      if (!isHiding || camera !== viewCamera) return;
+      const drawn = Array.isArray(drawable.material) ? drawable.material : [material];
+      saved = drawn.map((entry) => ({ material: entry, colorWrite: entry.colorWrite, depthWrite: entry.depthWrite }));
+      for (const entry of drawn) {
+        entry.colorWrite = false;
+        entry.depthWrite = false;
+      }
+    };
+    drawable.onAfterRender = (renderer, scene2, camera, geometry, material, group) => {
+      previousAfter.call(drawable, renderer, scene2, camera, geometry, material, group);
+      for (const flags of saved) {
+        flags.material.colorWrite = flags.colorWrite;
+        flags.material.depthWrite = flags.depthWrite;
+      }
+      saved = [];
+    };
+  }
+  return {
+    setView(mode, camera) {
+      isHiding = mode === "first" && camera !== null;
+      viewCamera = camera;
+    }
+  };
+};
+
 // src/player/avatar.ts
 var TWO_PI = Math.PI * 2;
 var MAX_GAIT = 1.4;
 var CLIP_BLEND = 0.12;
 var CLIP_CASCADE = 5;
 var FALL_SECONDS2 = 0.3;
+var BUILDER_EYE = [0, 1.815, 0.16];
+var EYE_OFFSET = [0, -0.068, 0];
+var EYE_BOB = 0.5;
 var HIP_HEIGHT = 0.95;
 var WALK_ARM = 0.28;
 var WALK_BOB = 0.035;
@@ -4250,7 +4522,11 @@ 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 SIT = { thigh: -1.5, lean: -0.08, arm: -0.45, armZ: 0.12, elbow: -0.75 };
+var LIE = { knee: 0.08, armZ: 0.12, elbow: -0.1 };
 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 };
+var DOOR_SHOULDER = 1.42;
+var DOOR_ARM = 0.62;
 var HAND_OFFSET = { x: 0, y: -0.33, z: 0.04 };
 var hexOf = (value) => typeof value === "string" ? Number.parseInt(value, 16) : value;
 var clamp = (value, min, max) => Math.min(max, Math.max(min, value));
@@ -4280,6 +4556,8 @@ var createPlayerAvatar = (THREE, options = {}) => {
   const fallSeconds = options.fallSeconds ?? FALL_SECONDS2;
   const smooth = options.cascade ?? true;
   const clipCascade = options.clipCascade ?? CLIP_CASCADE;
+  const eyeBob = options.eyeBob ?? EYE_BOB;
+  const eyeOffset = options.eyeOffset ?? EYE_OFFSET;
   const root = new THREE.Group();
   const tilt = new THREE.Group();
   tilt.add(body);
@@ -4331,6 +4609,7 @@ var createPlayerAvatar = (THREE, options = {}) => {
     const built = buildHand({ THREE, add: addMesh, hg, handM: handMaterial, s: side, detailed: true });
     hands.push({ side, hg, fingers: built.fingers, th: built.th });
   });
+  const armReach = createArmReach(THREE, rig, { R: hands.find((hand) => hand.side < 0).hg, L: hands.find((hand) => hand.side > 0).hg });
   const setHandGrip = (hand, grip, wristX = 0) => {
     hand.fingers.forEach((finger, j) => {
       finger.rotation.z = -hand.side * grip * (j % 2 ? 1.1 : 0.9);
@@ -4338,7 +4617,23 @@ var createPlayerAvatar = (THREE, options = {}) => {
     if (hand.th) hand.th.rotation.z = -hand.side * (0.32 + grip * 0.25);
     hand.hg.rotation.x = wristX;
   };
+  const eyeSocket = new THREE.Object3D();
+  eyeSocket.name = "eye";
+  eyeSocket.position.set(BUILDER_EYE[0] + eyeOffset[0], BUILDER_EYE[1] + eyeOffset[1], BUILDER_EYE[2] + eyeOffset[2]);
+  rig.headG.children[0].add(eyeSocket);
+  const headHider = createHeadHider([rig.headG, ...rig.neck ? [rig.neck] : []]);
+  const eyeLocal = new THREE.Vector3();
+  let bob = 0;
+  let hipWithoutBob = null;
   const legRestX = rig.legs.map((leg) => leg.g.position.x);
+  const legLengths = (() => {
+    const thigh = rig.legs[0].g;
+    const shin = rig.legs[0].kn;
+    root.updateMatrixWorld(true);
+    const hipY = thigh.getWorldPosition(new THREE.Vector3()).y;
+    const kneeY = shin.getWorldPosition(new THREE.Vector3()).y;
+    return { hipBelowTrunk: HIP_HEIGHT - hipY, thigh: hipY - kneeY, shin: kneeY - new THREE.Box3().setFromObject(shin).min.y };
+  })();
   const legSide = (index) => index === 0 ? 1 : -1;
   let cycles = 0;
   let time = 0;
@@ -4397,10 +4692,29 @@ var createPlayerAvatar = (THREE, options = {}) => {
       ...strain ? { legL: -0.5, legR: 0.4, kneeL: 0.55, kneeR: 0.08, drop: -0.05 } : {}
     };
   };
+  const doorPose = (door) => {
+    const { phase, progress } = door;
+    const on = phase === "reach" ? progress : phase === "release" ? 1 - progress : 1;
+    const swing = phase === "swing" ? progress : phase === "release" ? 1 : 0;
+    const shake = phase === "rattle" ? Math.sin(time * 55) * 0.06 * (1 - progress) : 0;
+    const drop = clamp((DOOR_SHOULDER - door.height) / DOOR_ARM, -0.9, 1);
+    const low = clamp((0.75 - door.height) / 0.5, 0, 1);
+    const raise = -Math.acos(clamp(drop, -1, 1)) * on - 0.35 * low * on;
+    const elbow = door.pull ? -0.35 - 0.75 * swing : -0.95 + 0.75 * swing;
+    return {
+      armR: raise + shake,
+      armRz: REST_ARM_Z * (1 - on) + 0.05 * on,
+      elbR: -0.12 + (elbow + 0.12) * on,
+      armLz: -REST_ARM_Z,
+      elbL: -0.12,
+      lean: ((door.pull ? -0.06 : 0.1) * swing + 0.35 * low) * on,
+      headX: 0.06 * on + 0.2 * low * on
+    };
+  };
   const holdingPose = (gait, itemUse) => {
-    const bob = Math.sin(cycles * TWO_PI) * 0.05 * gait;
+    const bob2 = Math.sin(cycles * TWO_PI) * 0.05 * gait;
     if (!itemUse) {
-      return { armL: -0.45 + bob, armLz: 0.22, elbL: -1.05 };
+      return { armL: -0.45 + bob2, armLz: 0.22, elbL: -1.05 };
     }
     const { id, position, rotation } = itemUse;
     if (id === "drink" || id === "sip" || id === "chug") {
@@ -4413,7 +4727,7 @@ var createPlayerAvatar = (THREE, options = {}) => {
         headX: -0.26 * tilt3
       };
     }
-    if (id === "open" || id === "close") {
+    if (id === "open" || id === "close" || itemUse.gripL !== void 0) {
       const reach = clamp((0.22 - position[0]) / 0.12, 0, 1);
       return {
         armL: -0.45 - 0.35 * reach,
@@ -4512,6 +4826,31 @@ var createPlayerAvatar = (THREE, options = {}) => {
       drop: Math.abs(Math.sin(ph)) * WALK_BOB * gait
     };
   };
+  const sitPose = (hip) => {
+    const knee = hip - legLengths.hipBelowTrunk - legLengths.thigh * Math.cos(SIT.thigh);
+    const shinFromVertical = Math.acos(clamp(knee / legLengths.shin, 0, 1));
+    const bend = -SIT.thigh - shinFromVertical;
+    return {
+      legL: SIT.thigh,
+      legR: SIT.thigh,
+      kneeL: bend,
+      kneeR: bend,
+      lean: SIT.lean,
+      drop: hip - HIP_HEIGHT,
+      armR: SIT.arm,
+      armL: SIT.arm,
+      armRz: SIT.armZ,
+      armLz: -SIT.armZ,
+      elbR: SIT.elbow,
+      elbL: SIT.elbow
+    };
+  };
+  const liePose = () => ({ legL: 0, legR: 0, kneeL: LIE.knee, kneeR: LIE.knee, lean: 0, drop: 0, armR: 0, armL: 0, armRz: LIE.armZ, armLz: -LIE.armZ, elbR: LIE.elbow, elbL: LIE.elbow });
+  const layBody = (hip) => {
+    tilt.rotation.set(-Math.PI / 2, 0, 0, "XYZ");
+    const pivot = new THREE.Vector3(0, HIP_HEIGHT, 0).applyEuler(tilt.rotation);
+    tilt.position.set(0, hip, 0).sub(pivot);
+  };
   const placeBody = (progress) => {
     const fk = progress * progress * (3 - 2 * progress);
     const flip = fract(cycles * 1.7) >= 0.5 ? 1 : 0;
@@ -4561,6 +4900,7 @@ var createPlayerAvatar = (THREE, options = {}) => {
       return run ? run.clip.id : null;
     },
     update(dt, state = {}) {
+      armReach.restore();
       const speed = state.speed ?? 0;
       const moving = speed >= 0.05;
       const down = !!state.down;
@@ -4571,13 +4911,27 @@ var createPlayerAvatar = (THREE, options = {}) => {
       profile.bob = (running ? RUN_BOB : WALK_BOB) * gait;
       time = cycles / (walkCadence(Math.max(speed, 0)) * (running ? 1.3 : 1));
       animator.animate(body, time, { speed });
+      bob = rig.fig.position.y - rig.dropBase;
       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));
+      const seat = down ? null : state.seat ?? null;
+      if (down) {
+        animator.setPose(rig, downPose());
+        bob = rig.fig.position.y - rig.dropBase;
+      } else if (seat) {
+        animator.setPose(rig, seat.pose === "lie" ? liePose() : sitPose(seat.hip));
+        bob = 0;
+      } else {
+        if (running) {
+          animator.setPose(rig, runningPose(gait, Boolean(state.armed || state.holding || state.itemUse)));
+          bob = rig.fig.position.y - rig.dropBase;
+        }
+        if (state.crouch) {
+          animator.setPose(rig, crouchPose(gait));
+          bob = rig.fig.position.y - rig.dropBase - CROUCH.drop;
+        }
         if (state.push) animator.setPose(rig, pushingPose(state.push));
+        else if (state.door) animator.setPose(rig, doorPose(state.door));
         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) {
@@ -4589,20 +4943,33 @@ var createPlayerAvatar = (THREE, options = {}) => {
           });
         }
       }
-      placeBody(fall);
-      stepClip(dt, down, Boolean(state.crouch));
-      if (smooth) animator.cascade(rig, run && !run.clip.loop ? dt * clipCascade : dt);
+      if (seat?.pose === "lie") layBody(seat.hip);
+      else placeBody(fall);
+      stepClip(dt, down, Boolean(state.crouch || seat));
+      const cascadeDt = run && !run.clip.loop ? dt * clipCascade : dt;
+      const targetWithoutBob = rig.fig.position.y - bob;
+      if (smooth) animator.cascade(rig, cascadeDt);
+      hipWithoutBob = smooth && hipWithoutBob !== null ? stepCascade2(hipWithoutBob, targetWithoutBob, cascadeDt, "hip") : targetWithoutBob;
+      bob = rig.fig.position.y - hipWithoutBob;
       const blow = run?.clip.events?.find((event) => (event.type === "impact" || event.type === "grip") && event.data?.kind)?.data?.kind;
       const ph = cycles * TWO_PI;
       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 = blow === "punch" ? 1.4 : blow === "shove" ? 0.15 : state.armed || holdRight || holdLeft ? 1.22 : running ? 0.85 : 0.12;
+        const holdLeft = !isRight && (state.itemUse?.id === "open" || state.itemUse?.id === "close" || state.itemUse?.gripL !== void 0);
+        const grip = !isRight && state.itemUse?.gripL !== void 0 ? 1.22 * state.itemUse.gripL : 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);
       });
+      root.updateMatrixWorld(true);
+      root.worldToLocal(eyeSocket.getWorldPosition(eyeLocal));
+      eyeLocal.y -= (1 - eyeBob) * bob;
+    },
+    eye(out = new THREE.Vector3()) {
+      root.updateWorldMatrix(true, false);
+      return root.localToWorld(out.copy(eyeLocal));
     },
+    setView: (mode, camera) => headHider.setView(mode, camera),
     play(clip, playOptions = {}) {
       const found = typeof clip === "string" ? clips.get(clip) : clip;
       if (!found) throw new Error(`Unknown pose clip: ${String(clip)}`);
@@ -4614,6 +4981,12 @@ var createPlayerAvatar = (THREE, options = {}) => {
       if (run) run.target = 0;
     },
     hand: (side) => sockets[side],
+    shoulder: (side) => armOf[side].g,
+    reach(targets, view) {
+      if (run || fall > 0) return;
+      root.updateMatrixWorld(true);
+      armReach.apply(targets, view);
+    },
     on(_type, listener) {
       listeners.add(listener);
       return () => void listeners.delete(listener);
@@ -4650,7 +5023,9 @@ var first_person_arms_default = {
     shoulder: [0.16, -0.36, 0.18],
     upper: 0.32,
     fore: 0.3,
-    reachShift: 0.35,
+    reachShift: 0.42,
+    reachBend: [1.35, 0.95],
+    elbowView: [[0.96, -0.26, -0.06], null],
     wrist: 0.07,
     elbowPole: [0.45, -1, 0.2],
     shoulderLeft: [-0.07, -0.46, 0.18],
@@ -4677,22 +5052,14 @@ var first_person_arms_default = {
 };
 
 // src/first-person/hand.ts
-var FINGERS = [
-  { z: -0.03, lengths: [0.034, 0.024, 0.02], width: 0.016 },
-  { z: -0.0105, lengths: [0.038, 0.027, 0.022], width: 0.0165 },
-  { z: 9e-3, lengths: [0.035, 0.025, 0.02], width: 0.0155 },
-  { z: 0.027, lengths: [0.029, 0.02, 0.018], width: 0.0135 }
-];
-var PALM = { length: 0.09, thick: 0.026, width: 0.09, wristWidth: 0.066 };
-var FINGER_THICK = 0.0135;
-var CURL = { near: 1.05, mid: 1.25, far: 0.85, spread: 0.06 };
-var THUMB = { base: [5e-3, -6e-3, -0.044], near: 0.034, far: 0.028, width: 0.019 };
+var PALM = { radius: 0.048, scale: [0.6, 1.05, 1], down: 0.035 };
+var CURL = { closed: 1.25, near: 0.9, far: 1.1 };
+var THUMB = { open: 0.32, closed: 0.25 };
 var createHandMesh = (THREE, skin, wristSkin = skin) => {
   const root = new THREE.Group();
   root.name = "first-person-hand";
   const geometries = [];
-  const box = (parent, sx, sy, sz, x, y, z, material = skin) => {
-    const geometry = new THREE.BoxGeometry(sx, sy, sz);
+  const add = (parent, geometry, material, x = 0, y = 0, z = 0) => {
     geometries.push(geometry);
     const mesh = new THREE.Mesh(geometry, material);
     mesh.position.set(x, y, z);
@@ -4700,64 +5067,26 @@ var createHandMesh = (THREE, skin, wristSkin = skin) => {
     parent.add(mesh);
     return mesh;
   };
-  const palmGeometry = new THREE.BoxGeometry(PALM.length, PALM.thick, PALM.width);
-  const palmPosition = palmGeometry.getAttribute("position");
-  for (let i = 0; i < palmPosition.count; i++) {
-    if (palmPosition.getX(i) < 0) palmPosition.setZ(i, palmPosition.getZ(i) * PALM.wristWidth / PALM.width);
-  }
-  palmGeometry.computeVertexNormals();
-  geometries.push(palmGeometry);
-  const palm = new THREE.Mesh(palmGeometry, skin);
-  palm.frustumCulled = false;
-  root.add(palm);
-  const wristGeometry = new THREE.CylinderGeometry(0.03, 0.033, 0.05, 8);
+  const group = new THREE.Group();
+  group.quaternion.setFromRotationMatrix(new THREE.Matrix4().makeBasis(new THREE.Vector3(0, -1, 0), new THREE.Vector3(-1, 0, 0), new THREE.Vector3(0, 0, -1)));
+  group.position.set(-PALM.down, 0, 0);
+  root.add(group);
+  add(group, new THREE.SphereGeometry(PALM.radius, 14, 10), skin, 0, -PALM.down, 0).scale.set(...PALM.scale);
+  const built = buildHand({ THREE, add, hg: group, handM: skin, s: -1, detailed: true });
+  const wristGeometry = new THREE.CylinderGeometry(0.03, 0.033, 0.05, 10);
   wristGeometry.rotateZ(Math.PI / 2);
-  geometries.push(wristGeometry);
-  const wrist = new THREE.Mesh(wristGeometry, wristSkin);
-  wrist.position.set(-PALM.length / 2 - 0.018, 0, 0);
-  wrist.frustumCulled = false;
-  root.add(wrist);
-  const joints = [];
-  FINGERS.forEach((finger, index) => {
-    const segments = [];
-    let parent = root;
-    let at = PALM.length / 2;
-    finger.lengths.forEach((length, k) => {
-      const group = new THREE.Group();
-      group.position.set(at, k === 0 ? 2e-3 : 0, k === 0 ? finger.z : 0);
-      const taper = 1 - k * 0.07;
-      box(group, length, FINGER_THICK * taper, finger.width * taper, length / 2, 0, 0);
-      parent.add(group);
-      segments.push(group);
-      parent = group;
-      at = length;
-    });
-    joints.push({ segments, weight: 1 + index * (CURL.spread / CURL.near) });
-  });
-  const thumbNear = new THREE.Group();
-  thumbNear.rotation.order = "YZX";
-  thumbNear.position.set(...THUMB.base);
-  box(thumbNear, THUMB.near, FINGER_THICK * 1.1, THUMB.width, THUMB.near / 2, 0, 0);
-  const thumbFar = new THREE.Group();
-  thumbFar.position.set(THUMB.near, 0, 0);
-  box(thumbFar, THUMB.far, FINGER_THICK, THUMB.width * 0.9, THUMB.far / 2, 0, 0);
-  thumbNear.add(thumbFar);
-  root.add(thumbNear);
+  add(root, wristGeometry, wristSkin, -PALM.down - 0.03, 0, 0);
   let lastGrip = 0;
   let indexCurl;
-  const curl = [CURL.near, CURL.mid, CURL.far];
-  const applyIndex = () => {
-    const finger = joints[0];
-    if (!finger) return;
-    const k = indexCurl === void 0 ? lastGrip : Math.min(1, Math.max(0, indexCurl));
-    finger.segments.forEach((segment, i) => segment.rotation.z = -curl[i] * k * finger.weight);
+  const curlFinger = (finger, k) => {
+    built.fingers[finger * 2].rotation.z = k * CURL.closed * CURL.near;
+    built.fingers[finger * 2 + 1].rotation.z = k * CURL.closed * CURL.far;
   };
+  const applyIndex = () => curlFinger(0, indexCurl === void 0 ? lastGrip : Math.min(1, Math.max(0, indexCurl)));
   const setGrip = (grip) => {
-    const k = Math.min(1, Math.max(0, grip));
-    lastGrip = k;
-    for (const joint of joints) joint.segments.forEach((segment, i) => segment.rotation.z = -curl[i] * k * joint.weight);
-    thumbNear.rotation.set(0, 0.55 - 1.45 * k, -0.1 - 0.75 * k);
-    thumbFar.rotation.z = -0.1 - 0.7 * k;
+    lastGrip = Math.min(1, Math.max(0, grip));
+    for (let finger = 1; finger < 4; finger++) curlFinger(finger, lastGrip);
+    if (built.th) built.th.rotation.z = THUMB.open + lastGrip * THUMB.closed;
     applyIndex();
   };
   const setIndex = (value) => {
@@ -4775,33 +5104,12 @@ var createHandMesh = (THREE, skin, wristSkin = skin) => {
   };
 };
 
-// src/first-person/ik.ts
-var solveTwoBone = (root, target, upper, lower, pole, out) => {
-  const line = out.line.copy(target).sub(root);
-  let distance2 = line.length();
-  if (distance2 < 1e-6) line.set(0, 0, -1);
-  else line.divideScalar(distance2);
-  const min = Math.abs(upper - lower) + 1e-4;
-  const max = upper + lower - 1e-4;
-  out.clamped = distance2 > max || distance2 < min;
-  distance2 = Math.min(max, Math.max(min, distance2));
-  const along = (distance2 * distance2 + upper * upper - lower * lower) / (2 * distance2);
-  const across = Math.sqrt(Math.max(0, upper * upper - along * along));
-  const side = out.side.copy(pole);
-  side.addScaledVector(line, -side.dot(line));
-  if (side.lengthSq() < 1e-8) side.set(0, 1, 0).addScaledVector(line, -line.y);
-  if (side.lengthSq() < 1e-8) side.set(1, 0, 0);
-  side.normalize();
-  out.joint.copy(root).addScaledVector(line, along).addScaledVector(side, across);
-  out.end.copy(root).addScaledVector(line, distance2);
-  return out;
-};
-var createTwoBone = (THREE) => ({ joint: new THREE.Vector3(), end: new THREE.Vector3(), clamped: false, line: new THREE.Vector3(), side: new THREE.Vector3() });
-
 // src/first-person/arms.ts
 var DEFAULT_BLEND = 0.18;
 var ELBOW_SEGMENTS = 8;
 var REACH_SLACK = 0.97;
+var ELBOW_VIEW_MARGIN = 0.86;
+var ELBOW_VIEW_PASSES = 4;
 var CONTACT_PROBE = 1.4;
 var CONTACT_MIN = 0.12;
 var CONTACT_MARGIN = 5e-3;
@@ -4950,6 +5258,11 @@ function createFirstPersonArms(THREE, options = {}) {
   const shoulderOf = (sign, out) => sign === -1 && rig.shoulderLeft ? out.set(...rig.shoulderLeft) : out.set(rig.shoulder[0] * sign, rig.shoulder[1], rig.shoulder[2]);
   const poleOf = (sign) => sign === -1 && rig.elbowPoleLeft ? new THREE.Vector3(...rig.elbowPoleLeft) : new THREE.Vector3(rig.elbowPole[0] * sign, rig.elbowPole[1], rig.elbowPole[2]);
   const kneePole = new THREE.Vector3(...rig.kneePole);
+  const reachOf = (sign) => {
+    const bend = rig.reachBend?.[sign === 1 ? 0 : 1];
+    if (bend === void 0) return (rig.upper + rig.fore) * REACH_SLACK;
+    return Math.sqrt(rig.upper * rig.upper + rig.fore * rig.fore + 2 * rig.upper * rig.fore * Math.cos(bend));
+  };
   const hip = new THREE.Vector3(...rig.hip);
   const euler = new THREE.Euler(0, 0, 0, "YZX");
   const quaternionOf = (r) => new THREE.Quaternion().setFromEuler(euler.set(r[0], r[1], r[2], "YZX"));
@@ -5039,15 +5352,45 @@ function createFirstPersonArms(THREE, options = {}) {
     out.scale = base.scale;
     return out;
   };
-  const drawArm = (arm, pose) => {
+  const elbowAt = new THREE.Vector3();
+  const viewOf = (camera) => {
+    const lens = camera;
+    if (!lens.isPerspectiveCamera) return null;
+    const tanV = Math.tan(lens.fov * Math.PI / 360);
+    return { tanV, tanH: tanV * lens.aspect };
+  };
+  const placeElbowInView = (sign, view) => {
+    const way = rig.elbowView?.[sign === 1 ? 0 : 1];
+    if (!way) return false;
+    elbowAt.set(way[0], way[1], way[2]).setLength(rig.fore).add(wristAt);
+    for (let pass = 0; pass < ELBOW_VIEW_PASSES; pass++) {
+      const depth = Math.max(0.05, -elbowAt.z);
+      const high = view.tanV * ELBOW_VIEW_MARGIN * depth;
+      const wide = view.tanH * ELBOW_VIEW_MARGIN * depth;
+      elbowAt.y = Math.max(elbowAt.y, -high);
+      elbowAt.x = Math.min(wide, Math.max(-wide, elbowAt.x));
+      elbowAt.sub(wristAt).setLength(rig.fore).add(wristAt);
+    }
+    shoulder.sub(elbowAt).setLength(rig.upper).add(elbowAt);
+    return true;
+  };
+  const drawArm = (arm, pose, view) => {
     copyPose(arm.drawn, pose);
     const scale = pose.scale;
     fingers.set(1, 0, 0).applyQuaternion(pose.q);
     wristAt.copy(pose.p).addScaledVector(fingers, -rig.wrist * scale);
     shoulderOf(arm.sign, shoulder).add(bobOffset);
-    const excess = shoulder.distanceTo(wristAt) - (rig.upper + rig.fore) * REACH_SLACK;
+    if (view && placeElbowInView(arm.sign, view)) {
+      solveTwoBone(shoulder, wristAt, rig.upper, rig.fore, towards.copy(elbowAt).sub(shoulder).add(elbowAt).sub(wristAt), bone);
+      finishArm(arm, pose, scale);
+      return;
+    }
+    const excess = shoulder.distanceTo(wristAt) - reachOf(arm.sign);
     if (excess > 0 && rig.reachShift > 0) shoulder.addScaledVector(towards.subVectors(wristAt, shoulder).normalize(), Math.min(excess, rig.reachShift));
     solveTwoBone(shoulder, wristAt, rig.upper, rig.fore, poleOf(arm.sign), bone);
+    finishArm(arm, pose, scale);
+  };
+  const finishArm = (arm, pose, scale) => {
     palmAt.copy(bone.end).addScaledVector(fingers, rig.wrist * scale);
     arm.drawn.p.copy(palmAt);
     arm.anchor.position.copy(palmAt);
@@ -5159,7 +5502,7 @@ function createFirstPersonArms(THREE, options = {}) {
           dropped.p.y -= AWAY_DROP * ease(arm.away);
           pose = dropped;
         }
-        drawArm(arm, pose);
+        drawArm(arm, pose, mode === "target" && targets?.elbows !== "body" ? viewOf(state.camera) : null);
         const shown = arm.away < AWAY_HIDDEN;
         for (const part of [arm.anchor, arm.upper, arm.fore, arm.cuff, arm.elbow]) part.visible = shown;
       }
@@ -5207,7 +5550,7 @@ var impactOf = (clip) => clip.events?.find((event) => event.type === "impact")?.
 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, {
+  const arms = options.firstPerson === false || options.firstPerson === void 0 ? 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,
@@ -5228,7 +5571,7 @@ var toRoomAvatar = (avatar, options = {}) => {
   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;
+    const free = state.speed < GUARD_SPEED && !state.down && !state.armed && !state.holding && !state.push && !state.door && !state.itemUse && !state.running;
     if (strikeLeft > 0) {
       strikeLeft -= dt;
       if (strikeLeft <= 0 && guardLeft > 0 && free) {
@@ -5247,7 +5590,8 @@ var toRoomAvatar = (avatar, options = {}) => {
     root: avatar.root,
     avatar,
     arms,
-    ...arms ? { firstPerson: { root: arms.root, update: (dt, state) => arms.update(dt, state) } } : {},
+    eye: (out) => avatar.eye(out),
+    setView: (mode, camera) => avatar.setView(mode, camera),
     update: (dt, state) => {
       stepGuard(dt, state);
       avatar.update(dt, {
@@ -5259,10 +5603,14 @@ var toRoomAvatar = (avatar, options = {}) => {
         pitch: -state.pitch,
         ...state.holding !== void 0 ? { holding: state.holding } : {},
         ...state.itemUse !== void 0 ? { itemUse: state.itemUse } : {},
-        ...state.push !== void 0 ? { push: state.push } : {}
+        ...state.push !== void 0 ? { push: state.push } : {},
+        ...state.seat !== void 0 ? { seat: state.seat } : {},
+        ...state.door !== void 0 ? { door: state.door } : {}
       });
     },
     hand: (side) => avatar.hand(side),
+    shoulder: (side) => avatar.shoulder(side),
+    reach: (targets, view) => avatar.reach(targets, view),
     strike: (clipId, strikeOptions) => {
       const clip = strikes.get(clipId);
       if (!clip) return null;