Ragdoll component

pages/docs/animation/skeletal-animation/skeleton-pose-component.md

@@ -1,6 +1,6 @@
 # Skeleton Pose Component
 
-The *skeleton pose component* allows you to assign a custom, static pose to an animated mesh. This can be used for decorative purposes, for instance to place an animated mesh in different poses in your scenes, but it can also be used as a start pose for a mesh that is further animated, for example through [ragdoll physics (TODO)](../../physics/jolt/ragdolls/jolt-ragdoll-component.md).
+The *skeleton pose component* allows you to assign a custom, static pose to an animated mesh. This can be used for decorative purposes, for instance to place an animated mesh in different poses in your scenes, but it can also be used as a start pose for a mesh that is further animated, for example through [ragdoll physics](../../physics/jolt/ragdolls/jolt-ragdoll-component.md).
 
 ![Custom pose for animated mesh](media/custom-pose.jpg)
 
@@ -14,7 +14,7 @@ The *skeleton pose component* allows you to assign a custom, static pose to an a
 
 ## Using Ragdolls for Posing
 
-When a pose component and a [ragdoll component (TODO)](../../physics/jolt/ragdolls/jolt-ragdoll-component.md) are both present on an animated mesh, the pose component can be used to define the starting pose of the ragdoll (make sure to configure the ragdoll to *wait for a pose* before it starts simulating).
+When a pose component and a [ragdoll component](../../physics/jolt/ragdolls/jolt-ragdoll-component.md) are both present on an animated mesh, the pose component can be used to define the starting pose of the ragdoll (make sure to configure the ragdoll to *wait for a pose* before it starts simulating).
 
 Additionally, when you [simulate a scene](../../editor/run-scene.md) in editor, you can [save the result of a ragdoll simulation](../../editor/run-scene.md#keep-simulation-changes) in a pose component:
 
@@ -28,4 +28,4 @@ You can then adjust individual limbs and repeat the process with a new starting
 
 * [Skeletal Animations](skeletal-animation-overview.md)
 * [Animated Mesh Component](animated-mesh-component.md)
-* [Ragdoll Component (TODO)](../../physics/jolt/ragdolls/jolt-ragdoll-component.md)
+* [Ragdoll Component](../../physics/jolt/ragdolls/jolt-ragdoll-component.md)

pages/docs/physics/jolt/actors/jolt-actors.md

@@ -42,7 +42,7 @@ Triggers are set up by attaching a [trigger component](jolt-trigger-component.md
 
 ## Other Actors
 
-ezEngine comes with a couple of additional components that end up as physics actors in the simulation, but have additional functionality for specific use cases. For example the [query shape actor](jolt-queryshape-actor-component.md) and the [hitbox component](../ragdolls/jolt-hitbox-component.md) can be used to define hit-boxes and the [ragdoll component (TODO)](../ragdolls/jolt-ragdoll-component.md) is used to physically simulate creatures.
+ezEngine comes with a couple of additional components that end up as physics actors in the simulation, but have additional functionality for specific use cases. For example the [query shape actor](jolt-queryshape-actor-component.md) and the [hitbox component](../ragdolls/jolt-hitbox-component.md) can be used to define hit-boxes and the [ragdoll component](../ragdolls/jolt-ragdoll-component.md) is used to physically simulate creatures.
 
 ### Character Controller
 

pages/docs/physics/jolt/ragdolls/jolt-hitbox-component.md

@@ -8,7 +8,7 @@ The component must be attached next to another component that defines the [skele
 
 Consequently, the configuration of the hitbox shapes is set up through the [skeleton asset](../../../animation/skeletal-animation/skeleton-asset.md).
 
-The hitboxes are usually used to be able to shoot an animated character. Although they share the collider setup with the [Jolt ragdoll component (TODO)](jolt-ragdoll-component.md), hitboxes and ragdolls are separate features that can be used independently of each other. For example, while a character is alive, it would use hitboxes, so that raycasts can determine where it would be hit, but it would not use a ragdoll component yet. Once a character dies, a ragdoll component would be activated to make it fall to the ground. The hitbox component could now be deactivated (which also makes sense for performance reasons), since it's functionality may not be needed anymore.
+The hitboxes are usually used to be able to shoot an animated character. Although they share the collider setup with the [Jolt ragdoll component](jolt-ragdoll-component.md), hitboxes and ragdolls are separate features that can be used independently of each other. For example, while a character is alive, it would use hitboxes, so that raycasts can determine where it would be hit, but it would not use a ragdoll component yet. Once a character dies, a ragdoll component would be activated to make it fall to the ground. The hitbox component could now be deactivated (which also makes sense for performance reasons), since it's functionality may not be needed anymore.
 
 ## Component Properties
 
@@ -17,7 +17,7 @@ The hitboxes are usually used to be able to shoot an animated character. Althoug
 
 ## See Also
 
-* [Jolt Ragdoll Component (TODO)](jolt-ragdoll-component.md)
+* [Jolt Ragdoll Component](jolt-ragdoll-component.md)
 * [Jolt Query Shape Actor Component](../actors/jolt-queryshape-actor-component.md)
 * [Skeleton Asset](../../../animation/skeletal-animation/skeleton-asset.md)
 * [Skeletal Animations](../../../animation/skeletal-animation/skeletal-animation-overview.md)

pages/docs/physics/jolt/ragdolls/jolt-ragdoll-component.md

@@ -1,10 +1,49 @@
 # Jolt Ragdoll Component
 
-<!-- PAGE IS TODO -->
+> **Note**
+>
+> Ragdolls are a work-in-progress feature. They are working, but the exact functionality may change in the future.
 
-Ragdolls are a work-in-progress feature. They are partially working, but unfinished and their functionality will change in the future.
+The *Jolt ragdoll component* is used to physically simulate limp bodies.
+
+<video src="media/ragdolls.webm" width="800" height="600" autoplay loop></video>
+
+## Ragdoll Configuration
+
+Ragdolls only work with [skeletons](../../../animation/skeletal-animation/skeleton-asset.md) that have a proper bone collider and joint setup. The most important bones need to have *collider shapes*. Additionally, bones that should be anatomically connected, need to have *joints* set up. Bones also must adhere to a physically plausible hierarchy, meaning that leg bones should be child bones of a hip bone, feet bones must be child bones of leg bones and so on. Unfortunately many assets don't strictly follow this rule, which often makes them unsuitable for use as a ragdoll.
+
+The ragdoll component works with *uniform scaling*, so you can create differently sized characters or objects. It does *not* work with non-uniform scaling.
+
+It is common to add a ragdoll component to a character, but set the component to *inactive*, and only activate the component when the character goes limp.  
+
+## Breakable Objects
+
+The ragdoll component can be used for a simple breaking effect. For this you need to build a mesh out of broken pieces and give each piece a bone. In the rest pose the mesh should look like one piece. Now you can use a [visual script](../../../custom-code/visual-script/visual-script-overview.md) to determine under what conditions the object should shatter and then activate the ragdoll component. In this case the skeleton only needs to define shapes for the bones, but no joints between them. Thus each fragment will fall individually and the object looks like it breaks apart.
+
+Use the properties `CenterPosition`, `CenterVelocity` and `CenterAngularVelocity` to make the pieces fly away more convincingly.
+
+> **Important**
+>
+> This feature is only experimental and very limited in functionality.
+
+<video src="media/breakable.webm" width="800" height="600" autoplay loop></video>
+
+## Component Properties
+
+* `SelfCollision`: Whether the individual bones of a ragdoll shall collide with each other. If disabled, they will pass through each other and only the joint constraints will prevent unnatural motion. Wether self collision works well or not on a given character highly depends on how the colliders for the bones are set up.
+* `StartMode`: In which *pose* the ragdall should start:
+    * `WithBindPose`: The ragdoll starts immediately and uses the default bind pose (or rest pose) of the skeleton.
+    * `WithNextAnimPose`: The ragdoll waits for the next animation pose from and then starts from there. This requires a [simple animation component](../../../animation/skeletal-animation/simple-animation-component.md) or [animation controller](../../../animation/skeletal-animation/animation-controller/animation-controller-overview.md) to be active.
+    * `WithCurrentMeshPose`: The ragdoll starts immediately with the current pose. This does not require another component to regularly provide new poses and thus can also be used with a [skeleton pose component](../../../animation/skeletal-animation/skeleton-pose-component.md).
+* `GravityFactor`: How much gravity to use.
+* `Mass`: How heavy the ragdoll should be.
+* `StiffnessFactor`: The overall stiffness of the joints. Each joint has an individual stiffness as defined in the [skeleton asset](../../../animation/skeletal-animation/skeleton-asset.md), but when scaling characters up or down, it may be necessary to also scale the stiffness.
+* `OwnerVelocityScale`: A ragdoll may get enabled while a character is moving, for example while it is running. The owner object velocity is then transferred to the ragdoll to have it continue falling into the direction, rather then suddenly stop and just fall down. This factor allows to tweak how much of that momentum to keep (or even exaggerate).
+* `CenterPosition`: An experimental feature mainly meant for breakable objects (ragdolls with no joints). Specifies an offset where the *center* of the object should be, to apply an outwards force from. 
+* `CenterVelocity`, `CenterAngularVelocity`: What linear and angular velocity to set at start outwards from the `CenterPosition` on each bone. This makes it possible to build *breakable* objects that break apart when the ragdall gets activated.
 
 ## See Also
 
 * [Skeletal Animations](../../../animation/skeletal-animation/skeletal-animation-overview.md)
 * [Jolt Hitbox Component](jolt-hitbox-component.md)
+* [Skeleton Asset](../../../animation/skeletal-animation/skeleton-asset.md)

pages/docs/toc.md

@@ -115,7 +115,7 @@
 #### [Jolt Swing-Twist Constraint Component](physics/jolt/constraints/jolt-swing-twist-constraint-component.md)
 ### Ragdolls
 #### [Jolt Hitbox Component](physics/jolt/ragdolls/jolt-hitbox-component.md)
-#### [Jolt Ragdoll Component (TODO)](physics/jolt/ragdolls/jolt-ragdoll-component.md)
+#### [Jolt Ragdoll Component](physics/jolt/ragdolls/jolt-ragdoll-component.md)
 ### Special
 #### [Character Controller](physics/jolt/special/jolt-character-controller.md)
 #### [Jolt Grab Object Component](physics/jolt/special/jolt-grab-object-component.md)