Ragdoll consists of custom (
MPxLocatorNode) nodes written in C++, but everything involved in connecting these up and generating the dependency network happens in Python. This API is exposed to you for integration with auto-rigging, tools development and to generally just extend the capabilities of the system.
The API is also available on GitHub for issue tracking and user contributions.
There are 3 supported methods of integrating Ragdoll into your pipeline. Each with its own flare.
The publicly facing programming interface to Ragdoll. Use this for tools integrated with other tools that rely on heavy compatibility between versions and few surprises on what goes in and out.
- ✔️ Guaranteed backwards compatibility
- ✔️ High interoperability with
- ✔️ No dependence on user selection or preferences
- ❌ Limited to documented and officially supported features
from maya import cmds from ragdoll import api as rd cube, _ = cmds.polyCube() cmds.move(0, 10, 0) cmds.rotate(35, 50, 30) scene = rd.createScene() rigid = rd.createRigid(cube, scene) cmds.evalDeferred(cmds.play)
api.py module builds on
commands.py, but wraps it in a string-based interface so as to make it compatible with your everyday calls to
api.py is present in
commands.py, along with a few extras that may or may not change over time. It is best suited for tight integration and control but is primarily used internally for implementing
- ✔️ Fast
- ✔️ Flexible
- ✔️ Same guarantees as
api.pyfor identical members
- ❌ Unfamiliar data
commands.pyuses the highly performant
cmdxlibrary to communicate with Maya and all return values are instances of
from maya import cmds from ragdoll import commands as rc from ragdoll.vendor import cmdx cmds.file(new=True, force=True) cube, _ = map(cmdx.encode, cmds.polyCube()) cube["translateY"] = 10 cube["rotate", cmdx.Degrees] = (35, 50, 30) # Every simulation needs a scene scene = rc.create_scene() assert isinstance(scene, cmdx.DagNode) assert scene.type() == "rdScene" # Every scene needs one or more rigid bodies rigid = rc.create_rigid(cube, scene) assert isinstance(rigid, cmdx.DagNode) assert rigid.type() == "rdRigid" # Allow start frame to evaluate before progressing cmds.evalDeferred(cmds.play)
Finally, this module is used for UI elements like the main Ragdoll menu. Every function takes selection into account, along with any preferences set via the Option Dialogs.
It's useful for when you want to replicate what the menu does, including taking selection into account and outputting warning messages in the Script Editor. It won't raise exceptions like
commands, instead each function return either
True for success or nothing for failure. Failures typically follow one or more warning messages.
- ✔️ Animator-friendly, useful for quick scripts
- ❌ No usable return value
- ❌ Sensitive to user preferences
- ❌ No guarantee on backwards compatibility
- ❌ Verbose output in Script Editor
from maya import cmds from ragdoll import interactive as ri cube, _ = cmds.polyCube() cmds.move(0, 10, 0) cmds.rotate(35, 50, 30) cmds.select(cube) ri.create_rigid() cmds.evalDeferred(cmds.play)
Currently available members of
help()for usage instructions
# Fundamentals api.createScene() api.createRigid(node, scene, passive=False, compute_mass=True) # Constraints api.pointConstraint(parent, child, scene) api.orientConstraint(parent, child, scene) api.hingeConstraint(parent, child, scene) api.socketConstraint(parent, child, scene) api.parentConstraint(parent, child, scene) api.convertToPoint(con) api.convertToOrient(con) api.convertToHinge(con, secondary_axis="y") api.convertToSocket(con) api.convertToParent(con) # Controls api.createAbsoluteControl(rigid) api.createRelativeControl(rigid) api.createActiveControl(reference, rigid) api.createKinematicControl(rigid) # Forces api.createForce(type, rigid, scene) api.createSlice(scene) api.assignForce(rigid, force) # Utilities api.transferAttributes(a, b, mirror=True) api.transferRigid(ra, rb) api.transferConstraint(ca, cb, mirror=True) api.editConstraintFrames(con) api.duplicate(rigid)
Gain more control over the integration of Ragdoll into your pipeline with these optional environment variables. For example, to manually load the Ragdoll plug-in and Maya menu, set
RAGDOLL_NO_AUTOLOAD=1 and then call:
import ragdoll.interactive ragdoll.interactive.install()
|RAGDOLL_PLUGIN||Override absolute path to binary plugin, .mll on Windows .so on Linux. This overrides whatever is on
|RAGDOLL_NO_STARTUP_DIALOG||Do not display the startup-dialog on first launch.||
|RAGDOLL_AUTO_SERIAL||Automatically activate Ragdoll on install using this serial number.||Unset|
|RAGDOLL_INSTALL_ON_IDLE||Restore plug-in load behavior pre-2021.04.30||Unset|