feat(render): contralateral arm swing during locomotion (L4.2)

Author: a-baran-orhan

packages/posecode-render/src/contacts.ts

@@ -176,3 +176,38 @@ export function relaxHands(
   }
   if (changed) m.root.updateMatrixWorld(true);
 }
+
+/** Fraction of the contralateral hip's sagittal angle carried into arm swing. */
+export const SWING_GAIN = 0.4;
+const SWING_EULER = new THREE.Euler();
+const HIP_EULER = new THREE.Euler();
+
+/**
+ * Contralateral arm swing: during locomotion the arms counter-swing to the legs
+ * (right leg forward ↔ left arm forward). Adds a swing to each free shoulder
+ * proportional to the OPPOSITE hip's sagittal (local X) angle, so any move that
+ * animates the hips (walk, march, box-step) gets natural arm swing for free.
+ * Skips shoulders the document authors and any gripping side.
+ */
+export function swingArms(
+  m: Mannequin,
+  authoredShoulders: ReadonlySet<string>,
+  gripSides: ReadonlySet<"left" | "right">,
+): void {
+  let changed = false;
+  for (const side of ["left", "right"] as const) {
+    if (gripSides.has(side)) continue;
+    const shoulderId = `shoulder_${side}`;
+    if (authoredShoulders.has(shoulderId)) continue;
+    const shoulder = m.bones.get(shoulderId);
+    const contraHip = m.bones.get(`hip_${side === "left" ? "right" : "left"}`);
+    if (!shoulder || !contraHip) continue;
+    HIP_EULER.setFromQuaternion(contraHip.quaternion, "XYZ");
+    if (Math.abs(HIP_EULER.x) < 1e-3) continue; // legs still → no swing
+    SWING_EULER.setFromQuaternion(shoulder.quaternion, "XYZ");
+    SWING_EULER.x += HIP_EULER.x * SWING_GAIN;
+    shoulder.quaternion.setFromEuler(SWING_EULER);
+    changed = true;
+  }
+  if (changed) m.root.updateMatrixWorld(true);
+}

packages/posecode-render/src/index.ts

@@ -27,7 +27,7 @@ import {
   type ClipSource,
 } from "./clips.js";
 import { depenetrate } from "./depenetrate.js";
-import { alignFloorPalms, levelPlantedFeet, wrapGrip, relaxHands } from "./contacts.js";
+import { alignFloorPalms, levelPlantedFeet, wrapGrip, relaxHands, swingArms } from "./contacts.js";
 
 const DEG = Math.PI / 180;
 
@@ -270,6 +270,8 @@ export function createViewer(
   // Finger bones the loaded document explicitly poses (make-a-fist, finger-spell,
   // hand-wave): the L4.1 resting-hand curl leaves these alone.
   let authoredFingers = new Set<string>();
+  // Shoulders the document poses: L4.2 arm-swing leaves these to the author.
+  let authoredShoulders = new Set<string>();
   // The last loaded document, kept so the viewer can re-solve base pose and
   // ground anchors when the character (with its own proportions) arrives.
   let lastIR: PosecodeIR | null = null;
@@ -596,6 +598,8 @@ export function createViewer(
       // lower-body poses (squat, lunge, deadlift) don't balance on the toes.
       // Runs before the floor clamp so the leveled sole is what rests on y=0.
       levelPlantedFeet(mannequin, info.groundLock);
+      // L4.2 aliveness: contralateral arm swing during locomotion (free arms only).
+      swingArms(mannequin, authoredShoulders, gripSidesOf(info.grips));
       // L4.1 aliveness: relax idle hands into a natural curl (grips still wrap).
       relaxHands(mannequin, gripSidesOf(info.grips), authoredFingers);
       // Safety net: nothing above ever intentionally pushes part of the body
@@ -697,6 +701,8 @@ export function createViewer(
       groundFigureOf(mannequin);
       levelPlantedFeet(mannequin, ir.phases[0]?.groundLock ?? []);
       authoredFingers = new Set(timeline.bonesUsed.filter(isFingerId));
+      authoredShoulders = new Set(timeline.bonesUsed.filter((id) => id.startsWith("shoulder_")));
+      swingArms(mannequin, authoredShoulders, gripSidesOf(ir.phases[0]?.grips ?? []));
       relaxHands(mannequin, gripSidesOf(ir.phases[0]?.grips ?? []), authoredFingers);
       captureGroundTargets();
       baseRootPos.copy(mannequin.root.position);

packages/posecode-render/test/contacts.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "vitest";
 import * as THREE from "three";
 import { buildMannequin } from "../src/mannequin.js";
-import { levelPlantedFeet, relaxHands } from "../src/contacts.js";
+import { levelPlantedFeet, relaxHands, swingArms } from "../src/contacts.js";
 import { groundFigure } from "../src/groundlock.js";
 
 const DEG = Math.PI / 180;
@@ -75,3 +75,33 @@ describe("relaxHands (L4.1)", () => {
     expect(m.bones.get("index_left")!.rotation.x).toBeCloseTo(1.4, 5);
   });
 });
+
+describe("swingArms (L4.2)", () => {
+  it("adds contralateral arm swing when a hip is flexed and the arm is free", () => {
+    const m = buildMannequin();
+    // Flex the right hip forward (walking: right leg forward → left arm forward).
+    m.bones.get("hip_right")!.rotation.x = -0.6;
+    const before = m.bones.get("shoulder_left")!.rotation.x;
+    swingArms(m, new Set(), new Set());
+    const after = m.bones.get("shoulder_left")!.rotation.x;
+    expect(Math.abs(after - before)).toBeGreaterThan(0.05); // swung
+    // swings the same sagittal direction as the contralateral hip (forward)
+    expect(Math.sign(after - before)).toBe(Math.sign(-0.6));
+  });
+
+  it("respects an authored shoulder (no swing)", () => {
+    const m = buildMannequin();
+    m.bones.get("hip_right")!.rotation.x = -0.6;
+    m.bones.get("shoulder_left")!.rotation.x = 0.9; // authored
+    swingArms(m, new Set(["shoulder_left"]), new Set());
+    expect(m.bones.get("shoulder_left")!.rotation.x).toBeCloseTo(0.9, 5);
+  });
+
+  it("skips a gripping side", () => {
+    const m = buildMannequin();
+    m.bones.get("hip_right")!.rotation.x = -0.6;
+    const before = m.bones.get("shoulder_left")!.rotation.x;
+    swingArms(m, new Set(), new Set(["left"]));
+    expect(m.bones.get("shoulder_left")!.rotation.x).toBeCloseTo(before, 5);
+  });
+});