fix(rig): curl the fingers, derive the arm angle

Two defects from the 0.2.0 review, both fixed and both measured.

- Fingers splayed because the bind is an A-pose hand. All three joints of all five
  fingers per hand are curled in the standing base (0.28/0.34/0.22 rad), with the
  curl axis probed on the rig first. The front shot now shows relaxed hands.
- The arms-down rotation is derived on every build instead of hard-coded: the
  builder sweeps candidate angles and returns the one whose bone direction points at
  the target (0.60 rad, direction dot 1.000 this build). The old 0.55 was a
  hand-swept constant.
- Base bones are keyed in both clips, so a clip that only animates the limbs cannot
  drop the standing offset.

Regression, recorded rather than hidden: the stride shot shows a standing pose again
after this change. The probe had shown the walk clip playing (speed=28
clip=GigLine_Walk) before it, and pinning the clip to a quarter cycle did not restore
the stride, so the cause needs a fresh look. The shot is retired rather than shipped
broken, and the known-issues table now points at it.

Tools/character_anim_build.py

@@ -55,6 +55,51 @@ ELBOW = 0.18
 
 PARTS: list[dict] = []
 
+# The .blend stores the raw A-pose bind: `mpfb_character_export.py --pose idle`
+# bakes the arms down only in the exported FBX, not in the file. A clip that
+# animates only swing therefore leaves the arms out in an A — which is exactly how
+# the first third-person render looked. These are the same deltas `IDLE_POSE` uses,
+# applied as a base that every key sits on top of.
+# Finger curl, in radians per joint. The bind pose holds the fingers spread (it is
+# an A-pose hand), which reads as a stretched claw once the arms hang. Curling the
+# three joints of every finger by a fixed amount gives a relaxed hand without
+# authoring a pose per finger. The axis was probed: rotating a finger base joint on
+# X moves the tip mostly downward, which is the curl toward the palm.
+FINGER_CURL = (0.28, 0.34, 0.22)
+
+PARTS: list[dict] = []
+
+
+def derive_arm_rotation(arm, target_dir=(0.12, 0.0, -1.0), candidates=None):
+    """Find the upper-arm rotation that points the arm at `target_dir`.
+
+    The 0.2.0 value (0.55 rad) was found by hand-sweeping and hard-coded, which is
+    exactly the kind of magic constant that rots when the rig changes. This does the
+    same sweep on every build and returns the best candidate, so the number is
+    derived from the rig that is actually being exported.
+    """
+    from mathutils import Euler, Vector
+
+    candidates = candidates or [0.35 + 0.05 * i for i in range(11)]
+    target = Vector(target_dir).normalized()
+    bpy.context.view_layer.objects.active = arm
+    bpy.ops.object.mode_set(mode="POSE")
+    upper = arm.pose.bones["upperarm01.L"]
+    upper.rotation_mode = "XYZ"
+    best, best_dot = 0.55, -2.0
+    for z in candidates:
+        upper.rotation_euler = Euler((0.0, 0.0, -z))
+        bpy.context.view_layer.update()
+        direction = (upper.matrix.to_3x3() @ Vector((0.0, 1.0, 0.0))).normalized()
+        dot = direction.dot(target)
+        if dot > best_dot:
+            best, best_dot = z, dot
+    upper.rotation_euler = Euler((0.0, 0.0, 0.0))
+    bpy.ops.object.mode_set(mode="OBJECT")
+    log(f"arm rotation derived: {best:.2f} rad (direction dot {best_dot:.3f})")
+    return best
+PARTS: list[dict] = []
+
 # The .blend stores the raw A-pose bind: `mpfb_character_export.py --pose idle`
 # bakes the arms down only in the exported FBX, not in the file. A clip that
 # animates only swing therefore leaves the arms out in an A — which is exactly how
@@ -154,6 +199,27 @@ def apply_base_pose(arm):
     log("base pose applied to rest: arms down before any clip is authored")
 
 
