@adatechnology/game-characters-three 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -1103,6 +1103,11 @@ type PlayerAvatar = {
     readonly playing: string | null;
     /** A socket at the hand: 'R' is the weapon hand (the puppet's right, at -x), 'L' the other one. */
     hand(side: 'R' | 'L'): THREE_NS.Object3D;
+    /**
+     * Brings the hands to where the tool in them asks (`HandTargets`, world space) after `update`: shoulder, elbow and wrist each bend inside the human range, the chest turns and the shoulder
+     * blade slides toward a hand out of reach. Null, a strike playing or the body going down leave the arms as `update` posed them. Call it after the tool is placed and the root moved.
+     */
+    reach(targets: HandTargets | null): void;
     on(type: 'event', listener: (event: AvatarEvent) => void): () => void;
     dispose(): void;
 };
@@ -1275,6 +1280,8 @@ type RoomAvatarLike = {
             contact?(origin: [number, number, number], direction: [number, number, number], maxDistance: number): number | null;
         }): void;
     };
+    /** Brings the body's hands to the tool in them, in third person (`RoomAvatar.reach`). */
+    reach(targets: HandTargets | null): void;
     /** 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';

package/dist/index.global.js

@@ -8637,6 +8637,176 @@ var GameCharactersThree = (() => {
     shirtColor: "3d5a73"
   };
 
+  // src/first-person/ik.ts
+  var solveTwoBone = (root, target, upper, lower, pole, out) => {
+    const line = out.line.copy(target).sub(root);
+    let distance3 = line.length();
+    if (distance3 < 1e-6) line.set(0, 0, -1);
+    else line.divideScalar(distance3);
+    const min = Math.abs(upper - lower) + 1e-4;
+    const max = upper + lower - 1e-4;
+    out.clamped = distance3 > max || distance3 < min;
+    distance3 = Math.min(max, Math.max(min, distance3));
+    const along = (distance3 * distance3 + upper * upper - lower * lower) / (2 * distance3);
+    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, distance3);
+    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 distance3 = Math.min(most, Math.max(least, line.length()));
+      v.target.copy(v.shoulder).addScaledVector(line.normalize(), distance3);
+      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_PI2 = Math.PI * 2;
   var MAX_GAIT = 1.4;
@@ -8733,6 +8903,7 @@ var GameCharactersThree = (() => {
       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);
@@ -8963,6 +9134,7 @@ var GameCharactersThree = (() => {
         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;
@@ -9016,6 +9188,11 @@ var GameCharactersThree = (() => {
         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);
@@ -9571,29 +9748,6 @@ var GameCharactersThree = (() => {
     };
   };
 
-  // src/first-person/ik.ts
-  var solveTwoBone = (root, target, upper, lower, pole, out) => {
-    const line = out.line.copy(target).sub(root);
-    let distance3 = line.length();
-    if (distance3 < 1e-6) line.set(0, 0, -1);
-    else line.divideScalar(distance3);
-    const min = Math.abs(upper - lower) + 1e-4;
-    const max = upper + lower - 1e-4;
-    out.clamped = distance3 > max || distance3 < min;
-    distance3 = Math.min(max, Math.max(min, distance3));
-    const along = (distance3 * distance3 + upper * upper - lower * lower) / (2 * distance3);
-    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, distance3);
-    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;
@@ -10059,6 +10213,7 @@ var GameCharactersThree = (() => {
         });
       },
       hand: (side) => avatar.hand(side),
+      reach: (targets) => avatar.reach(targets),
       strike: (clipId, strikeOptions) => {
         const clip = strikes.get(clipId);
         if (!clip) return null;