# Phase 9 Round 2 — Bugfix: Bone Visibility, IK Shape Following, Torso/Head Mount in the Harness

## Overview

Testing `break.stk` in the test harness revealed four defects. This round fixes all four with
changes confined to `scripts/stk_rig_adapter.gd` (mount pipeline) and `scripts/test_harness.gd`
(debug bone overlay). Root causes were established with a headless probe of the live rig
(spawned via `StickmanFactory` with the modification stack enabled, 2 frames).

### Root causes (verified)

| # | Symptom | Root cause (probe-verified) |
|---|---|---|
| 1 | Lower-limb bones/joints invisible in "Show Bones" | `test_harness.gd` `_draw_bones()` draws parent-**origin** → bone-origin lines. For lower bones the parent origin is the *hip/shoulder* (upper bone origin), so the lower segment duplicates the upper segment; wrist/ankle joints are never drawn (they are bone *ends*, not origins). |
| 2 | IK only moves lower-arm shapes; upper-arm shapes static | Round 1's `_neutralize_driver_rotations()` sets `update_rotation = false` on the 10 `RemoteTransform2D` drivers. Probe: every `Body/*` node shows `rot_deg = 0.00` while its bone rotates. Upper-limb visuals sit at fixed joints (shoulder/hip origins don't move) → static; lower-limb visuals *translate* with the elbow/knee but never rotate → appear "attached to the upper bones". |
| 3 | Torso top connects at the hip joint | With driver rotation neutralized, the torso (anchor top-center, driver rotation π suppressed) hangs with its top at the hip-driven `Body/Body` origin. The user's torso is drawn hip-at-bottom (`break.stk` torso rect y∈[209,308], hip end at 308) and must mount with the **hip end at the origin**, extending up. |
| 4 | Head features wrong scale / too thick / nose not triangular | `DEFAULT_LINE_WIDTH = 16.0` vs the editor's 2 px outline (`body_part_panel.gd:435`). Small eye/nose/mouth shapes get 16 px outlines that dominate their geometry. Additionally the `Head` `RemoteTransform2D` has a local position offset `(0.05, −72)` designed for the old 100-px-radius circle, so the mounted head floats 72 px above the neck joint. |

---

## 1. The rig's visual convention (verified numerically)

