stickman/docs/phase9_task3_coords_spec.md

Phase 9 Task 3 — Feature: Coordinates Display

Overview

RIGGING.md Task 3: the test harness needs a show/hide readout on the right side of the screen displaying the current skeleton pose so bone/IK work can be inspected numerically:

1. Skeleton2D position and rotation.
2. Bone positions and rotations — Torso, Head, Left/RightUpperArm, Left/RightLowerArm, Left/RightUpperLeg, Left/RightLowerLeg.
3. IK target positions — Head, Torso, Right_Hand, Left_Hand, Right_Leg, Left_Leg.

The display is easy to read on the right side of the screen and is toggled by a checkbox like the existing "Show Bones" / "Show IK Handles" toggles. It is a non-persistent debug aid: the toggle defaults ON per launch, and the panel is rebuilt from scratch each run.

1. Mechanism

The readout is a PanelContainer + RichTextLabel pair built entirely in code (_build_coords_panel()), not authored in test_harness.tscn, and added as a child of the harness root after the viewport container so it renders in front of the SubViewport. It anchors to the top-right of the window below the top UI bar (offset_top = 40.0) with a fixed width and auto-height, and the panel is MOUSE_FILTER_IGNORE so it never intercepts viewport pan/zoom/drag input — the label itself stays interactive: text is selectable and copyable (mouse drag + Ctrl+C, plus the built-in right-click copy menu).

Values are read live each frame in _process(delta), so the panel always mirrors the current pose. All values are world-space (global_position / global_rotation). Rotation is reported in degrees (rad_to_deg); positions are Vector2 formatted to 1 decimal place.

2. Implementation — scripts/test_harness.gd

2a. Constants

• const COORDS_PANEL_WIDTH: float = 320.0 — fixed panel width (also the offset_left extent).
• const COORD_BONE_PATHS: Array[String] — 10 Skeleton2D-relative bone paths, in display order; the display name is the last path segment (path.get_file()): Torso, Torso/Head, Torso/LeftUpperArm, Torso/LeftUpperArm/LeftLowerArm, Torso/RightUpperArm, Torso/RightUpperArm/RightLowerArm, Torso/LeftUpperLeg, Torso/LeftUpperLeg/LeftLowerLeg, Torso/RightUpperLeg, Torso/RightUpperLeg/RightLowerLeg.

2b. State

• var _coords_panel: PanelContainer = null — the readout container.
• var _coords_label: RichTextLabel = null — the monospace, selectable text readout.
• var _coord_bones: Dictionary = {} — bone display name → Bone2D, resolved per spawn.
• var _show_coords: bool = true — toggle state (default ON, harness-level, persists across spawns but not to disk).

2c. UI construction — _build_coords_panel()

Called from _build_ui() right after the viewport container. Builds:

• _coords_panel (PanelContainer):
  • PRESET_TOP_RIGHT anchors; offset_top = 40.0, offset_right = -8.0, offset_left = -COORDS_PANEL_WIDTH.
  • grow_vertical = GROW_DIRECTION_END + grow_horizontal = GROW_DIRECTION_BEGIN (auto-height/width from label content; grows leftward so text never runs off the right edge of the screen).
  • mouse_filter = MOUSE_FILTER_IGNORE on the panel (input passes through to the viewport; the label itself keeps mouse handling for text selection).
  • StyleBoxFlat override "panel": bg Color(0,0,0,0.55), border Color(1,1,1,0.12) width 1, corner radius 4, content margin 8.
• _coords_label (RichTextLabel): selection_enabled = true, context_menu_enabled = true, fit_content = true, autowrap_mode = OFF, scroll_active = false, focus_mode = FOCUS_CLICK; monospace via a SystemFont override on the normal_font theme item (Consolas, Menlo, DejaVu Sans Mono, Courier New fallbacks) at normal_font_size = 18.
• _coords_panel added to the harness root (add_child(_coords_panel)).

2d. Toggle — _on_show_coords_toggled(pressed)

CheckBox "Show Coords" (top bar HBox, after "Show IK Handles", before the status label), button_pressed = true at build. Handler sets _show_coords = pressed and flips _coords_panel.visible. No persistence to disk.

