The BehaviourPuppet handles pinning and unpinning puppets when they collide with objects or are hit via code, also automates getting up from an unbalanced state.

Getting Started

• Copy the entire gameobject of the BehaviourPuppet from the demo character in "Melee" scene to your own Puppet (parent to the Behaviours root).
• Collision resistance depends on many things, also the mass of your Rigidbodies, if the Puppet is too easy or difficult to unbalance, tweak the "Collision Resistance" value first.

Troubleshooting

• The Puppet never falls over, has "snake feet" - decrease "Collision Resistance".
• The Puppet loses balance on slightest contact - increase "Collision Resistance" and/or "Regain Pin Speed". Increase "Knock Out Distance".
• The Puppet tries to get up, but repeatedly fails - increase "Get Up Collision Resistance" and/or "Get Up Regain Pin Speed Mlp" and/or "Get Up Knock Out Distance".
• The Puppet's muscles are too stiff when unbalanced - decrease "Unpinned Muscle Weight Mlp".
• The Puppet doesn't lose balance when hit hard to the legs - find the group override for the "Hips" and "Leg" and the "Foot" group. Increasing "Unping Parents", "Unpin Children" and "Unpin Group" makes the collisions propagate more heavily to the other body parts. Also try decreasing "Knock Out Distance".

Collision And Recovery

• normalMode - how does the puppet behave when currently not in contact with anything? Active mode keeps the PuppetMaster Active and mapped at all times. Unmapped blends out mapping to maintain 100% animation quality. Kenamatic keeps the PuppetMaster in Kinematic mode until there is a collision.
• mappingBlendSpeed - the speed of blending in mapping in case of contact when in Unmapped normal mode.
• activateOnStaticCollisions - if false, static colliders will not activate the puppet when they collide with the muscles. Note that the static colliders need to have a kinematic Rigidbody attached for this to work. Used only in Kinematic normal mode.
• activateOnImpulse - minimum collision impulse for activating the puppet. Used only in Kinematic normal mode.
• groundLayers - the layers that the character controller will be grounded to when unpinned or getting up.
• collisionLayers - the layers that will unpin the Puppet on collision.
• collisionThreshold - an optimization. The minimum square magnitude of the impulse that will be processed.
• collisionResistance - smaller value means more unpinning from collisions so the characters get knocked out more easily. If using a curve, the value will be evaluated by each muscle's target velocity magnitude. This can be used to make collision resistance higher while the character moves or animates faster.
• collisionResistanceMultipliers - used for multiplying the value of collision resistance based on the layer that collided with the Puppet.
• maxCollisions - and optimization. The maximum number of collisions that will be processed per physics step. Helps to avoid peaks.
• regainPinSpeed - how fast will the muscles of this group regain their pin weight?
• muscleRelativeToPinWeight - Muscle weight multiplier relative to pin weight. It can be used to make muscles weaker/stronger when they are more/less unpinned while in the normal Puppet state.
• boostFalloff - Boosting is a term used for making muscles temporarily immune to collisions and/or deal more damage to the muscles of other characters. That is done by increasing Muscle.State.immunity and Muscle.State.impulseMlp. For example when you set muscle.state.immunity to 1, boostFalloff will determine how fast this value will fall back to normal (0). Use BehaviourPuppet.BoostImmunity() and BehaviourPuppet.BoostImpulseMlp() for boosting from your own scripts. It is helpful for making the puppet stronger and deliever more punch while playing a melee hitting/kicking animation.

Muscle Group Properties

• defaults - the default muscle properties. If there are no 'Group Overrides', this will be used for all muscles.
  unpinParents - how much will collisions with muscles of this group unpin parent muscles?
  unpinChildren - how much will collisions with muscles of this group unpin child muscles?
  unpinGroup - how much will collisions with muscles of this group unpin muscles of the same group?
  minMappingWeight - if 1, muscles of this group will always be mapped to the ragdoll.
  maxMappingWeight - if 0, muscles of this group will not be mapped to the ragdoll pose even if they are unpinned.
  disableColliders - if true, muscles of this group will have their colliders disabled while in puppet state (not unbalanced nor getting up).
  regainPinSpeed - how fast will muscles of this group regain their pin weight (multiplier)?
  collisionResistance - smaller value means more unpinning from collisions (multiplier).
  knockOutDistance - if the distance from the muscle to its target is larger than this value, the character will be knocked out.
  puppetMaterial - the PhysicsMaterial applied to the muscles while the character is in Puppet or GetUp state. Using a lower friction material reduces the risk of muscles getting stuck and pulled out of their joints.
  unpinnedMaterial - the PhysicsMaterial applied to the muscles while the character is in Unpinned state.
• groupOverrides - overriding default muscle properties for some muscle groups (for example making the feet stiffer or the hands looser).

Losing Balance

• knockOutDistance - if the distance from the muscle to its target is larger than this value, the character will be knocked out.
• unpinnedMuscleWeightMlp - smaller value makes the muscles weaker when the puppet is knocked out.
• dropProps - if true, all muscles of the 'Prop' group will be detached from the puppet when it loses balance.

Getting Up

• canGetUp - if true, GetUp state will be triggerred automatically after 'Get Up Delay' and when the velocity of the hip muscle is less than 'Max Get Up Velocity'.
• getUpDelay - minimum delay for getting up after loosing balance. After that time has passed, will wait for the velocity of the hip muscle to come down below 'Max Get Up Velocity' and then switch to the GetUp state.
• blendToAnimationTime - the duration of blending the animation target from the ragdoll pose to the getting up animation once the GetUp state has been triggered.
• maxGetUpVelocity - will not get up before the velocity of the hip muscle has come down to this value.
• minGetUpDuration - will not get up before this amount of time has passed since loosing balance.
• getUpCollisionResistanceMlp - collision resistance multiplier while in the GetUp state. Increasing this will prevent the character from loosing balance again immediatelly after going from Unpinned to GetUp state.
• getUpRegainPinSpeedMlp - regain pin weight speed multiplier while in the GetUp state. Increasing this will prevent the character from loosing balance again immediatelly after going from Unpinned to GetUp state.
• getUpKnockOutDistanceMlp - knock out distance multiplier while in the GetUp state. Increasing this will prevent the character from loosing balance again immediatelly after going from Unpinned to GetUp state.
• getUpOffsetProne - offset of the target character (in character rotation space) from the hip bone when initiating getting up animation from a prone pose. Tweak this value if your character slides a bit when starting to get up.
• getUpOffsetSupine - offset of the target character (in character rotation space) from the hip bone when initiating getting up animation from a supine pose. Tweak this value if your character slides a bit when starting to get up.

Events

• onGetUpProne - called when the character starts getting up from a prone pose (facing down).
• onGetUpSupine - called when the character starts getting up from a supine pose (facing up).
• onLoseBalance - called when the character is knocked out (loses balance). Doesn't matter from which state.
• onLoseBalanceFromPuppet - called when the character is knocked out (loses balance) only from the normal Puppet state.
• onLoseBalanceFromGetUp - called when the character is knocked out (loses balance) only from the GetUp state.
• onRegainBalance - called when the character has fully recovered and switched to the Puppet state.