A ragdoll represents a 3D animated character in the physics engine. To define a ragdoll you need several Bodies that represent the limbs of a character. In many cases, rigid bodies are only created for the important bones of the character skeleton. The rigid bodies are connected using constraints, e.g. BallJoints, HingeJoints, etc. See property Joints. Limits are constraints that restrict the relative movement of limbs to avoid unrealistic poses. Motors can be used to control the ragdoll pose.

The Ragdoll class is a container for all the parts of a ragdoll (bodies, joints, limits, motors, etc.). When AddToSimulation(Simulation) is called, all relevant parts are added to the physics Simulation and the ragdoll simulation starts. RemoveFromSimulation must be called to stop the ragdoll simulation and/or when the ragdoll is no longer needed.

UpdateBodiesFromSkeleton(SkeletonPose) takes a skeleton and moves the ragdoll bodies so that they match the skeleton pose. This method instantly moves ("teleports") the bodies to their new positions. When this method is used, the bodies do not smoothly interact with other physics objects. This method is usually only used to initialize the rigid body positions when the ragdoll is added to the simulation.

UpdateSkeletonFromBodies(SkeletonPose) animates a SkeletonPose so that it matches the ragdoll posture. If a skeleton should be animated by the physics system, then this method must be called in each frame.

DriveToPose(SkeletonPose, Single) uses motors to control the movement of the bodies. This method must be used if the ragdoll should interact with other physics objects, or if an animation should be blended with the physically-based movement.

While a ragdoll is added to a simulation, it is not allowed to add or remove Bodies, Joints, Limits or Motors.

Ragdoll creation:
The ragdoll does not contain helper methods for ragdoll creation. To create the ragdoll rigid bodies must be added to Bodies. The order of the rigid bodies is important because the index in this list determines with which skeleton bone the body will be associated. This list can contain entries (often bodies are only created for important bones). It is allowed that this list has less or more entries than the number of bones. Offsets can be added to BodyOffsets. The order of BodyOffsets is the same as for Bodies. If no offsets are set the bodies are centered at the bone origins.

Constraints that connect the rigid bodies should be added to the Joints list. The joints in this list can have any order. Typically, a BallJoint is created at each bone origin to connect the body of a bone with the body of the parent bone.

Constraints that restrict the allowed relative body movement should be added to the Limits list. The limits in this list can have any order.

Motors that control body movement should be added to Motors. The motors in this list can have any order.

Ragdoll usage scenarios:

• Collision detection only: A ragdoll can be used to detect collisions with an animated character. In this scenario, UpdateBodiesFromSkeleton(SkeletonPose) is called in each frame to set the rigid bodies to the pose of the skeleton. The physics Simulation can be used to detect collision of other rigid bodies with the ragdoll.
• Death animations: The ragdoll is activated when the character is dead. The bodies are simulated to create a falling animation. UpdateSkeletonFromBodies(SkeletonPose) is called in each frame. The physics simulation controls the skeleton animation.
• Character can push other bodies: The ragdoll bodies are Kinematic. Motors are used to move the rigid bodies to the skeleton position. In each frame DriveToPose(SkeletonPose, Single) must be called. If the rigid bodies collide with other obstacles, they move the obstacles. This is a one way interaction - the ragdoll does not react to collisions with other objects.
• Blending animation and physics: The ragdoll is controlled by the simulation and constraint motors are used to drive the bodies to a target skeleton pose. This can be used to let the ragdoll fall (simulated by the physics engine) and at the same time the character tries to obtain a defensive posture. In this scenario, DriveToPose(SkeletonPose, Single) must be called to set the motor target position. UpdateSkeletonFromBodies(SkeletonPose) must be called in each frame to update the skeleton of the visible model.

Reference