80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
# 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.
|