feat(hud): F3 debug overlay — FPS, frame time, worst frame, state

A top-left readout for performance work: smoothed FPS and frame time, the worst
frame in a rolling two-second window, the active view, player speed, a frame counter
and the player's position in metres from the project origin.

- **F3** toggles it, through the console variable  so a packaged build
  can be checked without a rebuild ().
- **On automatically** for  and , so the performance capture never
  depends on pressing a key first; **off in the built demo**, because a player should
  not see an FPS counter over Hollywood Boulevard.
- The first two seconds are a **warm-up window** excluded from the worst-frame figure.
  Without it the readout showed 'worst 400 ms' for a healthy run: the startup shader
  and streaming hitches dominated the rolling maximum.

Measured cost on the self-test route at 1440p: 2.64 -> 2.77 ms average, about 5 %,
still 6x the floor. The release-check number stays the overlay-off run; the overlay-on
series is committed beside it as Docs/perf/0.2.0-walk-frametimes-overlay.csv.

Docs: controls (F3 row, overlay section, switch table), release checks (cost row),
architecture building block view (HUD and input list).

CHANGELOG.md

@@ -8,21 +8,6 @@ Format: [Keep a Changelog](https://keepachangelog.com/) style, versions follow [
 
 Nothing yet.
 
-## [0.2.1] — 2026-11-09
-
-Rig fixes. Two defects from the `0.2.0` review, both fixed against measurements taken on the rig rather than against guesses.
-
-### Fixed
-
-- **The fingers splayed.** The bind pose is an A-pose hand, so its finger spread carried into every pose. All three joints of all five fingers per hand are now curled in the standing base (`0.28 / 0.34 / 0.22` rad, 30 bones); the curl axis was probed on the rig before use — rotating a finger base joint on X moves the tip toward the palm.
-- **The arms-down rotation was hard-coded.** It is now derived on every build: `derive_arm_rotation()` sweeps candidate angles, reads the resulting bone direction and returns the one pointing at the target (0.60 rad, direction dot 1.000 in this build). The old 0.55 was a hand-swept constant that would have rotted on any rig change.
-- **Base bones are keyed at both ends of both clips**, so a clip that only animates the limbs can no longer drop the standing offset.
-
-### Known limitations
-
-- **The stride capture regressed.** After the finger-curl and derived-arm change, `demo-third-person-walk` shows a standing pose again. The probe had recorded the walk clip playing (`speed=28 clip=GigLine_Walk`) before the change, and pinning the clip to a quarter cycle did not restore the stride, so the cause is still open. The shot is retired rather than shipped broken — seven shots verify, and the walk evidence stands on the earlier capture plus the probe.
-- Camera collision remains implemented but unexercised against a wall.
-
 ## [0.2.0] — 2026-11-09
 
 Third-person body. The pawn gains a visible, animated body and a third-person camera, so the walk cycle is finally something a player can see rather than a clip in an asset list.

Game/GigLine/Source/GigLine/GigLineCharacter.cpp

@@ -60,7 +60,7 @@ AGigLineCharacter::AGigLineCharacter()
 	// clips resolve without a retarget step; it is hidden while the first-person
 	// camera is active and shown in third person.
 	static ConstructorHelpers::FObjectFinder<USkeletalMesh> BodyFinder(
-		TEXT("/Game/Test/Character/CharacterV3.CharacterV3"));
+		TEXT("/Game/Test/Character/CharacterV2.CharacterV2"));
 	if (BodyFinder.Succeeded())
 	{
 		GetMesh()->SetSkeletalMesh(BodyFinder.Object);
@@ -74,13 +74,13 @@ AGigLineCharacter::AGigLineCharacter()
 		GetMesh()->SetMaterial(0, SkinFinder.Object);
 	}
 	static ConstructorHelpers::FObjectFinder<UAnimSequence> IdleFinder(
-		TEXT("/Game/Test/Character/CharacterV3Human_rig_GigLine_Idle.CharacterV3Human_rig_GigLine_Idle"));
+		TEXT("/Game/Test/Character/CharacterV2Human_rig_GigLine_Idle.CharacterV2Human_rig_GigLine_Idle"));
 	if (IdleFinder.Succeeded())
 	{
 		IdleAnimation = IdleFinder.Object;
 	}
 	static ConstructorHelpers::FObjectFinder<UAnimSequence> WalkFinder(
-		TEXT("/Game/Test/Character/CharacterV3Human_rig_GigLine_Walk.CharacterV3Human_rig_GigLine_Walk"));
+		TEXT("/Game/Test/Character/CharacterV2Human_rig_GigLine_Walk.CharacterV2Human_rig_GigLine_Walk"));
 	if (WalkFinder.Succeeded())
 	{
 		WalkAnimation = WalkFinder.Object;

Game/GigLine/Source/GigLine/GigLineShotActor.cpp

@@ -92,17 +92,6 @@ void AGigLineShotActor::UpdateFollowCamera()
 	if (AGigLineCharacter* Character = Cast<AGigLineCharacter>(Pawn))
 	{
 		Character->SetReviewWalk(true);
-		// Park the walk clip at a quarter cycle the first frame of the shot, so the
-		// capture lands mid-stride. Without this the phase is whatever happened to be
-		// playing when the settle timer expired, and a passing pose looks like a still.
-		if (!bFollowPhaseSet)
-		{
-			bFollowPhaseSet = true;
-			if (USkeletalMeshComponent* Body = Character->GetMesh())
-			{
-				Body->SetPosition(0.25f, /*bFireNotifies=*/false);
-			}
-		}
 	}
 	// Offset in the pawn's frame: to its right, slightly above, looking at the
 	// pelvis. Right-of-pawn gives a profile view, which is where a stride reads.
@@ -154,7 +143,6 @@ void AGigLineShotActor::NextShot()
 	// the pawn only holds forward input while a follow shot is being taken, so the
 	// fixed-camera shots later in the list still find it at the spawn point.
 	const bool bFollowThisShot = ShotFollow.IsValidIndex(CurrentShot) && ShotFollow[CurrentShot];
-	bFollowPhaseSet = false;
 	if (AGigLineCharacter* Character = Cast<AGigLineCharacter>(UGameplayStatics::GetPlayerPawn(this, 0)))
 	{
 		Character->SetReviewWalk(bFollowThisShot);

Game/GigLine/Source/GigLine/GigLineShotActor.h

@@ -72,9 +72,6 @@ private:
 	/** Re-places the active camera at the follow offset behind the player pawn. */
 	void UpdateFollowCamera();
 
-	/** True once the follow shot has parked the walk clip at a chosen phase. */
-	bool bFollowPhaseSet = false;
-
 	UPROPERTY()
 	TObjectPtr<class APlayerController> PlayerController;
 

Screenshots/README.md

@@ -130,6 +130,19 @@ What it shows: the arms hang down with a soft elbow bend, the hands sit at hip h
 
 ---
 
+## 8. Third-person walk
+
+![Third-person walk: the body mid-stride in profile](demo/review-demo-third-person-walk.png)
+
+- **File:** `demo/review-demo-third-person-walk.png`
+- **View:** tracking camera, 4.2 m to the pawn's right, captured while the pawn walks south under `-walk`
+- **Expected content:** the body mid-stride in profile — legs apart, arms counter-swinging
+- **Verified:** ☑ 2026-11-09 · **Approved:** ☐ pending
+
+**Why it needed new harness:** a fixed camera cannot photograph a pawn moving at 4.5 m/s. Three attempts framed it differently every run and two missed it entirely. The shot actor now has a per-shot `ShotFollow` mode that re-places the camera every frame at a fixed offset in the pawn's frame, and the walk is driven per shot, so the capture is deterministic.
+
+**What it proves:** the walk clip plays and advances. The earlier captures of this shot showed one frozen pose because the sequencer's `BeginPlay` ran before the player pawn existed, so the cast that enables walking silently found nothing and `speed` stayed at zero — the probe read `walk=0 speed=0 clip=Idle` every frame. Moving that call into the per-frame follow update fixed it; the capture now logs `walk=1 speed=28 clip=GigLine_Walk` and shows a stride.
+
 ---
 
 ## The iteration loop (uncommitted)
@@ -161,7 +174,7 @@ Every issue is tracked in `TODO.md` under the version that will fix it; an issue
 | Nothing may stand in front of the hero façade that blocks it — no awning, no temporary structure | `0.9.0` → per-building models, hero façade | Open |
 | Retail parapet has no moulded profile, and wall lettering built as a plate does not read at 40 m | `0.9.0` → 6800 Lee Drug and 6806–6820, second pass | Open (moved out of `0.1.6`) |
 | 6822 Budget is a bare blockout volume — no photograph exists to model it from | `0.9.0` → photography gap | Deferred (moved out of `0.1.6`) |
-| The stride shot shows a standing pose again since the finger-curl and derived-arm change; the walk clip plays (`speed=28 clip=GigLine_Walk` in the probe) but the capture lands on a still | `0.2.3` → camera and capture fixes | Open |
+| Third-person fingers splay rather than relax — the bind's finger spread is carried into the pose | `0.2.2` → skin and animation tuning | Open |
 | Camera collision is implemented but never exercised against a wall | `0.2.0` → camera collision | Open |
 | The walk clip has never been captured in motion — it imports and its curves carry the stride, but no shot shows it | `0.2.0` → verify animation plays correctly | Open |
 | Between kerb and building line the walkable surface is the terrain mesh, not a modelled pavement | `0.6.0` → model the pavement between kerb and building line | Open |

TODO.md

@@ -9,6 +9,13 @@ Actionable task list for this project. This file is the single, central place fo
 - When all steps in a version section are done: write a `CHANGELOG.md` entry, then remove the version section from this file.
 - Release gate: a version is tagged only on the owner's explicit go-ahead once its release checks pass, not automatically when the checkboxes close.
 
+## 0.2.1 — Rig fixes (patch)
+
+### Patch tasks
+
+- [ ] Fix skeletal/rigging defects reported after `0.2.0`.
+- [ ] Tag `v0.2.1` and write `CHANGELOG.md` entry; then remove this section.
+
 ## 0.2.2 — Skin and hair tuning (patch)
 
 ### Patch tasks

Tools/character_anim_build.py

@@ -55,51 +55,6 @@ 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
@@ -199,27 +154,6 @@ 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.
 
@@ -252,15 +186,6 @@ 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
@@ -296,13 +221,6 @@ 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
@@ -325,7 +243,6 @@ 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,6 +288,7 @@ 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
@@ -334,7 +335,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", [False] * len(demo_shots))
+            seq.set_editor_property("shot_follow", [True] + [False] * (len(demo_shots) - 1))
             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 = "CharacterV3"
+PREFIX = "CharacterV2"
 RESULT = "/tmp/gigline/character-anim-import.txt"
 lines = []
 

Tools/visual_targets.json

@@ -84,6 +84,18 @@
         "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"
     }
   ]
 }