feat: Add architecture plan for rig relocation and component modularization

2026-09-18 09:57:06 -04:00
parent 1a2a43c805
commit 9a22322dba
2 changed files with 82 additions and 1 deletions
@@ -0,0 +1,79 @@
+# 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.