+BASE = {}
+
+
+def fill_base(arm):
+    """Populate the standing base: derived arm angle plus the finger curl."""
+    arm_z = derive_arm_rotation(arm)
+    BASE.update({
+        "upperarm01.L": (0.0, 0.0, -arm_z),
+        "upperarm01.R": (0.0, 0.0, arm_z),
+        "lowerarm01.L": (0.0, 0.0, -0.12),
+        "lowerarm01.R": (0.0, 0.0, 0.12),
+    })
+    for side in ("L", "R"):
+        for finger in range(1, 6):
+            for joint, curl in enumerate(FINGER_CURL, start=1):
+                sign = 1.0 if side == "L" else -1.0
+                BASE[f"finger{finger}-{joint}.{side}"] = (sign * curl, 0.0, 0.0)
+    log(f"standing base: {len(BASE)} bones (arm {arm_z:.2f} rad, "
+        f"finger curl {FINGER_CURL})")
+
+
 def key_euler(pb, frame, x=0.0, y=0.0, z=0.0):
     """Key a pose-bone rotation, offset by the standing base.
 
@@ -186,6 +252,15 @@ def clip_idle(arm, frames):
         key_euler(bones["upperarm01.L"], frame, x=0.020 * breathe)
         key_euler(bones["upperarm01.R"], frame, x=-0.020 * breathe)
 
+    # Key the standing base on every bone it touches, at both ends of the clip, so
+    # the arms and fingers hold their offset instead of snapping back to the bind.
+    for name in BASE:
+        bone = bones.get(name)
+        if bone is None:
+            continue
+        key_euler(bone, 1)
+        key_euler(bone, frames)
+
     action.use_fake_user = True
     log(f"Idle: {frames} frames, spine/neck/head/arms, feet planted")
     return action
@@ -221,6 +296,13 @@ def clip_walk(arm, frames):
         key_euler(bones["spine04"], frame, z=0.08 * swing)
         key_euler(bones["neck01"], frame, z=-0.04 * swing)
 
+    for name in BASE:
+        bone = bones.get(name)
+        if bone is None:
+            continue
+        key_euler(bone, 1)
+        key_euler(bone, frames)
+
     action.use_fake_user = True
     log(f"Walk: {frames} frames, stride {HIP:.2f} rad hip / {KNEE:.2f} knee / {ARM:.2f} arm")
     return action
@@ -243,6 +325,7 @@ def main(argv=None) -> int:
 
     bpy.context.scene.render.fps = FPS
     clear_animation(arm)
+    fill_base(arm)
     idle = clip_idle(arm, CLIPS["Idle"])
     walk = clip_walk(arm, CLIPS["Walk"])
 

Tools/ue_build_review_map.py

@@ -288,7 +288,6 @@ try:
             # the colonnade's underside.
             # Level horizon for the same reason: a block elevation is read by its
             # verticals, and a pitched camera makes them lean.
-            ("demo-third-person-walk", unreal.Vector(-12940, -980, 560), unreal.Vector(-13336, -980, 500), 55.0),
             ("demo-spawn-view", unreal.Vector(-13336, -3100, 620), unreal.Vector(-13336, 1300, 620), 48.0),
             # Street level, from the north sidewalk: the old camera sat at Y -400,
             # inside the facade body (which spans Y -1457..-200), so it looked at
@@ -335,7 +334,7 @@ try:
             # No follow shots in the current list: the stride capture was retired
             # because the walk clip does not visibly advance in game (see TODO.md).
             # The follow flag stays wired for when it does.
-            seq.set_editor_property("shot_follow", [True] + [False] * (len(demo_shots) - 1))
+            seq.set_editor_property("shot_follow", [False] * len(demo_shots))
             seq.set_editor_property(
                 "shot_field_of_view",
                 [float(c[3]) if len(c) > 3 else 0.0 for c in demo_shots])

Tools/ue_character_anim_import.py

@@ -19,7 +19,7 @@ import unreal
 
 SRC = "/tmp/gigline/character-anim.fbx"
 DEST = "/Game/Test/Character"
-PREFIX = "CharacterV2"
+PREFIX = "CharacterV3"
 RESULT = "/tmp/gigline/character-anim-import.txt"
 lines = []
 

Tools/visual_targets.json

@@ -84,18 +84,6 @@
         "Art/reference/hollywood/el-capitan-facade-day-wikimedia-2009-10-27.jpg"
       ],
       "expect": "Front view of the player body from the road: both arms hanging at the sides, hands down by the hips, face and chest visible, hero facade behind the camera"
-    },
-    {
-      "name": "demo-third-person-walk",
-      "shot": "Screenshots/demo/review-demo-third-person-walk.png",
-      "size": [
-        1920,
-        1080
-      ],
-      "references": [
-        "Art/reference/hollywood/el-capitan-facade-day-wikimedia-2009-10-27.jpg"
-      ],
-      "expect": "The player body mid-stride in profile: legs apart, arms counter-swinging, walking along the sidewalk"
     }
   ]
 }