stickman/plans/PHASE_8_RIG_MODULARIZATION.md

Architecture Plan: Rig Relocation & Component Modularization

Objective

Relocate master_rig.tscn to res://scenes/stickman_rig.tscn and decouple stickman_rig.gd into dedicated, single-responsibility sub-components to improve maintainability, testability, and concern separation.

---

Phase 1: File Operations & Scene Relocation

1. Move res://master_rig.tscn to res://scenes/stickman_rig.tscn within Godot to maintain internal UID mappings and resource links.

2. Verify sub-resource integrity after relocation.

---

Phase 2: Script Modularization (stickman_rig.gd)

Extract key responsibilities into sub-nodes or dedicated helper scripts attached to stickman_rig.tscn:

• Ragdoll & Recovery Component (StickmanRagdoll)

• Move ragdoll body/joint tables (RAGDOLL_BODIES, RAGDOLL_JOINTS) and joint limit bands.

• Move procedural physics node instantiation (RagdollBodyContainer), pin joint setups, and impulse application (apply_ragdoll_velocity_boost).

• Extract rest detection polling (REST_LINEAR_THRESHOLD, REST_ANGULAR_THRESHOLD), rest timers, and stand-up recovery tweens (request_recovery, snap_to_standing).

• Locomotion & Terrain Subsystem (StickmanLocomotion)

• Extract surface raycast probing (_probe_ground_y, _probe_terrain_fan) and root elevation adjustments (_reanchor_root_to_landing).

• Move airborne physics, horizontal drag calculations (AIR_DRAG_X), downward gravity acceleration, and procedural wind-drag pose flailing.

• Extract landing impact velocity capture and knee-compression crouch/spring recovery tweens.

• Director & Action Runner (StickmanActionRunner)

• Extract the action queue data structure (action_queue) and execution state machines (RunnerState, ActionPhase).

• Move pathfinding coordination (NavigationAgent2D), kinematic walk_to execution, and FOOT_OFFSET alignment.

• Handle speech bubble triggers (speak), wait timers, and rule-injected reactive action clearing (clear_reactive_actions).

• Core Rig Coordinator (StickmanRig)

• Retain core rig state management (ANIMATED, RAGDOLL, RECOVERING).

• Focus strictly on facing profiles (FacingProfile), TwoBoneIK bend direction toggles (BendDirection), and draw-order sorting (Z_ORDER_BY_PROFILE).

• Serve as the root coordinator relaying signals and state transitions to sub-components.

---

Phase 3: Reference & Script Updates

Update hardcoded string references from "res://master_rig.tscn" to "res://scenes/stickman_rig.tscn":

• scripts/stickman_factory.gd: Update spawn_from_data() instantiation target.

• scripts/test_harness.gd, scripts/stk_rig_adapter.gd, scripts/create_animations.gd: Update script comments, tool headers, and path constants.

• tests/ Suite: Search and replace hardcoded scene path string literals across all unit tests.

---

Phase 4: Documentation Updates

Update path references across project markdown files:

• README.md, AGENTS.md, RIGGING.md, and relevant files in specs/ and plans/.

---

Phase 5: Verification & Acceptance Criteria

1. Separation & Testability: Confirm that locomotion raycasting and action runner execution can be tested independently without instantiating ragdoll physics.

2. Factory Instantiation: Verify StickmanFactory.spawn() loads res://scenes/stickman_rig.tscn cleanly without path errors.

3. Test Harness Verification: Run res://scenes/test_harness.tscn via F6 to ensure walk, speak, wait, and ragdoll actions execute cleanly.

4. Automated Suite: Run the full project unit test suite in tests/ to confirm all assertions pass.