Ragdoll

Export

Ragdoll gives a humanoid character’s body to Unity physics, allowing impacts and the environment to determine how it falls. Use it for physics-based deaths or scripted knockdowns. It is different from Die, which keeps the Animator in control and plays a selected death animation.

Before you begin

  • The built-in Character Manager workflow requires a Humanoid model with an Animator and mapped bones. It does not build Unity ragdolls for Generic models.
  • The model needs child bone Rigidbody, Collider, and Character Joint components. The character’s main Rigidbody remains on the root and is not part of the ragdoll body.
  • Run the Setup Manager’s Project setup so the Character, SubCharacter, and VisualEffect layers and their collision matrix exist.
  • Decide whether death should use Ragdoll or Die. Both listen to the death lifecycle, so do not leave both responses enabled unless their priority and states are deliberately coordinated.
  • Ragdoll does not include a stand-up animation or reposition the controller to the final physics pose. A recoverable knockdown needs additional recovery logic.

Build the ragdoll

Build with Character Manager

  1. Open Tools > Opsive > Ultimate Character Controller > Character Manager.
  2. Select the existing Humanoid character and confirm its Animator model is valid.
  3. Enable Ragdoll and select Update Character. For a new character, leave Ragdoll enabled when selecting Build Character.
  4. Character Manager adds the Ragdoll ability and runs Unity’s Ragdoll Builder for each Humanoid model.
  5. Expand the model hierarchy and inspect the generated colliders, rigidbodies, and joints. Adjust collider sizes and joint limits so they fit the mesh without intersecting neighboring body parts.

Add it to an existing ability list

  1. Select the character and open Ultimate Character Locomotion.
  2. Expand Abilities, select +, and add Ragdoll.
  3. Move Ragdoll near the top of the list, above ordinary movement, interaction, item, and impact abilities. The supplied character places it first.
  4. In the Ragdoll ability, select Add Ragdoll Colliders. Review the prefilled Humanoid bone assignments in Unity’s Ragdoll Builder and complete the build.
  5. If the hierarchy already has a complete ragdoll, do not build a second one. Each participating bone should have one intended Rigidbody and Collider setup.

At runtime, Ragdoll treats every child Rigidbody beneath the character root as part of the physics body. Keep unrelated rigidbodies, such as detachable props, outside that hierarchy or verify that controlling them with the ragdoll is intentional.

Configure the ability

  1. Keep Start Type and Stop Type set to Manual. The death event or gameplay code starts and stops the ability.
  2. Keep State set to Death for the standard death-state response.
  3. Enable Start On Death for a physics-based death. Disable it for a knockdown that should be controlled only by gameplay code.
  4. Start with the source defaults:
    • Start Delay: 0
    • Ragdoll Layer: Character
    • Inactive Ragdoll Layer: SubCharacter
    • Camera Rotational Force: (0, 0, 0.75)
    • Interpolation Mode: None
    • Collision Detection Mode: Continuous
  5. Leave Allow Positional Input and Allow Rotational Input disabled. The standard ability also disables the main controller’s gravity and horizontal and vertical collision detection while active; the child rigidbodies handle those responsibilities.

Ragdoll does not use an Ability Index or an Animator state-machine branch. It disables the Animator when physics begins.

Choose the physics behavior

Death or recoverable knockdown

With Start On Death enabled, Ragdoll receives the position and force from OnDeath, starts even though the character is no longer alive, and remains active until the respawn lifecycle sends OnWillRespawn.

For a temporary knockdown, disable Start On Death and start and stop Ragdoll from gameplay code. Stopping while the character is alive freezes the child rigidbodies, enables the Animator and main colliders, and sends an Animator snap. The controller stays at its existing transform, so a body that has rolled away will visually snap back. Reposition the controller and select an appropriate get-up pose before stopping if recovery should happen at the body’s final location.

Start delay

Start Delay postpones the switch from animation to physics. The Death state and camera response begin immediately, while the Animator and main colliders remain active until the fixed-time delay expires.

Keep the delay shorter than every possible respawn or manual-recovery time. The Version 3 ability schedules the physics switch without retaining a cancellation handle, so stopping before the delay expires does not cancel that pending switch.

Active and inactive layers

Ragdoll Layer is assigned to every child Rigidbody while physics is active. The default is Character. The source tooltip recommends VisualEffect when other characters should not step over the body; verify the result against the project’s collision matrix and gameplay requirements.

Inactive Ragdoll Layer defaults to SubCharacter. This keeps the frozen child colliders from behaving like additional locomotion colliders while the character is animated. A wrong inactive layer commonly causes self-collision or movement jitter.

Camera and rigidbody settings

Camera Rotational Force adds a camera reaction when the ability starts. A death multiplies this vector by the killing force magnitude; a manual start uses the configured vector directly.

Interpolation Mode and Collision Detection Mode are applied to every child Rigidbody while active. Use interpolation when the visible physics needs smoothing. Keep a continuous collision mode for fast impacts, or test a less expensive mode when the body moves slowly and physics cost matters.

How it runs

On initialization, Ragdoll disables its child physics: the rigidbodies become kinematic and frozen, their collision mode becomes Discrete, their interpolation becomes None, and their GameObjects move to Inactive Ragdoll Layer.

When the ability starts, it sends the camera force and waits for Start Delay. It then disables the Animator, clears locomotion position and rotation forces, disables the main character colliders, and activates every child Rigidbody. The rigidbodies inherit the character’s configured gravity, use the selected interpolation and collision mode, move to Ragdoll Layer, and receive the killing force at the supplied impact position.

