@adatechnology/game-characters-three 0.5.0 → 0.6.0

package/dist/index.js

@@ -4235,6 +4235,176 @@ 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],
+  /** From the wrist joint to the middle of the palm, metres of the body. */
+  palm: 0.042
+};
+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 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 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) - (up + fore) * ARM_REACH.slack;
+    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, length) => {
+    const excess = arm.g.getWorldPosition(v.shoulder).distanceTo(v.wrist) - length * ARM_REACH.slack;
+    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, up + fore);
+    arm.g.getWorldPosition(v.shoulder);
+    upper.getWorldQuaternion(q.body);
+    v.pole.set(ARM_REACH.elbowPole[0] * arm.outward, ARM_REACH.elbowPole[1], ARM_REACH.elbowPole[2]).applyQuaternion(q.body);
+    const most = Math.sqrt(up * up + fore * fore + 2 * up * fore * Math.cos(ARM_REACH.elbowMin));
+    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 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) {
+      if (!targets || !targets.R && !targets.L) return;
+      save();
+      applied = true;
+      upper.updateWorldMatrix(true, true);
+      if (targets.L && targets.R) turnChest(targets.L);
+      if (targets.R) reach("R", targets.R);
+      if (targets.L) reach("L", targets.L);
+    },
+    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/avatar.ts
 var TWO_PI = Math.PI * 2;
 var MAX_GAIT = 1.4;
@@ -4331,6 +4501,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);
@@ -4561,6 +4732,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;
@@ -4614,6 +4786,11 @@ var createPlayerAvatar = (THREE, options = {}) => {
       if (run) run.target = 0;
     },
     hand: (side) => sockets[side],
+    reach(targets) {
+      if (run || fall > 0) return;
+      root.updateMatrixWorld(true);
+      armReach.apply(targets);
+    },
     on(_type, listener) {
       listeners.add(listener);
       return () => void listeners.delete(listener);
@@ -4775,29 +4952,6 @@ 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;
@@ -5263,6 +5417,7 @@ var toRoomAvatar = (avatar, options = {}) => {
       });
     },
     hand: (side) => avatar.hand(side),
+    reach: (targets) => avatar.reach(targets),
     strike: (clipId, strikeOptions) => {
       const clip = strikes.get(clipId);
       if (!clip) return null;