# Phase 9 Round 3 — Bugfix: Overlay Head Bone, One Node Per Shape, Part Rotation/Scale in the Harness

## Overview

Three defects remain after Round 2 (user report, testing `break.stk` in the harness):

1. **"The head bone has another bone extending out of it"** — the harness bone overlay draws the
   Head leaf bone as a segment to `IK_Targets/Head` (0, −624), the `SkeletonModification2DLookAt`
   target — a long line sticking out of the head. It should draw the head bone along its own
   direction instead.
2. **Duplicate nodes per closed shape** — `_mount_shape()` mounts closed shapes as a `Polygon2D`
   fill **plus** a `Line2D` outline (e.g. `Body/Head/@Polygon2D@165` + `@Line2D@166`). Per the
   user, closed shapes should mount as **just the Polygon2D** and open shapes as **just one
   Line2D**.
3. **Part rotation & scale not applied** — the adapter ignores the per-part `rotation` (degrees)
   and `scale` the user applied in the Whole Stickman preview. A torso rotated 180° looks
   identical to an unrotated one; a head scaled ~2× in the editor (≈160×160 px) renders ~80×80
   in the harness.

---

## 1. Root-cause analysis

### 1a. Overlay head segment (`scripts/test_harness.gd`)

`_draw_bones()` treats every leaf bone identically: draw to its IK target. For the four limbs
the targets ARE the wrist/ankle joints (correct). For the Head the target is a LookAt aim point
232 px above the neck — drawn as a "bone" it looks broken. The Head bone is authored with
`length = 90`, `bone_angle = −90` (points up), so its true tip is
`origin + Vector2(0, -length).rotated(global_rotation)` — a 90 px segment inside the head.

**Fix:** special-case the Head leaf — draw along the bone's own direction; keep the limb leaf
bones drawing to their IK targets.

### 1b. Duplicate nodes (`scripts/stk_rig_adapter.gd` `_mount_shape`)

Closed shapes mount `Polygon2D` + closed `Line2D` outline (Round 1 mirrored the editor's
fill+outline rendering). The user wants one node per shape: closed → `Polygon2D` only; open →
`Line2D` only. `DEFAULT_LINE_WIDTH = 2.0` still applies to open lines.

### 1c. Part rotation/scale (`scripts/stk_rig_adapter.gd` mount pipeline)

