All Classes Namespaces Functions Variables Enumerations Properties Pages
PuppetMaster Overview


PuppetMaster uses a "Dual Rig" that consists of the normal animated character (from hereby: "Target") and the simplified ragdoll structure ("Puppet"). The main purpose of PuppetMaster is to make the Puppet ragdoll physically follow the motion and animation of the animated Target character. It will do so by two means, first is articulating the joints ("Muscles"), the other is pinning the rigidbodies to their targets using AddForce commands ("Pins"). The classes that control the behaviour of the Muscles and handle their strength, pinning and other properties are called "Puppet Behaviours". The dual rig and the Behaviours will share a common parent GameObject ("Root") that serves as a container for the PuppetMaster character rig. The kinematic Target character will be mapped to the dynamic Puppet ragdoll by the means of "Mapping", which can also be smoothly blended in and out for the entire character or for each Muscle separately.

Dual Rig


The main advantage of using a dual rig over a single character setup is performance. It is much less expensive mostly due to not having the necessity of performing costly transformations with objects that have Colliders attached. The performance win becomes even greater when having to do IK/FK procedures on the target pose. The PuppetMaster can be smoothly blended to run in Kinematic or Disabled mode. The former will simply make the ragdoll kinematic and match it with the target, the latter will completely deactivate the ragdoll when you don't need it. The dual rig also allows for choosing between flat or tree hierarchy modes for the ragdoll (click "Flat/Tree Hierarhcy" from the PuppetMaster's context menu) and will allow for sharing ragdolls between multiple characters in a future release of PuppetMaster. The PuppetMaster will automatically set up the dual rig for you when provided with a reference to a traditional ragdoll character.



The Target can be thought of as the normal animated character that you would see in any game, it usually has a character controller and any other gameplay components attached. Each frame, PuppetMaster will read the pose of the Target and feed it to the Muscles of the Puppet for following. After physics has solved, the Target will be mapped to the pose of the Puppet based on the mapping settings and stay there until animation overwrites it the next frame.



The simplified ragdoll structure (Puppet) is essentially a duplicate of the Target, but with ragdoll Components attached and all other Components and GameObjects unrelated to physics stripped. The PuppetMaster requires for the ragdoll to be set up using ConfigurableJoints only. Any other Joint can be converted to a ConfigurableJoint by selecting the (root) GameObject and clicking on "GameObject/Convert to ConfigurableJoints" from the menu bar. The Puppet ragdoll can be set up in tree or flat hierarchy modes (click "Flat/Tree Hierarhcy" from the PuppetMaster's context menu).



The PuppetMaster will turn each ConfigurableJoint of the Puppet into a Muscle that maintains a reference to its animated target and automatically calculates Joint target rotations, pinning forces and other values. When the Puppet is unpinned, the ragdoll will follow the animation in muscle space and the result is physically authentic and accurate. When pinned, the pinning forces will move the ragdoll bones to the world space position of their targets, they can be imagined as spring joints pulling each ragdoll bone towards their animated target. Pinning is therefore an unnatural force that can be managed to make the ragdoll simulate game character motion that physically would be almost unachievable. The Muscles are listed in the PuppetMaster's inspector, each having individual properties, enabling you to specify the physical behaviour of each Muscle or Muscle Group.



The PuppetMaster can run in 3 Modes. Active is the active ragdoll mode that makes the Puppet physically follow its Target by employing the muscle forces, pins or both at the same time. The Puppet is able to collide with and be affected by objects in the scene. The Kinematic mode makes the Rigidbodies of the Puppet kinematic and the Muscles will not be used anymore. The Puppet is still able to collide with objects and receive raycast hits. The Disabled mode completely deactivates the Puppet along with its Rigidbodies and Colliders. In Disabled mode the PuppetMaster will not have any effect on the performance. All modes can be blended in/out smoothly in respect to the "Blend Time" parameter.

Puppet Behaviours


The Puppet Behaviours are classes that inherit from the abstract BehaviourBase.cs and that's main idea is to provide a pattern for developing functionalities that dynamically adjust muscle and pin weights, strength and other properties or make kinematic adjustments to the target pose. The most important Puppet Behaviour is the BehaviourPuppet.cs that handles the pinning of Puppets to target animation, releasing those pins in case of collision and re-tightening them when getting up from the ground. The Puppet Behaviours can be switched, for example when the BehaviourPuppet loses balance, it can theoretically switch to BehaviourCatchFall or BehaviourWindmill (both missing from the initial release, but will be developed in the future). The Puppet Behaviours are designed so tha they would not contain a single external object reference. That means they can be simply duplicated and moved to another Puppet.