[PlasmaDev5]

Active ragdoll

A new Active anim mode for plJoltRagdollComponent: the ragdoll follows the animation pose with its own muscles, keeps its balance, and reacts to hits and falls the way a person would. Settings live in a new Ragdoll Profile asset (presets: Dead, Stunned, Conscious, Athlete, Slapstick) with a property-grid editor.

What the controller does

• Muscles: an arbiter blends weighted pose proposals (animation, neutral float pose, protection poses, IK) per joint. Muscles that carry weight are stiff against the inertia they move; reacting arms are softer and underdamped, so they swing instead of snapping.
• Balance: capture-point balance with a capped upright assist and up to two recovery steps. The stepping leg follows IK alone, its foot lifts early, and a small internal foot-pelvis assist carries it to the target.
• Stagger: the arms are thrown out against the push while stepping.
• Hand-over: when balance fails, the muscles keep working over 0.45 s. The knees buckle progressively and the arms come round into the catch, rather than the body dropping limp.
• Saving the fall:
  • Catch: the arms reach for the ground in the fall direction until the first impact, then the elbows give into the head guard.
  • Side landing: while a foot is down, the body twists so a hip and shoulder take the impact. The lower arm reaches down, the upper one guards the head.
  • Leg reach: after balance fails, the rear leg reaches for the ground (on stairs, the next step down) and the front knee comes up.
  • Grab: the hands probe for solid, non-floor surfaces in reach and grip with a spring (up to half the body's weight, tears 25 cm off the hold).
• On the ground: face, back and boxer guards; a roll guard with arm bracing against the roll; a limb-spread slide brake. A settled body relaxes and lies flat instead of arching.
• Injury: joints can dislocate but never past a hard envelope (region caps: shoulder 120/80, elbow 100/60, knee 90/30). A per-substep spin backstop plus a post-step position projection keep overshoot to about 2°.
• Debug overlay (Jolt.Ragdoll.Debug 1): active behaviour, why balance gave up, every blend weight, fall direction, grab state, and a line per bone showing where its muscles want it.

Tests

Tests/JoltRagdollTests.cpp, group ragdoll: 45 checks, 0 failures, 8 open plan gates (Development). The controller costs about 0.6 ms per frame for 8 ragdolls, physics excluded.

JoltTests.exe --record-ragdolls <folder> writes per-frame body transforms for the scenarios, so the motion can be inspected without an editor.

Tried in engine

A live demo in a TestingChambers copy with the Quaternius UAL1 mannequin (CC0). A shot stumbles it back two steps along a wall and the right hand grabs the wall. It goes over the edge with a catch, side landing and leg reach, then tumbles down a 16-step flight. Captured from the Player window; videos are kept with the docs.

Open

• Plan gates (8 open): 120 N s push recovery (0 of 10), and the arms moving differently after a blast, among others.
• Missing harness checks: the newest behaviours (grab held or torn, side-landing rate, leg reach) are not yet checked in the harness; so far they have only been seen in the engine demo.
• Not run: the editor (profile asset window) and the EditorTest group.
• Engine bug, unfixed: code-built skeletons lose m_BoneDirection in plSkeleton's move. The test fixture works around it.

---

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}