feat: Implement kinematic-to-ragdoll transition system
- Added KINEMATIC_BLENDING_AND_RECOVERY.md to outline features for smooth transitions between kinematic and ragdoll states, including visual and physical blending, and ragdoll recovery. - Introduced KINEMATIC_TO_RAGDOLL.md detailing the objectives, scope, and core architecture for transitioning the stickman from kinematic to ragdoll mode. - Created KINEMATIC_TO_RAGDOLL_SPEC.md as an implementation specification, verifying codebase facts and correcting the initial plan based on Godot 4.4 source. - Enhanced StickmanRig with state management for animated and ragdoll modes, including momentum preservation and ragdoll construction. - Updated physics_test_harness to support toggling between kinematic and ragdoll states with user input.
This commit is contained in:
@@ -0,0 +1,72 @@
|
||||
# Kinematic-to-Ragdoll Translation
|
||||
|
||||
## 1. Objective
|
||||
|
||||
We want dynamic state-switching system that transitions the `master_rig.tscn` stickman from a kinematic, IK-driven puppet (`ANIMATED` mode) into a fully physical, ragdoll-driven entity (`RAGDOLL` mode). This enables natural falling, tumbling, and collision responses with the physics environment (terrain and props) while preserving the stickman’s current momentum.
|
||||
|
||||
## 2. Scope & Impact
|
||||
|
||||
- **Primary Target:** `scripts/stickman_rig.gd` (the runtime controller of `master_rig.tscn`).
|
||||
- **Secondary Target:** `scripts/physics_test_harness.gd` (adds trigger method).
|
||||
- **Scene Impact:** The `master_rig.tscn` scene file will **not** be modified. All ragdoll nodes (bodies and joints) will be spawned procedurally in code, keeping the scene file clean and maintaining the separation between visual authoring and runtime physics.
|
||||
|
||||
## 3. Core Architecture / Behavior
|
||||
|
||||
### 3.1. State Management
|
||||
|
||||
`StickmanRig` gains a new `state` property with two modes: `ANIMATED` and `RAGDOLL`.
|
||||
|
||||
- **`ANIMATED` (Default):** The skeleton and visual `Body/*` nodes are visible and driven by the `AnimationPlayer` and `SkeletonModificationStack2D` (IK). The script tracks the root node’s velocity every frame to cache momentum.
|
||||
- **`RAGDOLL`:** The kinematic rig is frozen (IK disabled, `AnimationPlayer` stopped), the `Body/*` visual nodes are hidden, and a new network of `RigidBody2D` nodes (with matching collision shapes) is spawned and reparented to the world root. Physical `PinJoint2D` nodes connect these bodies, simulating the bone hierarchy.
|
||||
|
||||
### 3.2. Velocity Handoff (Momentum Preservation)
|
||||
|
||||
To avoid unnatural "freeze" effects when switching, the system captures the `linear_velocity` and `angular_velocity` of the rig root in `ANIMATED` mode (using `_process`). Upon entering `RAGDOLL` mode, these cached velocities are applied directly to the ragdoll’s **Torso** body, ensuring the stickman continues its current motion (falling, sliding, etc.) seamlessly.
|
||||
|
||||
## 4. Implementation Breakdown
|
||||
|
||||
### 4.1. Ragdoll Construction
|
||||
|
||||
A dedicated builder function iterates over a predefined set of `Bone2D` nodes from the `Skeleton2D` hierarchy. For each bone, it spawns a `RigidBody2D` with the following specifications:
|
||||
|
||||
- **Position:** The midpoint of the bone (calculated from `global_position` and `bone.length`).
|
||||
- **Rotation:** Matches the `global_rotation` of the bone.
|
||||
- **Collision Shapes:**
|
||||
- **Head:** Uses a `CircleShape2D` with a radius of **100px** (matching the visual head graphic).
|
||||
- **Other Bones (Limbs & Torso):** Uses a `CapsuleShape2D`. The height matches the bone’s `.length` property, and the radius matches the visual line width (approximately **14px**).
|
||||
- **Mass Distribution:** The Torso is given a significantly higher mass (e.g., `8.0`) compared to limbs (e.g., `1.5`) to create realistic inertia and prevent limbs from dragging the body into orbit upon collision.
|
||||
- **Damping:** `Linear` and `Angular` damping are applied to prevent excessively bouncy or "spaghetti-like" behavior.
|
||||
|
||||
### 4.2. Jointing (Parent-Child Constraints)
|
||||
|
||||
For every child bone that has a valid parent bone, the system spawns a `PinJoint2D`.
|
||||
|
||||
- **Positioning:** The joint is placed at the **bottom of the parent bone**, which aligns with the **top of the child bone**.
|
||||
- **Rotation Limits (Critical for realism):**
|
||||
- **Elbows and Knees:** Angular limits are enforced (strictly restricted to prevent backward bending/hyperextension).
|
||||
- **Head/Neck:** Loose limits or free rotation to allow natural lolling.
|
||||
- **Torso/Shoulders/Hips:** Moderate limits to maintain structural integrity while allowing dynamic twisting.
|
||||
- **Stiffness:** The `softness` and `bias` properties are tuned to prevent limb separation (stretching) under stress.
|
||||
|
||||
### 4.3. Cleanup & Reversion
|
||||
|
||||
The `RAGDOLL` mode is designed to be reversible:
|
||||
|
||||
- When exiting `RAGDOLL` (or reloading the rig), all dynamically spawned `RigidBody2D` and `PinJoint2D` nodes are queued for deletion.
|
||||
- The kinematic `Body/*` nodes are made visible again.
|
||||
- The `SkeletonModificationStack2D` (IK) is re-enabled, and the `AnimationPlayer` is reset to a neutral state.
|
||||
|
||||
## 5. Integration with Test Harness
|
||||
|
||||
The existing `PhysicsTestHarness` scene will be updated to include a user trigger:
|
||||
|
||||
- **Key Binding:** Pressing the **R** key will call the `toggle_ragdoll()` method.
|
||||
- **Collision Proxy Management:** The harness currently places a `RigCollisionProxy` (a large static box) around the rig to allow props to interact with it. When entering `RAGDOLL` mode, this proxy **must be destroyed** immediately; otherwise, the physical ragdoll will spawn inside the box and float unrealistically. The ragdoll will instead collide directly with the actual terrain geometry.
|
||||
|
||||
## 6. Acceptance Criteria (For QA/Testing)
|
||||
|
||||
- **Transition Seamlessness:** Switching to ragdoll mid-walk or mid-air applies the correct linear/angular momentum so the stickman continues the trajectory naturally.
|
||||
- **Terrain Interaction:** The ragdoll must rest, slide, or tumble naturally on flat ground, ramps, and stairs (colliding with the `TerrainBlock` static bodies).
|
||||
- **Structural Integrity:** Limbs should not stretch or detach under gravity or moderate impact. Elbows and knees must not bend backwards.
|
||||
- **Visual Fidelity:** The physical collision shapes should align visually with the hidden `Line2D` bones (no floating collision boxes).
|
||||
- **Cleanup:** Rapid switching between modes (spawning/deleting ragdolls) does not cause memory leaks or orphaned nodes.
|
||||
Reference in New Issue
Block a user