Skip to content

Node Reference

Detailed information about all of Ragdoll's custom nodes along with the most commonly used attributes. For full attribute reference, see the link at the bottom of each node type, such as rdRigid.

Each Ragdoll node starts with rd, e.g. rdRigid


Scene

Container of all rigids, constraints and forces that interact.

The scene represents the knowledge each simulation has, including rigids and their properties, constraints, forces. The works. There can be more than one Ragdoll scene in your Maya scene, but much like Maya scenes they cannot interact. The order in which scenes are simulated is also undefined, so you cannot expect e.g. fingers in one solver to run after the body in another solver.

Parallelism

Ragdoll scenes support both scene-level parallelism and node-level parallelism.

Scene-level parallelism happens when there are more than one Ragdoll scene present, each scene is then run in parallel for improved performance. For that reason, prefer using as many scenes as possible, especially if they are unlikely to interact.

Node-level Parallelism happens internally, whereby a single simulation is distributed over multiple threads. The behavior can be tuned via the rdScene.threadCount attribute. Keep this at 0 when your scenes are small, i.e. < 100 rigids. The overhead of splitting up a simulation outweighs the benefit unless there is a lot to split. You should notice a performance difference in either direction as you manipulate this attribute.


image

Attribute Description Type
.airDensity Global multiplier to the linearDamping and angularDamping of every rigid part of this scene. This is a convenience attribute to the same attribute found in the rdRigid node for global effects, like the whole scene turning into honey. float
.currentTime Ragdoll's knowledge of time. This is typically connected automatically and needn't be touched, but it is technically possible to animate this and achieve complex slow-motion or time-related effects. time
.enabled State of the solver. An enabled solver will update whenever time changes. bool
.gravity Default gravity, in Maya's current distance unit (typically centimeters). Because native Maya shapes are generally quite small - e.g. 1 centimeter for a polyCube - the default gravity is less than the realistic 986.0 cm/s2. If your characters are real-world scaled - e.g. 2 meters tall - then gravity should be closer to 986.0 instead. distance3
.groundFriction Friction of the ground. float
.groundRestitution Bounciness of the ground plane. float
.substeps Divide changes in time by this many. Ragdoll simulates once per frame (or generally once per change in time, including sub-frame changes), but multiples the number of steps taken by this amount for greater accuracy at a (possible) cost to performance. int
.useGround Automatically add a static ground shape to this scene. This has a very similar effect to making your own plane and turning that into a Passive Rigid. The ground responds to changes in translation of the scene, but cannot be animated. bool


Rigid

A single transform in or out of Ragdoll.

The rigid is the physical equivalent of native Maya geometry. It can either feed into the simulation (passive) or come out of the simulation (active).

  • Active Rigid pass data from Ragdoll to Maya
  • Passive Rigid pass data from Maya to Ragdoll


image

Attribute Description Type
.airDensity Multiplier of both linearDamping and angularDamping. The two damping attributes are typically used together, but can also be used separately in which case this attribute could be left at 1.0 and forgotten. float
.angularDamping Resistance along the opposite direction of rotation for a rigid. Like linearDamping but along the rotation axes. float
.collide Whether this rigid should collide with other rigids. This can be useful in areas of many overlapping rigids that aren't necessarily constrained, such as a shoulder or hip. bool
.friction The resistance at which two rigids rub against each other. A value of 0 creates an appearance of ice, whereas a value of 1.0 represents 100% friction, no sliding allowed. The value may exceed 1.0, but it is unclear what happens. Use at your own risk. float
.inputMatrix Passive position and orientation, this may be animated. matrix
.inputParentInverseMatrix Used to cancel out any Maya parent prior to outputting the outputMatrix. matrix
.kinematic Whether this rigid should be affected by contacts, constraints and forces. bool
.linearDamping Resistance in the opposite direction of travel for a rigid. This creates an underwater look, or at high-enough values resembles honey or eventually cement. float
.mass The 'weight' of a rigid. Except 'weight' is technically the result of mass and gravity, and a rigid still has mass even when there isn't any gravity. This attribute is mostly relevant when two active rigids interact, think of a pool table where one of the balls is heavier than another. On the other hand, dropping a feather from high on up onto a static ground yields an identical result to dropping much heavier bowling ball. The ground being static will not move regardless and the speed at which your rigid falls to the ground is independent of its mass given there is no actual air in the simulation to apply counterforce like in the real world. float
.restitution The 'bounciness' of a rigid body. Bounce is an opposite force applied whenever two rigids come into contact. The bounce is however also dependent on the rdScene.bounceThresholdVelocity which determines how strong a contact must be in order for an opposing force to be added. Without a threshold, a rigid would bounce at increasingly small intervals into infinity. However, for high-frequency bounces, like a billiard ball bouncing on a marble floor, don't forget to increase your substeps so as to capture the very small and fast motion happening towards the end of its bounce lifetime. float
.shapeExtents The dimensions of the 'Box' shapeType. float3
.shapeLength Length of the 'Capsule' and 'Cylinder' shapeType. float
.shapeOffset Position of a shape relative the rigid. Think of the shape as being a child of the rigid, and this is its child position. It'll be in the orientation of the parent, as you would expect. double3
.shapeRadius Radius of the 'Sphere', 'Capsule' and 'Cylinder' shapeType. float
.shapeType Shape used for collision detection and automatic computation of centerOfMass and angularMass. The 'Mesh' option converts any input to inputMesh or inputCurve to a suitable physical representation called 'Convex Hull'. As the name implies, the hull cannot be concave. To model concave shapes, like a torus, use multiple rigids and parent them together to form a compound shape. enum
.thickness Additional offset from the surface of a shape. Think of this as the shape being extruded by this amount along the surface normals. It's meant to create some padding between two rigids that collide and can help stabilise complex or strong contacts. float