2e. Update loop — _process(_delta) → _update_coords_display()

_process(delta) early-outs when _show_coords is false or _coords_label is null; otherwise calls _update_coords_display() each frame. _update_coords_display():

• If _rig is null/invalid → label text "No rig loaded", return.
• "Skeleton2D" section: position + rotation (degrees) via _skeleton.global_position / _skeleton.global_rotation (guarded).
• "Bones" section: iterates COORD_BONE_PATHS, looking each bone up in _coord_bones by display name; position + rotation (degrees). Missing/invalid bones skipped.
• "IK Targets" section: iterates IK_HANDLE_PATHS and reads each handle from _ik_handles (the same 6 handle set used by the drag handles); position only. Missing/invalid handles skipped.
• Lines joined with \n into _coords_label.text; the text is only reassigned when the built string differs from the current one, so an active text selection survives idle frames (it refreshes while bones are actively moving). Formatting helpers: _fmt_vec2(v) (%8.1f, %8.1f), _fmt_deg(rad) %7.1f° (1 decimal place).

2f. Resolution & lifecycle

• _resolve_rig_nodes() additionally calls _resolve_coord_bones().
• _resolve_coord_bones() clears _coord_bones, then for each COORD_BONE_PATHS entry resolves via _skeleton.get_node_or_null(NodePath(path)) as Bone2D; valid bones are keyed by path.get_file(), missing ones emit push_warning.
• _free_current_rig() clears _coord_bones. The _show_coords toggle itself persists across respawns (it lives at harness level, not per-rig).

3. Files modified

File	Changes
scripts/test_harness.gd	COORDS_PANEL_WIDTH, COORD_BONE_PATHS, _coords_panel, _coords_label, _coord_bones, _show_coords, _build_coords_panel(), _on_show_coords_toggled(), _process(), _update_coords_display(), _resolve_coord_bones(), _fmt_vec2(), _fmt_deg(); "Show Coords" checkbox.
docs/phase9_task3_coords_spec.md	This file.
AGENTS.md	Test-harness section: "Phase 9 Task 3 coordinates display" bullet; test_harness.tscn scene description now lists the "Show Coords" toggle.
RIGGING.md	Mark Task 3 implemented.

4. Edge cases

• No rig loaded: _update_coords_display() shows "No rig loaded".
• Missing bone nodes (foreign/partial rig): _resolve_coord_bones() warns once, and the per-frame loop skips missing/invalid bones via is_instance_valid.
• Toggle off: _process() early-outs; panel hidden.
• Re-spawn: _coord_bones re-resolved per spawn; _free_current_rig() clears it. The _show_coords toggle stays at its user-set value across spawns (harness-level state).
• Input blocking: MOUSE_FILTER_IGNORE keeps the panel from intercepting viewport pan/zoom/ drag.
• World-space values: global_position/global_rotation reflect the live pose regardless of Camera2D pan/zoom, so the readout tracks the actual rig transforms.

5. Design decisions

#	Decision	Justification
D1	Panel is code-built (_build_coords_panel()), not a scene node	Mirrors the code-built harness top bar; keeps test_harness.tscn unchanged and the panel trivial to rebuild.
D2	MOUSE_FILTER_IGNORE on the panel	The readout must never block viewport interaction (pan/zoom/IK dragging).
D3	World-space values + degrees	Matches what the debug overlay and drag handles use; degrees are the convention in the harness and the editor.
D4	IK targets report position only	IK targets carry no meaningful rotation for this readout (they are aim/IK markers).
D5	Toggle non-persistent, default ON	Debug aid only; no settings.json involvement, consistent with the other harness toggles.

6. Test plan

1. Parse check: ..\Godot_v4.7.1-stable_win64_console.exe . --headless --check-only --quit (user-requested; no errors).
2. Manual F6 check:
   • Launch harness; readout visible on the top-right with "No rig loaded".
   • Load stickmen/basic.stk; Skeleton2D, 10 Bones, and 6 IK Target rows populate with numeric values.
   • Drag an IK handle → position/rotation values update live each frame.
   • Uncheck "Show Coords" → panel hides; recheck → reappears with current values.
   • Confirm the panel does not block middle-mouse pan / wheel zoom / IK drags beneath it.