+info re KineticRagdollControl & DynamicAnimControl (#94)

* +info re KineticRagdollControl & DynamicAnimControl

* correct name of SkinningControl

src/docs/asciidoc/jme3/advanced/ragdoll.adoc

@@ -14,11 +14,9 @@ The jMonkeyEngine3 has built-in support for link:http://jbullet.advel.cz[jBullet
 image::jme3/advanced/ragdoll.png[ragdoll.png,width="",height="",align="center"]
 
 
-
 == Sample Code
 
 *  link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/bullet/TestRagDoll.java[TestRagDoll.java] (Tip: Click to pull the ragdoll up)
-*  link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/bullet/TestBoneRagdoll.java[TestBoneRagdoll.java] – This ragdoll replaces a rigged model of a character in the moment it is “shot to simulate a collapsing person. (Also note DoF of the limbs.)
 
 
 == Preparing the Physics Game
@@ -175,3 +173,87 @@ Read the <<jme3/advanced/physics#responding_to_a_physicscollisionevent,Respondin
 == Best Practices
 
 If you experience weird behaviour in a ragdoll – such as exploding into pieces and then reassembling – check your collision shapes. Verify you did not position the limbs too close to one another when assmebling the ragdoll. You typically see physical nodes being ejected when their collision shapes intersect, which puts physics in an impossible state.
+
+
+== Ragdoll Physics using KinematicRagdollControl (deprecated as of JMonkeyEngine v3.3)
+
+KinematicRagdollControl is an unfinished work in progress.  The intent was to automate the creation of limbs and joints for ragdoll physics.  The idea was to create a control,
+
+[source,java]
+----
+ragdoll = new KinematicRagdollControl(0.5f);
+----
+
+and add it to a rigged model and also to physics space:
+
+[source,java]
+----
+model.addControl(ragdoll);
+getPhysicsSpace().add(ragdoll);
+----
+
+A rigid body and a physics joint would be created automatically for each bone in the skeleton, or alternatively just for the bones specified by invoking the addBoneName() method.  As long as the control was in kinematic mode, the physics objects would mimic the motion of the bones, including skeletal animations and rotation/translation of the model.  When it was time to simulate a ragdoll, you would invoke
+
+[source,java]
+----
+ragdoll.setRagdollMode();
+----
+
+and thereafter physical forces would override any skeletal animation.
+
+=== Sample Code
+
+*  https://github.com/jMonkeyEngine/jmonkeyengine/blob/v3.2/jme3-examples/src/main/java/jme3test/bullet/TestRagdollCharacter.java[v3.2-branch TestRagdollCharacter.java]  In this example, the control remains in kinematic mode.  Hold down the "U" key to advance the model toward the wall.  Press the spacebar to play the "Slice" animation.  When the model comes into contact with the wall, the blocks will tumble.
+
+*  https://github.com/jMonkeyEngine/jmonkeyengine/blob/v3.2/jme3-examples/src/main/java/jme3test/bullet/TestBoneRagdoll.java[v3.2-branch TestBoneRagdoll.java]  Press the left mouse button to shoot a cannonball at the model.  Ragdoll physics starts when a cannonball touches the model.  Press the spacebar to resume kinematic mode and cause the model to rise to his feet. 
+
+
+== Ragdoll Physics using DynamicAnimControl (JME 3.3 and later)
+
+DynamicAnimControl is a replacement for KinematicRagdollControl.  The intent is similar, except that a DynamicAnimControl can be simultaneously kinematic for some bones and dynamic for others.  Also, DynamicAnimControl can be configured to work with a wider variety of models than KinematicRagdollControl.
+
+To simplify the implementation, the ragdoll created by a DynamicAnimControl is composed of "links".  Just as a RigidBodyControl connects a rigid body to a spatial, a link connects a rigid body to one or more bones in the model's skeleton.  Just like a RigidBodyControl, a link can be in kinematic mode or dynamic mode.
+
+And just as the bones in a skeleton are arranged in parent/child hierarchy, so are the links in a DynamicAnimControl ragdoll.  In the ragdoll hierarchy, there is exactly one link that has no parent; it is referred to as the "torso".  Every other link is a "bone link" which has another link as its parent.  Each bone link is connected to its parent by a physics joint.
+
+As with KinematicRagdollControl, you start by creating a control,
+
+[source,java]
+----
+ragdoll = new DynamicAnimControl();
+----
+
+but before adding it to the model, you must configure it by specifying the mass of the torso and also the mass and range of motion for each linked bone:
+
+[source,java]
+----
+ragdoll.setMass(DacConfiguration.torsoName, 1f);
+ragdoll.link("Waist", 1f, new RangeOfMotion(1f, -0.4f, 0.8f, -0.8f, 0.4f, -0.4f));
+...
+----
+
+You probably don't want to link every bone in the model's skeleton.  For instance, if the model has articulated fingers, you probably want to link the hand bones but not the individual finger bones.  Unlinked bones will be managed by their nearest linked ancestor, and the torso will manage any bones for which no ancestor is linked.  If you link too many bones, the ragdoll may become inflexible or jittery due to collisions between rigid bodies that don't share a physics joint.
+
+Only after the control is configured should you add it to the model and to physics space:
+
+[source,java]
+----
+model.addControl(ragdoll);
+getPhysicsSpace().add(ragdoll);
+----
+
+Note that the control must be added to the Spatial with the SkinningControl, which isn't necessarily the model's root spatial.
+
+As long as a link is in kinematic mode, its physics objects will mimic the motion of the bones, including skeletal animations.  When it's time to simulate a ragdoll, you can invoke
+
+[source,java]
+----
+ragdoll.setRagdollMode();
+----
+
+to put all links into dynamic mode.  Thereafter, physical forces will override any skeletal animation.
+
+=== Sample Code
+
+*  link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/bullet/TestBoneRagdoll.java[master-branch TestBoneRagdoll.java]  Press the left mouse button to shoot a cannonball at the model.  Ragdoll physics starts when a cannonball touches the model.  Press the spacebar to resume kinematic mode and cause the model to rise to his feet. 
+