From 9a22322dba22236abd6eff448d64ab822b82516f Mon Sep 17 00:00:00 2001 From: Ryan Kegel Date: Fri, 18 Sep 2026 09:57:06 -0400 Subject: [PATCH] feat: Add architecture plan for rig relocation and component modularization --- .codex/agents/architect.toml | 4 +- plans/PHASE_8_RIG_MODULARIZATION.md | 79 +++++++++++++++++++++++++++++ 2 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 plans/PHASE_8_RIG_MODULARIZATION.md diff --git a/.codex/agents/architect.toml b/.codex/agents/architect.toml index 1add5fc..bb27340 100644 --- a/.codex/agents/architect.toml +++ b/.codex/agents/architect.toml @@ -21,6 +21,8 @@ You are the Lead Systems Architect. Refer to `AGENTS.md` for project directory s - Target Nodes / Classes modified. - Signal interfaces & static type contracts. - Layout/Theme updates required. + - **Visual Diagrams & Schematics:** Include ASCII diagrams or Mermaid charts illustrating node hierarchies, state transitions, or signal flow interactions. + - **Concrete Examples & Data Flows:** Provide code/data examples demonstrating practical usage, sample dictionary shapes, or step-by-step state transformations. - **Architectural Suggestions & Alternatives:** (Optional/Required if applicable) Highlight alternative approaches, potential pitfalls, or future-proofing ideas that improve the feature. -3. **Handoff:** Save to `specs/[feature-name].md` and stop for user approval. +3. **Handoff:** Save to `specs/[feature-name].md` and display a summary including key diagrams and practical examples, then stop for user approval. """ \ No newline at end of file diff --git a/plans/PHASE_8_RIG_MODULARIZATION.md b/plans/PHASE_8_RIG_MODULARIZATION.md new file mode 100644 index 0000000..4d0237a --- /dev/null +++ b/plans/PHASE_8_RIG_MODULARIZATION.md @@ -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.