# 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.