stickman/docs/phase9_round6_bugfix_spec.md

Phase 9 Round 6 — Bugfix: Joint-End Anchor Selection via the Guide Placement

Overview

User report: the lower left leg and lower right arm are mounted 180° off their bones (the far end attaches at the joint). Root cause (verified against break.stk data): the adapter picks the joint end with fixed per-side family rules (left limbs → drawn max_x end, right limbs → drawn min_x end, plus a 180° flip heuristic), but the user's drawn-side conventions are inconsistent across parts — e.g. the left lower leg's knee is at the drawn min_x end while the rule assumes max_x. The only reliable signal for which drawn end is the joint is the user's placement, which Round 5 now stores as guide_offset.

1. Verified diagnosis (break.stk, real data)

joint_in_part_space = C − guide_offset (C = raw bbox center; both ends E-transformed):

Part	rule anchor	dist to joint	other end	dist to joint	correct end
left_lower_leg (rot 90)	E(max_x) = ankle	≈199	E(min_x) = knee	≈11	min_x ✗ (bug)
right_lower_arm (rot 90)	E(min_x) = wrist	≈204	E(max_x) = elbow	≈2	max_x ✗ (bug)
left_lower_arm (rot 90)	E(max_x) = elbow	≈4	E(min_x) = wrist	≈204	max_x ✓
right_lower_leg (rot 90)	E(min_x) = knee	≈6	E(max_x) = ankle	≈199	min_x ✓
right_upper_arm (rot −180)	flip → E(max_x) = shoulder	≈7	E(min_x) = hand	≈178	max_x ✓ (flip heuristic)
torso (rot 180)	flip → E(neck end)	≈5	E(hip end)	≈400	neck ✓ (flip heuristic)
head	E(chin)	≈43	E(cap top)	≈191	chin ✓

Rule: when guide_offset is present, choose as the joint anchor whichever transformed end (E(J_raw) or E(F_pt_raw)) is nearest to C − guide_offset (the part's guide joint in part space). This fixes both buggy parts, preserves every correct case, and naturally reproduces the 180° flip behavior (a flipped part's far end lands near the joint).

2. Fix specification — scripts/stk_rig_adapter.gd

In _compute_mount_transform() (the anchor/flip section, ~lines 397–407):

1. When has_guide_offset is true:
   • joint_pos := center - guide_offset (the guide joint in the part's E-space; the editor stored guide_offset = (pos + C) − joint_preview, so C − guide_offset = joint_preview − pos — the joint position in the adapter's local frame, up to the preview translation which is distance-preserving).
   • d_joint := j_prime.distance_to(joint_pos); d_far := f_pt_prime.distance_to(joint_pos).
   • If d_far < d_joint (strict): anchor = f_pt_prime, v = -f_prime (the far end attaches — replaces the flip heuristic for this case). Else: anchor = j_prime, v = f_prime.
2. When has_guide_offset is false (old files): keep the current family rules + 180° flip heuristic exactly as today.
3. theta, s, the Round 5 offset t = (guide_offset + (anchor − center)).rotated(−c_node), the head fallback (HEAD_CHIN_DROP), and everything downstream are unchanged — they already consume anchor/v generically.

Note: this answers the user's hypothesis directly — the pivot point was indeed on the wrong drawn side; instead of guessing per-side conventions (or baking rotation/scale, which does not record which end is the joint), the stored guide placement decides the pivot side.

3. Files modified

File	Changes
scripts/stk_rig_adapter.gd	Nearest-end anchor selection when guide_offset is present (replaces the family-side + flip choice for that case).
docs/phase9_round6_bugfix_spec.md	This file.

4. Edge cases

• Old files without guide_offset → family rules + flip heuristic (current behavior).
• Tie (strict <) → keeps the family-rule end.
• Flipped parts with guide_offset → the far end is naturally nearest (the flip behavior is preserved without the heuristic).
• Misplaced parts (placement error > half the part length) → the wrong end may win; degenerate input, acceptable.
• Head → the chin is nearest the Neck (≈43 vs ≈191); the Round 5 offset and the HEAD_CHIN_DROP fallback are unchanged.

5. Test plan

1. Parse check: ..\Godot_v4.7.1-stable_win64_console.exe . --headless --check-only --quit.
2. Headless smoke test (spawn the current break.stk):
   • Body/LeftLowerLeg: the mounted knee end ≈ local (0, 0) (was the ankle end) and the far end ≈ (0, +200) — shin hangs from the knee.
   • Body/RightLowerArm: the mounted elbow end ≈ local (0, 0), far end ≈ (0, +200).
   • Regressions: Body/LeftLowerArm elbow ≈ (0,0); Body/RightLowerLeg knee ≈ (0,0); Body/RightUpperArm shoulder ≈ (0,0) (flip case via nearest rule); torso flipped neck end ≈ (0,0); head chin ≈ (0, +28) (guide-offset present → no chin-drop, chin ≈ 28 from the neck per the stored offset); all parts' far ends along +Y local (bone-aligned).
   • No-guide-offset fallback (synthetic dict without the key): lower limbs use the family rules + flip heuristic (regression: flipped torso anchor = far end; 90° limbs anchored at the family side).
   • IK regression: moving a hand target still rotates the body nodes with the bones.
3. Cleanup temp test files.

6. Design decisions

#	Decision	Justification
D1	Joint end = the fitted end nearest the stored guide joint (C − guide_offset)	The drawn-side conventions are inconsistent per part; the placement is the ground truth.
D2	Nearest rule only when guide_offset is present	Old files keep exact current behavior.
D3	Keep θ/s/t and the head fallback unchanged	They consume anchor/v generically; the placement math is already correct.
D4	No baking of rotation/scale into the .stk	Baking alone cannot record which drawn end is the joint; the stored placement already encodes it.

7. Implementation order

1. stk_rig_adapter.gd — nearest-end anchor selection (guarded by has_guide_offset).
2. Headless smoke test + parse check.
3. Docs (BUGS.md Round 6 note, AGENTS.md, README.md).