Constraint

A relationship between two rigids.

Typically this relationship is something to limit one or more axes - e.g. translateXYZ and rotateZ - of one rigid relative another rigid, like a door "constrained" to a wall. In that case, the wall would be considered a "parent" and the door a "child".

However it is important to keep in mind that in the real world, there is no such thing. The door is as constrained to the wall as the wall is constrained to the door. This is especially apparent when the two constrained rigids are both active and have a similar mass, such as your upper and lower leg. As you bend your knee, both the thigh and lower leg are affected equally.


image

Attribute Description Type
.angularDriveDamping Angular damping of the drive. float
.angularDriveStiffness Angular stiffness of the drive. float
.angularLimitDamping Damping of contacts with the limit. It is an opposing force to whatever direction a contact is applied. A low value produces a springy appearance, whereas a high value resists any and all motion. float
.angularLimitStiffness Stiffness of contacts with the angular limit. A low value makes limits appear soft. Values are relative the mass of your rigid and the amount of force being applied by contacts and other constraints. But with a mass of 1.0 and under normal gravity, the default value should produce a somewhat hard response. float
.driveEnabled Whether or not to try and follow the driveMatrix attribute. Drives (a.k.a. Guides) are used to follow an input animation by applying forces relative the delta between your animation and the simulation. The further your animation is from the current state of the simulation, the stronger the force. It's a spring-like force. bool
.driveMatrix A target position and orientation for the childRigid, relative the parentFrame. The constraint can apply a spring-like force to both parent and child to try and match this matrix as though the childRigid was an actual child of the parentRigid. matrix
.driveStrength Multipler to linearDriveStiffness, linearDriveDamping, angularDriveStiffness and angularDriveDamping. This is a convenience attribute to simplify manipulation (and animation) of the overall drive behaviour. The same result can be achieved by manually multiplying these values. The equation is strength * strength * stiffness and the same for damping. float
.limitEnabled Whether any of the specified limits are enabled or not. Think of this as a convenience override for linear (position) and angular (rotation) limits. You can achieve the same effect by setting each limit to a value of 0. bool
.limitStrength Multiplier for the linearLimitStiffness, linearLimitDamping, angularLimitStiffness and angularLimitDamping attributes. float
.linearDriveDamping Linear damping of the drive. A high value produces a slimy, slow-moving motion. float
.linearDriveStiffness Linear stiffness of the drive. If you think of the drive as a spring, then the stiffness determines the thickness of the coil of that spring. A thick coil yields a fast, springy motion. float
.linearLimitDamping Damping factor for contacts with the limit. float
.linearLimitStiffness Stiffness of contacts with linear limit. Whenever the linear limit is hit, this attribute determines how soft/hard to response should be. A low value (e.g. 10) yields a soft appearance, whereas a high (e.g. 1'000'000) yields a metal-versus-marble contact. float


Control

A placeholder for drawing a rigid under a different transform.

This node is cosmetic only. It helps you spot the rigid and rigid orientation in the viewport for a standalone controller, like a Guide. It also draws the node with a special icon in the outliner. But that's about it!



Constraint Multiplier

Multiply one or more attributes of one or more constraints.

This node enables you to animate one attribute that affect many attributes, like Translate Guide Stiffness across an entire character or limb.


Attribute Description Type
.angularDriveDamping Multiplier for rdConstraint.angularDriveDamping float
.angularDriveStiffness Multiplier for rdConstraint.angularDriveStiffness float
.angularLimitDamping Multiplier for rdConstraint.angularLimitDamping float
.angularLimitStiffness Multiplier for rdConstraint.angularLimitStiffness float
.driveStrength Multiplier for rdConstraint.driveStrength float
.limitStrength Multiplier for rdConstraint.limitStrength float
.linearDriveDamping Multiplier for rdConstraint.linearDriveDamping float
.linearDriveStiffness Multiplier for rdConstraint.linearDriveStiffness float
.linearLimitDamping Multiplier for rdConstraint.linearLimitDamping float
.linearLimitStiffness Multiplier for rdConstraint.linearLimitStiffness float


Rigid Multiplier

Multiply one or more attributes of one or more rigids.

This node enables you to animate one attribute that affect many attributes, like Air Density across an entire character or limb.


Attribute Description Type
.airDensity Multiplier for rdRigid.airDensity float
.angularDamping Multiplier for rdRigid.angularDamping float
.linearDamping Multiplier for rdRigid.linearDamping float


Other

Notes on general concepts used in Ragdoll.


Backwards Compatibility

  • Default values never change, those written into the node type itself
  • Initial values may change, those set during node-creation

This means previously authored scenes will always behave the same, whilst still enabling new default values for future versions and future authored physics.


Exclusive Nodes

Ragdoll consists of a few new native types, like rdRigid and rdConstraint. During creation, Ragdoll may generate Maya-native types too, like multMatrix and composeMatrix. Those nodes are exclusive to Ragdoll and should be removed alongside them. This is managed via the so-called .exclusiveNodes attribute on each Ragdoll node type.


User Attributes

Whenever Ragdoll attributes appear on your original animation controls, they are referred to as "user attributes" by Ragdoll and tracked via the .userAttributes attribute on each Ragdoll node. These attributes are exclusive to Ragdoll and are removed alongside the Ragdoll node types they interact with.


Last update: 2021-03-28