stickman/plans/RAGDOLL_CLEANUP.md

Ragdoll Cleanup — Implementation Plan

1. Overview

This plan addresses three specific issues with the stickman's ragdoll state:

#	Issue	Impact
1	Recovery Position Offset	Stickman floats above the terrain when recovering from ragdoll.
2	Visual Identity Loss	Custom colors/shapes disappear; replaced by gray bones.
3	Profile Persistence	Joint bending doesn't respect LEFT/RIGHT/FORWARD profile in ragdoll.

Each issue has a clear fix and verification steps.

---

2. Issue 1: Recovery Position Offset (Floating)

2.1. The Problem

When the stickman recovers from ragdoll, it appears floating above the terrain at the landing position, rather than standing with feet on the ground.

Root Cause: _reanchor_root_to_landing() calculates the ground contact point using _captured_ground_y = torso.center.y + RAGDOLL_TORSO_RADIUS. This assumes the torso is lying flat on its side. If the ragdoll's torso is rotated (as it often is after a fall), the calculated ground point is incorrect. I

2.2. The Fix

Replace the torso-capsule ground calculation with a downward raycast from the ragdoll's center to find the actual terrain surface.

Implementation:

# In _start_recovery() before destroying the ragdoll:
func _get_ground_y_at_position(world_pos: Vector2) -> float:
    var space := get_world_2d().direct_space_state
    var query := PhysicsRayQueryParameters2D.create(
        world_pos + Vector2(0, -50),  # Start slightly above
        world_pos + Vector2(0, 2000)  # Downward
    )
    query.collision_mask = 1  # Terrain layer
    var result := space.intersect_ray(query)
    if result:
        return result.position.y
    return world_pos.y  # Fallback to current Y

Then use this to position the standing figure's feet:

# In _reanchor_root_to_landing():
var ground_y := _get_ground_y_at_position(_captured_landing_center)
var feet := Vector2(_captured_landing_center.x, ground_y)
var new_root := feet + FOOT_OFFSET
global_position = new_root

2.3. Acceptance Criteria

• Stickman recovers to a standing position with feet touching the terrain surface.
• Works on flat ground.
• Works on slopes and uneven terrain.
• Works on ramp edges.
• No floating or clipping into terrain.

3. Issue 2: Ragdoll Visual Identity

3.1. The Problem

When entering ragdoll mode, the stickman's custom colors and shapes are hidden, replaced by gray capsule "bone guide" visuals.

Root Cause: _enter_ragdoll() hides Body/* visuals and spawns plain RigidBody2D bodies with default capsule colors. The gray appearance is the default capsule color.

3.2. The Fix Ragdoll bodies should inherit the visual properties (colors, shapes) from the Body/* nodes.

Implementation:

Read the geometry and color from each Body/* part node (Line2D or Polygon2D).

Create matching visual children on each ragdoll rigidbody.

The ragdoll's collision shapes remain simple capsules for physics; visual shapes are cosmetic overlays.

Mapping:

Body Node	Ragdoll Body	Visual Child
Body/Head	Head RigidBody	CircleShape2D (color from visual)
Body/Body	Torso RigidBody	CapsuleShape2D (color from visual)
Body/LeftUpperArm	LeftUpperArm RigidBody	CapsuleShape2D (color from visual)
etc.	etc.	etc.

Important: The visual shapes are positioned/rotated to match the ragdoll body's orientation. They are cosmetic only — physics uses the capsule collision shapes underneath.

3.3. Acceptance Criteria

• Ragdoll bodies match the stickman's custom colors and shapes.
• No gray "bone guide" visuals appear.
• Visuals transition smoothly between ANIMATED and RAGDOLL.
• Visuals stay consistent when exiting ragdoll.

4. Issue 3: Profile Persistence in Ragdoll

4.1. The Problem

The stickman's facing profile (LEFT/RIGHT/FORWARD) bone bending does not persist into ragdoll mode. Joints bend unrealistically when ragdolling.

Root Cause: The ragdoll's PinJoint2D angular limits are set once at build time using a generic rule. They don't account for the current facing_profile.

4.2. The Fix

The ragdoll build should read the current facing_profile and apply profile-specific joint limits.

Implementation:

When building the ragdoll (_build_ragdoll()), pass the current facing_profile to _apply_ragdoll_joint_limits():

FORWARD: Use the existing default (elbows/knees fold toward +CW).

LEFT: Mirror the joint limits (swap the elbow/knee fold direction).

RIGHT: Use the same as FORWARD (or mirror appropriately).

Using PROFILE_FLAGS:

The existing PROFILE_FLAGS constants already map facing profiles to per-joint flip_bend_direction flags. Use these to determine joint limit mirroring:

Joint	FORWARD	LEFT	RIGHT
LeftArm	Normal	Normal	Inverted
RightArm	Inverted	Normal	Normal
LeftLeg	Inverted	Inverted	Normal
RightLeg	Normal	Inverted	Inverted
``
The flip_bend_direction flag determines which way the joint naturally bends. This should be applied to the ragdoll's PinJoint2D angular limits.

Example for elbow/knee joints:

```gdscript
# If flipped = true, the joint bends toward -CW instead of +CW
if flipped:
    joint.angular_limit_lower = -150.0
    joint.angular_limit_upper = 5.0
else:
    joint.angular_limit_lower = -5.0
    joint.angular_limit_upper = 150.0

4.3. Acceptance Criteria

• LEFT profile ragdoll joints bend the correct way.
• RIGHT profile ragdoll joints bend the correct way.
• FORWARD profile ragdoll joints bend the correct way.
• Profile persists after recovery.
• Joints do not hyperextend or bend backwards.

5. Implementation Order

Step	Task	Dependencies
1	Fix Recovery Position — Replace torso-capsule ground calculation with downward raycast.	None
2	Fix Ragdoll Visuals — Ragdoll bodies inherit Body/* geometry/color as cosmetic children.	None
3	Fix Profile Persistence — Ragdoll joints respect facing_profile via PROFILE_FLAGS.	None
4	Integration Test — Test all three fixes together in the Sandbox Stage.	Steps 1-3

6. File Changes Summary

File	Changes
scripts/stickman_rig.gd	Fix _reanchor_root_to_landing() with raycast; _build_ragdoll() reads facing_profile; _apply_ragdoll_joint_limits() uses profile flags for mirroring; _enter_ragdoll() preserves visual geometry.

7. Full Acceptance Criteria

7.1. Recovery Position

• Stickman recovers to a standing position with feet touching the terrain surface.
• Works on flat ground, slopes, and uneven terrain.
• No floating or clipping into terrain.

7.2. Ragdoll Visuals

• Ragdoll bodies match the stickman's custom colors and shapes.
• No gray "bone guide" visuals appear.
• Visuals transition smoothly between ANIMATED and RAGDOLL.
• Visuals stay consistent when exiting ragdoll.

7.3. Profile Persistence

• LEFT profile ragdoll joints bend the correct way.
• RIGHT profile ragdoll joints bend the correct way.
• FORWARD profile ragdoll joints bend the correct way.
• Profile persists after recovery.
• Joints do not hyperextend or bend backwards.

7.4. Backward Compatibility

• Existing ragdoll behavior remains intact.
• Existing profiles work as before.
• No new errors or warnings in the console.