Developer Guide (Version 1.11)

Articulated Entity-Specific Functions

Articulated entities consist of linked, rigid bodies called structural units. Each structural unit has a joint that connects it to its parent. For the connection structure, you should use a tree with a single root. Linked loops are not allowed.

Articulated entities can simulate body effects without interactions with the environment by using featherstone mode, which you can tweak so that the entity tolerates strong impacts and so that complex body structures have stiff springs. Articulated entities use a common solver for interactive mode.


You can use pe_params_joint to:

  • Create a joint between two bodies in an articulated entity

  • Change the parameters of an existing articulated entity

  • Query the parameters of an existing articulated entity, when used with GetParams

A joint is created between the two bodies specified in the op parameter at the pivot point (in the entity frame). When a geometry is added to an articulated entity, it uses pe_articgeomparams to specify which body the geometry belongs to (in idbody). idbody can be any unique number and each body can have several geometries. There are no restrictions on the order in which joints are created, but all bodies in an entity must be connected before the simulation starts.

Joints use Euler angles to define rotational limits. Flags that start with angle0_ can be specified individually for each angle by shifting left by the 0-based angle index. For example, to lock the z-axis you can use OR the flags with angle0_locked<<2). The child body inherits the coordinate frame from the first entity (geometry) that was assigned to it.

Joint angular limits are defined in a relative frame between the bodies that the joint connects. Optionally the frame of the child body can be offset by specifying a child's orientation that corresponds to rotation angles (0,0,0), using q0, pMtx0, or pMtx0T. This can help to get limits that can be robustly represented using Euler angles.

A general rule for limits is to set upper and lower bounds at least 15 to 20 degrees apart (depending on simulation settings and the height of the joint's velocity) and to keep the y-axis limit in the -90..90 degrees range (preferably within safe margins from its ends).


All angles are defined in radians in the parameter structure.

pe_params_joint uses 3D vectors to represent groups of three values that define properties for each angle. In addition to limits, each angle can have a spring that will pull the angle to 0 and a dashpot that will dampen the movement as the angle approaches its limit. Springs are specified in acceleration terms: stiffness and damping can stay the same for joints that connect bodies with different masses, and damping can be computed automatically to yield a critically damped spring by specifying auto_kd for the corresponding angle.

joint_no_gravity makes the joint unaffected by gravity, which is useful if you assume forces that hold the joint in its default position are enough to counter gravity). This flag is supported in featherstone mode.

joint_isolated_accelerations makes the joint use a special mode that treats springs like guidelines for acceleration, which is recommended for simulating effects on a skeleton. This flag is supported in featherstone mode.

Effective joint angles are always the sum of q and qext. If springs are activated, they attempt to drive q to 0. The allows you to set a pose from animation and then apply physical effects relative to it. In articulated entities, collisions are only checked for pairs that are explicitly specified in pSelfCollidingParts (this setting is per body or per joint, rather than per part).


pe_params_articulated_body allows you to set and query articulated entity simulation mode parameters. Articulated entities can be attached to something or be free, and are set by the bGrounded flag. When grounded, the entity can:

  • Fetch dynamic parameters from the entity it is attached to (if bInreritVel is set; the entity is specified in pHost)

  • Be set using the a, wa, w and v parameters

bCollisionResp switches between featherstone mode (0) and constraint mode (1).

bCheckCollisions turns collision detection on and off. It is supported in constraint mode.

iSimType specifies a simulation type, which defines the way in which bodies that comprise the entity evolve. Valid values:

  • 0 – joint pivots are enforced by projecting the movement of child bodies to a set of constrained directions |

  • 1 – bodies evolve independently and rely on the solver to enforce the joints. The second mode is not supported in featherstone mode. In constraint mode, it is turned on automatically if bodies are moving fast enough.

    We recommend setting this value to 1 to make slow motion smoother.

Lying mode

Articulated entities support a lying mode that is enabled when the number of contacts is greater than a specified threshold (nCollLyingMode). Lying mode has a separate set of simulation parameters, such as gravity and damping. This feature was designed for ragdolls to help simulate the high damping of a human body in a simple way, for example by setting gravity to a lower value and damping to a higher than usual value.

Standard simulation versus freefall parameters

Standard simulation parameters can be different from freefall parameters. When using the constraint mode, articulated entities can attempt to represent hinge joints (rotational joints with only axis enabled) as two point-to-point constraints by setting the bExpandHinges parameter (this value propagates to joint_expand_hinge flags for all joints, so you do not need to manually set the value for joints).