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

Move res://master_rig.tscn to res://scenes/stickman_rig.tscn within Godot to maintain internal UID mappings and resource links.
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

Separation & Testability: Confirm that locomotion raycasting and action runner execution can be tested independently without instantiating ragdoll physics.
Factory Instantiation: Verify StickmanFactory.spawn() loads res://scenes/stickman_rig.tscn cleanly without path errors.
Test Harness Verification: Run res://scenes/test_harness.tscn via F6 to ensure walk, speak, wait, and ragdoll actions execute cleanly.
Automated Suite: Run the full project unit test suite in tests/ to confirm all assertions pass.

3.6 KiB Raw Blame History