The `RemoteTransform2D` drivers push **global** position + rotation onto the `Body/*` nodes.
With rotation pushes enabled, each `Body/*` node's world rotation = `bone_pose_rotation +
RT_local_rotation`. The authored RT local rotations are:

| Part | RT local rotation | Bone pose → visual direction at rest/IK (probe-verified) |
|---|---|---|
| `Body/Body` (torso) | `π` (3.1415927) | hanging geometry `(0,+Y)` → world `−Y` (up) ✓ |
| `Body/LeftUpperArm` | `+π/2` | hanging → world `−X` (left arm outward) ✓ |
| `Body/RightUpperArm` | `−π/2` | hanging → world `+X` (right arm outward) ✓ |
| `Body/LeftLowerArm` | `π` | hanging → world `−Y` (forearm direction) ✓ |
| `Body/RightLowerArm` | `−π/2` | hanging → world `−Y` (forearm direction) ✓ |
| `Body/LeftUpperLeg` / `RightUpperLeg` | `0` | hanging → world toward the knee ✓ |
| `Body/LeftLowerLeg` / `RightLowerLeg` | `−π/2` | hanging → world toward the ankle ✓ |
| `Body/Head` | `0` | upright (no rotation needed) ✓ |

**Consequence:** mounted geometry must be authored in the rig's "hanging" convention —
the joint end at the local origin, the far end along local `+Y` — and the drivers rotate it
correctly **in any pose**, so IK flexing follows the bones exactly. (This replaces the Round 1
"clean unrotated frame + rotation neutralization" approach, which is what broke IK following.)

## 2. Fix 1 — `StkRigAdapter` mount pipeline (rotation compensation by hanging convention)

### 2a. Remove driver neutralization

Delete `_neutralize_driver_rotations()` and its call in `apply()`. The drivers keep their
defaults (`update_position/rotation/scale = true`).

### 2b. Mount transform (per part)

For each part compute the bbox over all shape points. Let `cx = (min_x + max_x) / 2`,
`cy = (min_y + max_y) / 2`, `width = max_x − min_x`, `height = max_y − min_y`,
`long_axis_is_x = width >= height`, `extent = max(width, height)`.

**Anchor `J`, scale `S` (drawn space), and alignment rotation `θ`:**

| Part family | Anchor J | Scale S | θ (maps far end to local +Y) |
|---|---|---|---|
| Head | `(cx, max_y)` (bottom-center = chin) | `(1, 1)` | `0` (upright, extends `−Y`) |
| Torso | `(cx, max_y)` (bottom-center = hip end) | `(1, s)` | `π` (drawn extends up → rotated to hang down; driver π flips it back up) |
| Left limbs (arms + legs), long axis X | `(max_x, cy)` (joint at right end) | `(s, 1)` | `−π/2` (far end `−X` → `+Y`) |
| Right limbs, long axis X | `(min_x, cy)` (joint at left end) | `(s, 1)` | `+π/2` (far end `+X` → `+Y`) |
| Legs drawn vertically (long axis Y) | `(cx, min_y)` (hip at top) | `(1, s)` | `0` (already hanging) |
| Arms drawn vertically (long axis Y) | `(cx, min_y)` (shoulder at top) | `(1, s)` | `0` (already hanging) |

where `s = bone_length / extent` with `bone_length` from `_bone_length_for()` (unchanged),
guarded: `extent <= 0.0001 → s = 1.0`. Head: no scale, no rotation.

**Point transform** (replaces `_transform_points` math):

```
q = (P − J) ⋅ S            # scale along the drawn long axis only (cross axis 1:1)
pt_local = q.rotated(θ)   # rotate into the hanging frame
```

Notes:

- This preserves the Round 1 anisotropic-scaling requirement in effect: **only the long axis is
  scaled** (arms/legs = the drawn segment axis), cross-axis thickness stays 1:1. For
  horizontally-drawn arms it is mathematically identical to Round 1's `x·(bone/part_length)`.
- `break.stk`'s legs are drawn **horizontally** (long axis X, extent ≈101), so under Round 1's
  literal "legs scale Y" they mounted as 101-px-thick bars. The long-axis rule fixes this:
  legs become ~200 long × 28 thick — matching the drawn/assembled proportions 1:1.
- The torso pre-rotation π + the driver's π cancel at rest, so the mounted torso appears with
  the hip end at the hip joint and the top at `−torso_length` (the neck) — exactly where the
  user assembled it (their preview scale 3.99 ≈ 391.5/99 = 3.955).

### 2c. Head joint placement

The `Head` driver (`Skeleton2D/Torso/Head/RemoteTransform2D`) has local position
`(0.0503, −72.0)` — authored to center the old 100-px circle 72 px above the neck. In
`_fit_bones()` (head section), **zero the driver's local position** so `Body/Head` sits on the
neck joint. The mounted head (chin at local origin) then lands with the chin on the neck and
rotates about the neck with the head bone's LookAt.

### 2d. Line width

`DEFAULT_LINE_WIDTH := 2.0` (was 16.0) — matches the editor's outline width
(`body_part_panel.gd:435` `width: float = 2.0`), so eyes/nose/mouth/cap render 1:1.

### 2e. Keep

`_reset_node_transform()` (scale `(1,1)`, rotation `0` before mounting — drivers overwrite each
frame anyway), head `set_script(null)`, `_fit_bones` bone fitting, `_recalibrate_ik`,
`_bone_length_for`, node-path constants, bbox recompute (file `pivot`/`length` still ignored).

## 3. Fix 2 — `test_harness.gd` bone overlay

Rewrite `_draw_bones()`:

1. For each bone (all 10): draw a joint dot at `bone.global_position`.
2. For each **Bone2D child** of the bone: draw a line `origin → child.global_position`
   (true bone segment; works for nested lower bones).
3. For **leaf bones** (no Bone2D child): draw a line from the origin to the bone's
   corresponding IK target (map: `LeftLowerArm → IK_Targets/Left_Hand`,
   `RightLowerArm → IK_Targets/Right_Hand`, `LeftLowerLeg → IK_Targets/Left_Leg`,
   `RightLowerLeg → IK_Targets/Right_Leg`, `Head → IK_Targets/Head`) — shows the forearm/shin
   segments and the wrist/ankle joints; falls back to
   `origin + R(global_rotation) · (length, 0)` when the target node is missing.
4. Keep the existing colors/widths (`_bone_color`).

Result: 9 distinct segments (spine, neck-head, both arms ×2, both legs ×2) + 10 bone-origin
dots + target joints — lower limbs clearly visible.

## 4. Files modified

| File | Changes |
|---|---|
| `scripts/stk_rig_adapter.gd` | Remove `_neutralize_driver_rotations()` + call; new anchor/scale/rotation table in `_mount_shapes()` + `_compute_anchor`/`_compute_scale`/rotation helpers; `DEFAULT_LINE_WIDTH = 2.0`; zero the Head driver's local position in `_fit_bones()`; update doc comments. |
| `scripts/test_harness.gd` | Rewrite `_draw_bones()` (child-direction segments + leaf→IK-target segments + dots). |
| `docs/phase9_round2_bugfix_spec.md` | This file. |

## 5. Edge cases

- Empty part → skip (unchanged). `extent <= 0` → `s = 1`.
- Vertically-drawn legs/arms → θ = 0 (hanging already); horizontally-drawn → ±π/2.
- Torso drawn with hip at top (not bottom) would mount flipped — accepted assumption
  (mirrors Round 1's shoulder-inward assumption); `break.stk` has hip at bottom.
- Multi-shape parts: bbox over all shapes (unchanged).
- Old files without `pivot`/`length`: unaffected (bbox recomputed).
- Missing driver/target nodes: null-guarded warnings (unchanged pattern).

## 6. Test plan

1. Parse check: `..\Godot_v4.7.1-stable_win64_console.exe . --headless --check-only --quit`.
2. Headless smoke test (SceneTree, spawn `break.stk` via `StickmanFactory`, enable the
   modification stack, wait 2 frames), asserting:
   - No `update_rotation == false` on any of the 10 drivers.
   - `Body/*` world rotations ≈ their bone's world rotation + RT local rotation (e.g.
     `Body/LeftUpperArm.global_rotation ≈ LeftUpperArm.global_rotation + π/2`).
   - Mounted geometry hangs: `Body/LeftUpperLeg` shape points start at the node origin and
     extend toward `+Y` local, with Y extent ≈ 200 (bone length) and X extent ≈ 28 (thickness).
   - `Body/Body` (torso) shape Y extent ≈ 391.5, X extent ≈ 35.
   - `Body/Head` shape chin point ≈ local origin; the Head driver position == (0,0);
     mounted Line2D width == 2.0.
   - Bones overlay data: 10 bones; each lower bone's parent is the upper bone (sanity).
   - Then SET a pose override or drag an IK target (move `IK_Targets/Left_Hand`),
     await a frame, and assert `Body/LeftUpperArm.global_rotation` **changed** with the bone
     (upper arm follows) and `Body/LeftLowerArm.global_position` moved with the elbow.
3. Harness manual check (F6): lower limb bones + wrist/ankle joints visible; drag hand IK →
   upper arm shape rotates at the shoulder and lower arm shape flexes at the elbow.
4. Cleanup: delete the temporary test script.

## 7. Design decisions

| # | Decision | Justification |
|---|---|---|
| D1 | Restore driver rotation pushes; drop `_neutralize_driver_rotations()` | Probe-verified root cause of the IK-following bug; the hanging convention + driver rotations track bones in every pose. |
| D2 | Mount geometry in the rig's hanging frame (joint at origin, far end `+Y`) with a per-part alignment rotation | Makes the mount pose-agnostic; no per-part hardcoded compensation table needed. |
| D3 | Scale only the drawn long axis (auto-detected); cross axis 1:1 | Fixes `break.stk`'s horizontally-drawn legs (101-px bars → 200×28) and keeps Round 1's anisotropic-scaling intent. |
| D4 | Torso: anchor bottom-center + θ = π | Hip end at the hip joint; top lands at the neck, matching the user's assembled torso (preview scale ≈ 391.5/99). |
| D5 | Head: zero the Head driver's local position | Chin lands on the neck joint; head rotates about the neck with LookAt. |
| D6 | `DEFAULT_LINE_WIDTH = 2.0` | Matches the editor's 2 px outline — features render 1:1. |
| D7 | Harness overlay: parent→child segments + leaf→IK-target segments | Shows true lower-limb bones and wrist/ankle joints. |

## 8. Open questions — RESOLVED (user-approved)

1. **Legs drawn horizontally (break.stk).** ✅ **Auto-detect the long axis** (rotate to hang,
   scale the long axis) — replaces Round 1's fixed "legs = Y axis".
2. **Figure pose = rig rest/IK pose.** ✅ **Rig pose, shapes 1:1** — part transforms remain
   v1-ignored; the drawn shapes are fitted 1:1 onto the rig's bones.

## 9. Implementation order

1. `stk_rig_adapter.gd` — remove driver neutralization; new anchor/scale/θ helpers.
2. `stk_rig_adapter.gd` — rewrite `_mount_shapes()`/`_mount_shape()`/`_transform_points()`;
   `DEFAULT_LINE_WIDTH = 2.0`; zero Head driver position.
3. `test_harness.gd` — rewrite `_draw_bones()`.
4. Headless smoke test + parse check.
5. Docs (`BUGS.md` Round 2 note, `AGENTS.md`, `README.md`).