The `.stk` part dict carries `rotation` (degrees, about the part bbox center) and `scale`
(about the bbox center) from the Whole Stickman preview
(`whole_stickman_preview.gd:500-506`: `world = C + R(rot)·S·(pt − C)`, `C =` bbox center). The
adapter currently mounts the raw drawn geometry, ignoring both. The user's requirement: the
shapes must appear in the harness exactly as rotated/scaled in the editor (the guide in the
editor IS the rig's rest pose).

**Full application is possible without detaching limbs** — the earlier "flip-only" concern was
based on computing the alignment on the *raw* geometry and then rotating on top, which
double-rotates. The correct composition (per user direction) is:

1. Apply the part transform **first**: `Q = E(P) = C + R(rot)·S·(P − C)` for every point
   (scale then rotate about the bbox center — the editor's exact transform).
2. Compute the anchor and alignment **on the transformed geometry**:
   - `J' = E(J_raw)` (the drawn joint end, transformed).
   - `F' = E(J_raw + F_raw) − J' = R(rot)·S·F_raw` (the transformed far vector).
3. Alignment `θ = F'.normalized().angle_to(Vector2.DOWN)` — rotates the fitted long axis onto
   the bone. Because the user aligned the shape to the guide (the bone direction), θ is the
   residual between their drawn orientation and the bone; the shape appears in the harness as
   in the editor, attached at the joint. 90° rotations (break.stk's lower limbs — sideways
   drawn bars turned vertical) work: `F'` points along the fitted limb, `θ` keeps it hanging,
   and the limb stays connected to the elbow/knee.
4. **180° flips** (rotations whose wrapped value is within ±45° of 180°): a flip about the
   center swaps the ends of the shape. In the editor the flipped shape shows its drawn far end
   at the joint region, so the harness attaches the **drawn far end** at the joint:
   - `flipped = |wrapf(rot_rad, -PI, PI)| > PI * 0.75`
   - if flipped: anchor `A = E(far_raw_end)`, far vector `V = −F'`; else `A = J'`, `V = F'`.
   The flipped part then hangs the other way along the bone with its content turned around —
   the rotation is visibly applied (e.g. the 180° torso shows its drawn neck end at the hip
   joint and the drawn hip end up at the neck — matching the editor's flipped torso).
5. Bone fit scale `s = bone_length / V.length()` measured on the transformed extent (so a
   user-scaled part is not double-fitted; `s ≈ 1` when the user already scaled to the bone
   length — verified numerically for every `break.stk` part). Guards: `|V| <= 0.0001 → s = 1,
   θ = 0`.
6. Mounted points: `v = R(θ)·(Q − A)`; `v.y *= s`.
7. **Head special case (unchanged semantics):** `θ = 0`, `s = 1` (the head mounts upright,
   chin at the origin, extending `−Y`; the head driver has no rotation). The flip anchor rule
   still applies (a 180° head attaches at its cap top — upside-down, chin up — matching the
   editor). Part scale applies through `E` (head face ≈160 px: drawn 80 × 1.986).

---

## 2. Fix specification

### 2a. `scripts/test_harness.gd` — head leaf segment

In `_draw_bones()`, for the leaf bone `Head` (no Bone2D child): draw
`origin → origin + Vector2(0, -length).rotated(global_rotation)` instead of the IK-target
segment. Limb leaf bones (LeftLowerArm, RightLowerArm, LeftLowerLeg, RightLowerLeg) keep the
IK-target segments. Implement via a per-bone check (`bone.name == "Head"`) or by removing
`Head` from `LEAF_BONE_IK_PATHS` and handling it in the no-target fallback (the fallback
already draws `origin + R(global_rotation)·(length, 0)` — change it to use the bone's
`bone_angle` direction: `Vector2(length, 0).rotated(deg_to_rad(bone.bone_angle)).rotated(global_rotation)`;
for the Head (`bone_angle = −90`) that yields `(0, −90)` rotated by the pose — the desired
segment; for other bones `bone_angle` is 0 → `(length, 0)` — same as today).

### 2b. `scripts/stk_rig_adapter.gd` — one node per shape

`_mount_shape()`: closed → `Polygon2D` only (polygon + color; **no** outline Line2D); open →
`Line2D` (width `DEFAULT_LINE_WIDTH`). Delete the outline branch.

### 2c. `scripts/stk_rig_adapter.gd` — part transform composition

Read per-part `rotation` (float, **degrees**, default 0.0) and `scale` (`{x, y}`, default
`(1, 1)`) from the part dict. Apply in the mount pipeline:

1. Raw bbox `C` (center), raw anchor `J_raw`, raw far point `F_pt_raw = J_raw + F_raw`
   (direction from the joint end to the far end, per the Round 2 family rules), as today.
2. `E(P) = C + R(rot_rad)·S_part·(P − C)` — the preview's part transform, applied to every
   point and to the anchor/far point: `J' = E(J_raw)`, `F_pt' = E(F_pt_raw)`,
   `F' = F_pt' − J'`.
3. `flipped = |wrapf(rot_rad, -PI, PI)| > PI * 0.75`.
4. Anchor `A` and far vector `V`: `A = F_pt'`, `V = −F'` if flipped, else `A = J'`,
   `V = F'`.
5. `θ = V.normalized().angle_to(Vector2.DOWN)` (0 if `|V| <= 0.0001`).
6. `s = bone_length / |V|` (head → 1.0; guards `|V| <= 0.0001 → 1.0`).
7. Mounted points: `v = R(θ)·(Q − A)`; `v.y *= s`. Head: `θ = 0`, `s = 1` (upright mount,
   flip anchor rule still applies).

**Example (torso, rot 180°, scale (0.857, 3.99)):** `E` flips the drawn torso; `J'` = the
transformed hip end (now the fitted top), `F_pt'` = the transformed neck end (fitted bottom);
flipped → `A` = the neck end; `V` points up → `θ = π`; `s ≈ 391.5/395`; the torso extends up
from the hip joint with the drawn **neck end attached at the hip** and the drawn hip end up at
the neck — the 180° rotation visibly applied (unrotated: hip end at the hip, neck at the
neck).

**Example (lower arm, rot 90°):** not flipped; `J'` = the elbow (fitted bottom); `F'` points
up (the editor's bent forearm) → `θ = π`; the forearm hangs along the bone from the elbow with
its content turned 90° — exactly as assembled in the editor.

**Scale check:** part scale composes into `E` and the fit `s` is measured on the transformed
extent → no double-fitting. Head: `s = 1` but `E` applies `1.986` → the face mounts at ≈160 px
(drawn 80 × 1.986).

### 2d. Keep (unchanged)

`_reset_node_transform`, head `set_script(null)`, head-driver zeroing, `_fit_bones`,
`_recalibrate_ik`, `_bone_length_for`, `_compute_part_bbox`, width 2.0, all node-path
constants, null guards.

---

## 3. Files modified

| File | Changes |
|---|---|
| `scripts/stk_rig_adapter.gd` | `_mount_shapes()` reads part `rotation`/`scale`; mount pipeline composes `E_full` + fitted anchor/θ/fit-scale + flip heuristic; `_mount_shape()` mounts one node per shape (closed → Polygon2D only). |
| `scripts/test_harness.gd` | `_draw_bones()` leaf fallback uses the bone's `bone_angle` direction (Head draws a 90 px segment inside the head; limbs unchanged). |
| `docs/phase9_round3_bugfix_spec.md` | This file. |

## 4. Open question — RESOLVED (user directive)

1. **Rotation semantics.** User directive: *the shapes must appear in the harness exactly as
   rotated/scaled in the editor — that is the point of the guide.* ✅ **Full application**: the
   part transform `E` is applied to the geometry first, and the mount (anchor + alignment +
   fit) is computed on the transformed geometry, so every rotation is rendered. Rotations
   align the drawn long axis onto the bone (a 90° rotation turns a sideways-drawn bar into the
   limb as assembled — the limb stays attached to its joint; this does **not** detach limbs
   because the anchor is the transformed joint end, not a raw-geometry point). 180° flips
   additionally swap the attachment to the drawn far end (the end the user rotated into the
   joint position), making flips visible.

## 5. Edge cases

- Rotation absent (old files) → 0.0; scale absent → (1, 1) — Round 2 behavior unchanged.
- Negative part scale (mirroring) → `E_full` mirrors the points; `θ` adapts; fine.
- `F'` ≈ 0 (degenerate) → `s = 1`, `θ = 0`, no flip effect.
- Flip + IK: the flip is baked into the mounted points, so IK flexing still follows the bones.
- Multi-shape parts: bbox/transform over all shapes (unchanged).
- `-360`-style rotations normalize via `wrapf` ✓.

## 6. Test plan

1. Parse check: `..\Godot_v4.7.1-stable_win64_console.exe . --headless --check-only --quit`.
2. Headless smoke test (spawn `break.stk`, stack enabled, 2 frames):
   - Every `Body/*` node's children: closed shapes → exactly one Polygon2D and zero Line2D
     for that shape (count Polygon2D == number of closed shapes; Line2D count == number of
     open shapes; no node has both for the same shape).
   - Head: mounted face width ≈ 159–160 px (bbox width 108 × 1.986 ≈ 215 incl. cap; the face
     circle x-span ≈ 160), chin still at local origin.
   - Legs/arms still hang along bones: `Body/LeftUpperLeg` far end ≈ (0, +~200) local after
     `θ`+fit; thickness ≈ 24 (drawn 28 × part-scale 0.853).
   - Flip: temporarily modify the stk dict — set `torso.rotation = 180.0` — re-apply to a
     fresh rig, assert the drawn torso **neck end** now lands ≈ (0, 0) (hip joint) and the
     drawn **hip end** ≈ (0, −391.5) (neck) — the ends swapped vs. rotation 0 (hip end at the
     hip). Restore rotation 0 → hip end back at (0, 0).
   - Overlay: `test_harness.gd` head-leaf drawing path exists (code review; the overlay draws
     cannot be asserted headlessly — verified by review + manual F6).
   - Regression: driver rotations enabled; IK-following still works (move Left_Hand target,
     assert Body/LeftUpperArm rotation tracks bone + π/2).
3. Manual harness check (F6): no bone sticking out of the head; single nodes in the Remote
   Inspector; torso flip visible after rotating 180° in the editor and saving.

## 7. Design decisions

| # | Decision | Justification |
|---|---|---|
| D1 | Head leaf overlay segment along the bone's own direction (`bone_angle`-aware fallback) | The LookAt target is an aim point, not a joint; the bone itself is neck→head-top. |
| D2 | One node per shape (closed → Polygon2D only) | User request; removes node duplication in the Body tree. |
| D3 | Apply part scale fully (via `E`) + measure bone-fit scale on the transformed extent | Reproduces the editor scale (head 160 px) without double-fitting bone-scaled parts. |
| D4 | Apply part rotation fully: `E` first, then anchor/alignment/fit on the transformed geometry; 180° flips swap the attachment to the drawn far end | User directive (editor fidelity); the transformed joint anchor keeps 90°-rotated limbs attached to their bones. |
| D5 | Flip shown via the anchor swap (no separate content rotation) | Matches the editor: the flipped shape's far end sits at the joint region; content turns around on the bone. |

## 8. Implementation order

1. `stk_rig_adapter.gd` — part `rotation`/`scale` read + `E_full`/`J'`/`F'`/`θ`/fit/flip in
   `_mount_shapes()` + `_compute_mount_transform()` restructure.
2. `stk_rig_adapter.gd` — `_mount_shape()` single-node-per-shape.
3. `test_harness.gd` — head-leaf overlay segment.
4. Headless smoke test + parse check.
5. Docs (`BUGS.md` Round 3 note, `AGENTS.md`, `README.md`).