stickman/docs/phase9_task2_zorder_spec.md

Phase 9 Task 2 — Feature: Body-Part Z-Order by Facing Profile

Overview

RIGGING.md Task 2: when the stickman faces different directions, body parts must be drawn in the right order relative to the torso:

1. Facing left → left upper/lower arm and left upper/lower leg draw behind the torso; the right-side limbs draw in front. On the far (behind-torso) side the arm draws behind the leg; on the near (in-front) side the arm draws in front of the leg.
2. Facing right → right upper/lower arm and right upper/lower leg draw behind the torso; the left-side limbs draw in front, with the same far-arm-behind-leg / near-arm-in-front-of-leg rule.
3. Facing forward → all four limb pairs draw in front of the torso.
4. In all cases the head draws in front of the torso.

Task 1 already built the harness-level FacingProfile { LEFT, RIGHT, FORWARD } state (_facing_profile, the "Facing" MenuButton, _apply_facing_profile()). Task 2 reuses that profile state to also reorder the rig's Body/* visual part nodes.

1. Mechanism

master_rig.tscn's Body node is a plain Node2D container whose children are the per-part visual nodes: Head, Body (the torso visual), LeftUpperLeg, RightUpperLeg, LeftLowerLeg, RightLowerLeg, LeftUpperArm, RightUpperArm, LeftLowerArm, RightLowerArm. All have default z_index = 0, and Godot 4 Node2D draws siblings in tree order (first child = back, last child = front). The RemoteTransform2D drivers only push global transforms — they never touch tree order. Therefore draw order = child order of the Body container, and reordering is a pure move_child() operation. This is safe to do at any time: the adapter mounts shapes as children of each part node (_mount_shape adds Line2D/Polygon2D under the part node), so moving a part node moves its whole shape group and never disturbs intra-part shape order.

Per-part authored node names are fixed, so z-order tables are static string arrays — no runtime lookup by part key needed (the harness already owns the rig-facing logic for Task 1).

2. Z-order tables

Back-to-front (first entry = backmost, last = frontmost). Within each limb pair the upper limb stays behind the lower limb (the elbow/knee overlaps the lower limb). On the far (behind-torso) side the arm pair draws behind the leg pair; on the near (in-front) side the arm pair draws in front of the leg pair (per the user's per-direction spec). The head is always last.

const Z_ORDER_BY_PROFILE := { FacingProfile.FORWARD: [torso, left upper leg, right upper leg, left lower leg, right lower leg, left upper arm, right upper arm, left lower arm, right lower arm, head], FacingProfile.LEFT: [left upper arm, left lower arm, left upper leg, left lower leg, torso, right upper leg, right lower leg, right upper arm, right lower arm, head], FacingProfile.RIGHT: [right upper arm, right lower arm, right upper leg, right lower leg, torso, left upper leg, left lower leg, left upper arm, left lower arm, head] }

with node names from master_rig.tscn ("Head", "Body", "LeftUpperArm", …).

• FORWARD matches the requirement "legs and arms drawn in front of the torso"; all limbs are on the near side, so arms draw in front of legs.
• LEFT places both left limb pairs behind the torso (left arm behind left leg) and the right pairs in front (right arm in front of right leg) (requirement 1); RIGHT mirrors it (requirement 2).
• The head is frontmost in all three (requirement 4).

3. Implementation — scripts/test_harness.gd

3a. Constants

• const BODY_CONTAINER_PATH := "Body" — rig-relative path of the visual container.
• const Z_ORDER_BY_PROFILE: Dictionary = { FacingProfile.FORWARD: [...], ... } per §2.

3b. State

• var _body_container: Node2D = null — resolved at spawn, cleared in _free_current_rig().

3c. Resolution

• _resolve_rig_nodes() additionally resolves _body_container via _rig.get_node_or_null(NodePath(BODY_CONTAINER_PATH)) as Node2D (null → push_warning).

3d. Reorder

New _apply_body_z_order(): when _body_container is valid, walk the profile's ordered part names back-to-front and call _body_container.move_child(part, _body_container.get_child_count() - 1) for each existing child (skip missing parts — a .stk may omit a part). Moving to the end in back-to-front sequence yields the profile order and leaves unknown/extra children untouched at the back.

3e. Hooks

• _apply_facing_profile(profile) calls _apply_body_z_order() after setting the flip_bend_direction flags (single entry point: menu selection and fresh spawns both flow through it).
• No other changes: _load_and_spawn() already calls _apply_facing_profile(_facing_profile) after spawn, so every loaded rig gets the current profile's z-order.

4. Files modified

File	Changes
scripts/test_harness.gd	BODY_CONTAINER_PATH, Z_ORDER_BY_PROFILE, _body_container, resolve + clear + _apply_body_z_order(), hook in _apply_facing_profile().
docs/phase9_task2_zorder_spec.md	This file.
AGENTS.md	Test-harness section: "Phase 9 Task 2 body-part z-order" bullet.
README.md	Test-harness bullet: facing profiles now also reorder Body/* draw order.
RIGGING.md	Mark Task 2 implemented (Task 1 was documented in the same way).

5. Edge cases

• Missing Body container (foreign rig): null-guarded; z-order silently skipped.
• Missing part nodes (partial .stk): skipped by get_node_or_null; no warnings spam.
• Re-spawn: _body_container is re-resolved per spawn; _free_current_rig() nulls it.
• z_index: all authored Body/* nodes use default z_index = 0; nothing in the adapter or harness sets it, so tree order remains the sole depth source.

6. Design decisions

#	Decision	Justification
D1	Z-order lives in the harness, reusing FacingProfile state	The rig stays generic; Task 1 already made the harness the owner of facing state; the rig itself has no z-order concept.
D2	Upper limb behind lower limb in every profile	Elbow/knee joints overlap the lower limb; matching the authored scene order avoids joint seams.
D3	Far-side arms draw behind the legs; near-side arms draw in front of the legs (user-specified per direction)	Matches the user's Left/Right spec: e.g. facing left → left arm behind left leg, right arm in front of right leg.
D4	Head always frontmost (last in array)	Explicit requirement 4.

7. Test plan

1. Parse check: ..\Godot_v4.7.1-stable_win64_console.exe . --headless --check-only --quit (user-requested; no errors).
2. Temporary headless SceneTree script (pattern from the Round 7 spec; deleted afterwards):
   • Instantiate the harness scene, add_child it, call _load_and_spawn("res://stickmen/basic.stk").
   • Assert Body children order equals Z_ORDER_BY_PROFILE[FacingProfile.FORWARD].
   • Call _apply_facing_profile(FacingProfile.LEFT) → assert left limb pairs precede the torso node (left arm pair before left leg pair) and right pairs follow it (right leg pair before right arm pair); repeat for RIGHT (mirrored).
   • Assert Body/Head is the last child in all three profiles.
3. Manual F6 check: load a .stk, switch Facing — far-side limbs visibly tuck behind the torso; head stays on top.

8. Implementation order

1. scripts/test_harness.gd — constants, state, resolution, reorder + hook.
2. Parse check + headless verification script (temp, then removed).
3. Docs: AGENTS.md, README.md, RIGGING.md.