When Ragdoll stops, it reverses those changes: child bodies freeze, the Animator and main colliders return, and the inactive layer is restored. With Start On Death enabled, this happens on OnWillRespawn, before the Respawner moves and reactivates the character. A manual living recovery also sends OnCharacterSnapAnimator so the model returns to the controller pose.

Verify in Play Mode

  1. Keep the Ragdoll ability, Animator, root Rigidbody, and several child bone rigidbodies visible in the Inspector.
  2. Before activation, confirm the Animator is enabled, the main character colliders are enabled, and child rigidbodies are kinematic, frozen, and on Inactive Ragdoll Layer.
  3. Apply lethal damage with a visible impact force. Confirm Ragdoll becomes active, the camera reacts, and physics begins after Start Delay.
  4. While active, confirm the Animator and main colliders are disabled, child rigidbodies are non-kinematic and unconstrained, and the hit force moves the body from the correct position.
  5. Repeat with a low and high killing force. Confirm the physical and camera reactions scale with that force.
  6. Allow Character Respawner to run. Confirm Ragdoll stops on OnWillRespawn, the inactive layer and frozen child bodies return, the Animator and main colliders are enabled, and normal movement works after respawn.
  7. For a recoverable knockdown, start and stop the ability while the character is alive. Confirm the expected snap behavior before implementing any custom root repositioning or get-up animation.
  8. Test the complete cycle on slopes, stairs, walls, and around other characters to validate collider sizes, joint limits, and layer collisions.

Troubleshooting

Symptom Check Fix
Add Ragdoll Colliders does nothing The model has an Animator Monitor, an Animator, a Humanoid Avatar, and mapped required bones. Configure the model as Humanoid and rebuild through Character Manager. Generic models are not supported by the built-in ragdoll builder workflow.
The character collapses incorrectly or explodes Generated colliders overlap, joint anchors or limits are unsuitable, or the model scale is problematic. Adjust the Rigidbody mass distribution, collider shapes, and Character Joint limits in the model hierarchy, then retest from a neutral pose.
The body does not fall Child bones have rigidbodies and Start Delay has elapsed. Build the ragdoll, verify the child bodies are beneath the character root, and confirm they become non-kinematic and unconstrained when active.
The Animator continues controlling the body Ragdoll is active and the selected child rigidbodies were discovered during initialization. Confirm the correct Ragdoll ability instance starts and that the model uses the character’s Animator Monitor.
The body ignores the killing force The death source supplied a nonzero force and hit position through OnDeath. Correct the damage impact data. For a manual start, assign Ragdoll’s Force and Position properties before starting it.
The character jitters before ragdolling Child colliders are on Inactive Ragdoll Layer and the UCC layer matrix is installed. Restore SubCharacter, rerun the Setup Manager’s Project layer setup, and remove unrelated child rigidbodies from the ragdoll hierarchy.
Other characters collide with the body incorrectly Ragdoll Layer and the project collision matrix do not match the desired corpse behavior. Test Character and the component-recommended VisualEffect layer, then keep the choice that matches navigation and collision requirements.
Ragdoll and a death animation compete Both Ragdoll Start On Death and Die are enabled. Disable the unused response or deliberately coordinate their list priority and states.
The body reactivates after an early recovery or respawn The ability stopped before a nonzero Start Delay expired. Keep recovery and respawn later than the delay, or use 0 until custom cancellation is implemented.
The model snaps away when a living knockdown ends The controller root was not moved to the final ragdoll pose. Position and orient the controller from the chosen body reference, prepare a get-up pose, then stop Ragdoll.
The character remains ragdolled after a custom respawn The custom path did not send OnWillRespawn, or Start On Death is disabled for a manually controlled ragdoll. Stop Ragdoll explicitly before moving the character, or use the complete Character Respawner lifecycle.
Main colliders or animation do not return The Ragdoll ability never stopped. Confirm the respawn path sends OnWillRespawn, or call the standard ability stop API for a manual knockdown.
  • Die provides an Animator-driven death instead of a physics body.
  • Impact Knock Back provides a brief animated impact response and explicitly allows Ragdoll to take priority.
  • Health sends the death position and force used by Ragdoll.
  • Respawner sends the pre-respawn event that stops a death ragdoll.
  • Revive provides a different recovery path when the character should return through an ability.
  • Layer Manager explains the UCC collision layers.
  • Character Creation explains building and updating a Humanoid character through Character Manager.
  • Abilities explains list priority and manual ability control.

Developer reference

Ragdoll uses Start Type Manual, Stop Type Manual, and the Death state. It allows itself to remain active after death. It listens for OnDeath and OnWillRespawn, sends OnCameraRotationalForce, and sends OnCharacterSnapAnimator when a living character returns to animation. The usual OnCharacterAbilityActive event also reports its start and stop.

For a manual knockdown, set the optional force and position before starting the ability:

using Opsive.UltimateCharacterController.Character;
using Opsive.UltimateCharacterController.Character.Abilities;
using UnityEngine;

public class RagdollExample : MonoBehaviour
{
    [SerializeField] private UltimateCharacterLocomotion m_CharacterLocomotion;

    public void StartRagdoll(Vector3 position, Vector3 force)
    {
        var ragdoll = m_CharacterLocomotion.GetAbility<Ragdoll>();
        ragdoll.Position = position;
        ragdoll.Force = force;
        m_CharacterLocomotion.TryStartAbility(ragdoll);
    }

    public void StopRagdoll()
    {
        var ragdoll = m_CharacterLocomotion.GetAbility<Ragdoll>();
        m_CharacterLocomotion.TryStopAbility(ragdoll);
    }
}

Death-supplied force is multiplied by MathUtility.RigidbodyForceMultiplier before it is applied to each child Rigidbody. Under the multiplayer compile symbol, the ability also serializes each child body’s position, rotation, velocity, and angular velocity as its network start data.