Skip to content

Import Physics

Import physics onto existing controllers from disk.


From the Ragdoll menu, select the Import Physics option in the Animation sub-menu.



Import onto Selected Character


Import onto the Ragcar


Import Physics

Animators can now setup physics one character, export it, and then import onto another.

The usecase is having spent time setting up a perfect ragdoll and then wanting to reuse this setup across multiple scenes, on multiple instances of the same referenced character, or on characters with similar naming scheme and anatomy. It can also be used to import parts of a character or individual objects.


Here's an 18 second run-down of the complete workflow, from authoring to import.



Anything you can apply physics to can be exported.

The nodes onto which physics is imported..

  • ✔️ Can have a different namespace
  • ✔️ Can have a different naming convention
  • ✔️ Can have a different pose
  • ✔️ Can have a different scale
  • ✔️ Can be animated
  • ✔️ Can be referenced
  • ✔️ Can be imported in pieces, based on what is currently selected

It will remember..

  • ✔️ All edited attributes, like Guide Strength
  • ✔️ All edited constraints, like their limits and frames

It will not remember..

  • ❌ The vertices of the Mesh shape type (not part of the exported file)
  • ❌ Controls (i.e. Soft Pin, Hard Pin and Mimic)
About those 'Convex Hulls'..

Convex hulls, those triangulated versions of your Maya shapes - the Mesh shape type - are re-generated onto whatever character you import onto. This is probably what you want, and enables you to apply physics onto characters with different geometry from when you originally authored the physics. Although sometimes it's not, which is why this we be augmented in a future release.

And that's about it! It doesn't even have to be a "character", any combination of Maya nodes you can apply physics to can have their physics exported. Like a (rag)car, or just a (rag)box.

User Interface

Use the UI to visualise the contents of an exported .rag file and customise the import.

The UI resembles native Maya and Ragdoll option dialogs, with two interesting bits.

1. File Browser

The top part displays other Ragdoll scene (.rag) files in the same directory as the selected file, along with the thumbnail stored during the time of export. The thumbnail currently isn't visible during export, it is captured from the currently active viewport. An Export UI with thumbnail preview (and more!) will be added in a future release.

2. Content Preview

This sections shows you the contents of the physics scene, ahead of actually importing it.

It will visualise a number of things.

  1. Which Maya nodes will be "physicalised"?
  2. Which nodes present during export are not present in the currently opened scene?
  3. What was the original path of a node during export?
  4. What is the destination path of the node being imported?
  5. Is there a destination node?
  6. Is the destination already physicalised?
  7. What was the original node icon, e.g. nurbsCurve or mesh?
  8. What is the Shape Type of the exported rigid, e.g Capsule?


The export-format is identical to what game developers use to author physics in Maya and import it into their game engine. It contains all data managed by Ragdoll, in full detail. Enough detail to reverse-engineer it back into a Maya scene, which is exactly what's going on here.

Example Files

It means some information is lost, in particular any custom connections made or custom attributes added or removed. It will use the same menu items you used to author a ragdoll, and nothing else. So things not possible with those commands will not be captured in the exported file format.


Each export captures the currently active 3d viewport for use as a thumbnail. So, whenever you export, remember to smile and wave! :D


Context Sensitive

The visualisations will update as you select different nodes and edit the various options in the UI.

To illustrate this, let's import onto the same scene we exported.


Only one character is physicalised and exported.



Notice that importing is not possible, since the character is already physicalised. Unless we replace the namespace, by selecting another character.


Use Selection

Import onto selected nodes with Use Selection toggled (it's the default).


Search and Replace

Every node is stored along with its full path, such as..


And in most cases can get quite long, with one or more namespaces and tens to hundreds of levels deep in hierarchy.


Here, the namespace is simply _:

The Search and Replace boxes of the UI can be used to replace parts of each path, to try and map the original path to whatever path is currently available in the scene.


Auto Namespace

One challenge with export/import it remapping names from the original scene onto your new scene. Ragdoll solves the typical case of only the namespace being different with "Auto Namespace".


"Auto Namespace" will replace any namespace in the original file with whatever namespace is currently selected. Neat! If there are multiple namespaces, it'll use the last namespace.

Auto Scene

Locate and use the original physics scene from the original file, so as to preserve your multi-scene setups.

For example, if your one character has 3 physics scenes - one for the right arm, one for the left and a single one for both legs - then "Auto Scene" will preserve these scenes for you.

Performance Tip

Using more than one scene can improve performance significantly, as Ragdoll will parallelise each invidual scene. The caveat is that rigids in different scenes cannot interact with each other.

Ragdoll Clean

Here's a quick way you can use this feature to "clean" a physics scene.

  1. Export
  2. Delete All
  3. Import

The resulting scene will be "clean" in that it will have been broken down into its componens and reassembled again, not taking into account anything Ragdoll doesn't know about.


(I may just add a menu item for this, called Clean to do this in one go :)

Import Python API

Anything the UI can do can be done via Python, using the new dump.Loader object.

from ragdoll import dump
loader = dump.Loader()"c:\path\to\myRagdoll.rag")

# Search and replace these terms from the full node path
# E.g. |root_grp|arm_left -> |root_grp|arm_right
    ("_left", "_right"),
    ("_ik", "_fk"),

# An automatic method of search-and-replace, that replaces
# any namespaces found in the file with this.
# E.g. |char1:root_grp -> |char2:root_grp

# Limit imported nodes to those with an absolute path 
# starting with *any* of these

# Deconstruct the provided `.rag` file
# (This is what is visualised in the UI)
# (The exact layout of this data may change)
analysis = loader.analyse()
assert isinstance(analysis, dict)

# Print a brief human-readable summary of the current analysis

# Actually apply the contained physics in this file
# "Re-interpret" means it will attempt to call the same command
# as you did when creating the file, like `Active Chain` and
# any constraints, in the same order (where possible).

Heads up

Consider this a version 0.1 of the API, it will likely change in the future.

Last update: 2021-08-08