Maya Plugin

Command line and scripting

Install, simulate and render from a terminal with mayapy and Render, build Deformable scenes with Python scripts, every Deformable action as a Python function, the runtime commands and their flags, and fracture points for particles.

On this page

Everything in the Deformable menus is a Python function you can call from a script, and Maya can simulate and render a scene without opening its window. This page is for pipeline work: render farms, batch jobs and scene-building scripts.

The examples call mayapy and Render by name. They are in Maya’s bin folder:

System Folder
macOS /Applications/Autodesk/maya2027/Maya.app/Contents/bin
Linux /usr/autodesk/maya2027/bin
Windows C:\Program Files\Autodesk\Maya2027\bin

Install from a terminal

Unzip the plugin into a modules folder, as Install the plugin shows, and Maya, mayapy and Render find it there. A scene file that holds Deformable nodes loads the plugin when it opens. A script that builds a scene loads it with cmds.loadPlugin("deformable").

On a render farm, unzip it into a shared folder and point Maya at it with the MAYA_MODULE_PATH environment variable, which lists the folders that hold .mod files:

sh
export MAYA_MODULE_PATH=/studio/maya/modules

Restart Maya after you install a new version: a running Maya keeps the plugin it loaded.

Render from a terminal

Maya’s Render command renders a scene file without opening Maya’s window. Give it the full path of the file. The plugin simulates each frame as the render reaches it, and a baked scene renders its bake:

sh
Render -r arnold -s 1 -e 48 /projects/shot/shot.ma

Render the whole range from the start frame. The Deformable Scene’s Start Frame is an attribute of the scene, so -s does not move it: a render that starts after the start frame renders a scene that is not baked at rest. To render frames 10 to 48 of a simulation that starts at frame 1, bake it and save the file first. The render then reads those frames from the bake. See Bake Simulation.

The plugin prints what it does, each line starting with Deformable:, so a render log shows it:

Line When
Deformable: deformableScene1: frame 12 of 48 in 2.41 s · deformableScene1 step 2.30 s, mean 2.35 s A frame was simulated, in that many seconds. Each Deformable Scene that stepped follows, with how long its step took and the mean step since the start frame.
Deformable: deformableScene1: 47 frames simulated in 113.20 s The simulation reached the end of the playback range.
Deformable: deformableScene1: Frame 10 renders pCube1 without the simulation: render from frame 1, or bake first The render starts where the simulation cannot reach, and the named objects are not baked.
Deformable: deformableScene1: The bake no longer matches the scene: bake again or free it The scene changed after its bake, or the bake folder is missing, so the scene simulates instead.
Deformable: pSphere1: Deformable Tetrahedralize: <message> A node shows a new error or warning.
Deformable: deformableScene1: <message> The scene says something new, such as Play from the start frame. See Troubleshooting.
Deformable: deformableScene1: Left out of the simulation: Bolt (its tetrahedrons are too small). See Troubleshooting. Play left the named objects out and simulates the others. See An object stays still at Play.

A message is printed when it appears, not again on each frame.

Simulate from a terminal

mayapy is Maya’s Python: it runs a script with Maya and the plugin, without a window. This command opens a file and plays every frame from the start frame to the end of the playback range, as Simulate Frame Range does:

sh
mayapy -c "import maya.standalone; maya.standalone.initialize(); from maya import cmds; cmds.file('/projects/shot/shot.ma', open=True); from deformable_maya import commands; commands.run('deformableSimulateFrameRange')"

The frame cache lives only in memory, so this command saves nothing. Use it to time a simulation, or to check that a file simulates on a render node before you render it. It prints a line for each frame, with about how long the frames left take, and one for the whole range:

text
Deformable: deformableScene1: frame 1 of 48 in 0.04 s · less than a minute left
Deformable: deformableScene1: frame 2 of 48 in 2.61 s · about 1 min left
…
Deformable: deformableScene1: frame 48 of 48 in 2.38 s
Deformable: deformableScene1: Simulated frames 1–48 in 1 min 55 s

It stops where a scene says something that stops the simulation, and prints where and why, such as Deformable: deformableScene1: Stopped at frame 1: No Deformable Scene: choose Deformable Scene > Create Scene. Advice, such as objects that no Deformable Scene takes, is printed and the range goes on.

To keep the frames, bake instead: commands.run('deformableBakeSimulation'), then save the file with cmds.file(save=True).

Build a scene with a script

This script builds the scene of Getting started: a brick sphere that falls onto a floor. It sets one scene setting, saves the file, bakes 48 frames beside it, and prints what the sphere looks like at the end. Save it as drop_sphere.py and run it with mayapy drop_sphere.py:

python
import os

import maya.standalone

maya.standalone.initialize(name="python")

from maya import cmds

cmds.loadPlugin("deformable")

from deformable_maya import commands

# A new scene, 48 frames long.
cmds.file(new=True, force=True)
cmds.playbackOptions(minTime=1, maxTime=48)

# A sphere 3 units up, in an autocage, made of brick. The first create action adds the Deformable Scene.
sphere = cmds.polySphere(name="ball")[0]
cmds.setAttr(sphere + ".translateY", 3)
cmds.select(sphere)
commands.run("deformableCreateObjectWithAutocage")
commands.run("deformableAssignMaterialPreset", preset="brick")

# A floor 20 units wide, extruded 0.2 down, that does not move, rendered with the plane's shading.
floor = cmds.polyPlane(name="floor", width=20, height=20, subdivisionsWidth=1, subdivisionsHeight=1)[0]
cmds.select(floor)
commands.run("deformableCreateBareObject", source="nonClosedPolygonMesh", thickness=0.2, direction="down")
commands.run("deformableUseTetrahedralMeshAsSurfaceMesh")
commands.run("deformableSetType", type="kinematic")

# Ten substeps a frame, on the scene's shape.
cmds.setAttr("deformableSceneShape1.substeps", 10)

# Save, then bake every frame into the folder beside the file, and save the bake's record.
cmds.file(rename=os.path.abspath("drop_sphere.ma"))
cmds.file(save=True, type="mayaAscii")
commands.run("deformableBakeSimulation")
cmds.file(save=True)

cmds.currentTime(48)
cmds.getAttr("deformableSceneShape1.simulatedFrame")
lowest = cmds.exactWorldBoundingBox("ball_surfaceMesh")[1]
print(f"Frame 48: lowest point {lowest:.2f}, {cmds.polyEvaluate('ball_surfaceMesh', face=True)} faces")

maya.standalone.uninitialize()

After the plugin’s lines, it prints a line such as this one. The sphere lies broken on the floor, and its surface has gained the faces of the cracks:

text
Frame 48: lowest point -0.02, 3788 faces

The file drop_sphere.ma and its folder deformable_cache_drop_sphere are beside the script, ready to render.

A few things to know when you script the plugin:

  • The actions work on the selection. Each create action selects what it made, so the next action applies to it. Bake Simulation, Free Simulation and Simulate Frame Range are the exceptions: they act on every Deformable Scene.
  • The tools compute as Maya asks for them. In mayapy and a batch render, they run at once, on the main thread. In Maya’s window they run in the background; cmds.deformableJobs(finish=True) waits for them all.
  • A saved file needs no update. The plugin stores the tool outputs in the file. A script that opens a saved file can simulate or render right away, as in the commands above.
  • A script bakes over a bake. Bake Simulation asks before it overwrites a bake only in Maya’s window. Another file’s bake, such as that of shot.ma beside shot.mb, it bakes over only with overwrite=True.

Read the simulation from a script

Maya evaluates only what something asks for. In Maya’s window, the viewport asks for what it shows; in mayapy, nothing does. So a script that steps the time must also read the Deformable Scene’s simulatedFrame on every frame, or the frames it skips are never simulated:

python
for frame in range(1, 49):
    cmds.currentTime(frame)
    cmds.getAttr("deformableSceneShape1.simulatedFrame")

simulatedFrame is the frame the scene shows: the frame it simulated, replayed or read from its bake. Read it after setting the time, before you read an object’s outputs.

The actions as Python functions

Every menu item and shelf button runs an action of the deformable_maya Python package, which the module puts on Maya’s Python path. Run one by its key:

python
from deformable_maya import commands

commands.run("deformableCreatePrimitiveObject", primitive="sphere")
commands.run("deformableSetType", type="kinematic")

commands.run(key, **flags) takes the flags by their camelCase names, as below; a flag you leave out takes its default. Each action is also a function of a module of deformable_maya.actions, which takes the flags in snake_case, such as deformable_maya.actions.create.create_primitive_object(primitive="sphere"). commands.actions() gives every action of the menus by its key.

An action works on the selection, as the menu item does, and is one undo step. When the selection does not fit, it prints a warning that says what to select, such as Deformable: Select one or more deformable objects, changes nothing and returns None. Any other failure raises an exception, after it took back what the action did.

Key Menu item Flags
deformableCreateScene Deformable Scene > Create Scene, Create New Scene new: True to create another Deformable Scene
deformableCreatePrimitiveObject Deformable Object > Create Primitive Object primitive: cube, sphere, cylinder, cone, pyramid or platonicSolid
deformableCreateObjectFromPolygonMesh Deformable Object > Create Object from Polygon Mesh maximumArea, quality, maximumEdgeLength, anisotropyScale, anisotropyDirection
deformableCreateObjectWithAutocage Deformable Object > Create Object with Autocage scaleGap, targetFaceCount, maximumEdgeLength, breakable
deformableCreateBareObject Deformable Object > Create Bare Object source: polygonMesh, polygonMeshWithAutocage, triangleMesh, tetrahedralMesh or nonClosedPolygonMesh; thickness; direction: both, up or down; spanLayers
deformableCreateAutocageMesh Deformable Object > Create Autocage Mesh
deformableAddSurfaceMesh Deformable Object > Add Surface Mesh to Object breakable
deformableUseTetrahedralMeshAsSurfaceMesh Deformable Object > Use Tetrahedral Mesh as Surface Mesh
deformableCreateSplintersFromImage Deformable Object > Create Splinters from Image imageLibrary, such as "rough_bricks" or "Custom"; imageFile; allowNonconvex
deformableImportSplinterMesh Deformable Object > Import Splinter Mesh meshLibrary, such as "brick_wall"; meshFile, an OBJ file
deformableAddSplintersToObject Deformable Object > Add Splinters to Object
deformableAddGlueRegion Deformable Object > Add Glue Region
deformableAddRegion Deformable Object > Add New Region type: passive, material or density; preset for a material region
deformableMakeMeshIntoRegion Deformable Object > Make Mesh into Region type: passive, glue, material or density; preset for a material region
deformableApplyField Deformable Object > Apply Field to Object
deformableVerifyMesh Deformable Object > Verify Mesh angleThresholdDegrees, gapThreshold, planarThreshold, checkUVConsistency, uvThreshold, sameUV, convex, closedBoundary, selfIntersection: skip, perIsland or full
deformableCheckCoLocatedVertices Deformable Object > Check Co-located Vertices
deformableSetBreakable Edit Deformable > Make Breakable, Make Unbreakable breakable: True or False
deformableSetType Edit Deformable > Make Dynamic, Make Kinematic type: dynamic or kinematic
deformableSetEnabled Edit Deformable > Enable, Disable enabled: True or False
deformableSetWait Edit Deformable > Wait on Update, Don’t Wait on Update wait: True or False
deformableUpdateNow Edit Deformable > Update Now
deformableDuplicateObject Edit Deformable > Duplicate Object
deformableMoveToScene Edit Deformable > Move to Scene
deformableDisassembleObject Edit Deformable > Disassemble Object, Detach component: "" for the whole object, surfaceMesh, splinters or fields
deformableDelete Edit Deformable > Delete, Deformable Scene > Delete Scene
deformableDeleteHistory Edit Deformable > Delete History
deformableRefreshSurfaceMesh Edit Deformable > Refresh Surface Mesh
deformableAssignInnerMaterial Edit Deformable > Assign Inner Material
deformableShowShape Edit Deformable > Show Shape shape: surfaceMesh, inputSurfaceMesh, cage, drivenTetrahedralMesh, simulatedTetrahedralMesh, splinters or regions
deformableHideShape Edit Deformable > Hide Shape shape, as Show Shape
deformablePaintDrivenVertices Edit Deformable > Paint Driven Vertices
deformableSelectNode Edit Deformable > Select, Deformable Material > Select Material Node type: scene, object or material
deformableFindIntersectingObjects Edit Deformable > Intersecting Objects > Find Intersecting Objects
deformableKeepIntersectingObjects Edit Deformable > Intersecting Objects > Keep Intersecting Objects in Selection
deformableAssignMaterialPreset Deformable Material > Assign Material Preset preset, such as "rubber"
deformableAssignMaterialFromActive Deformable Material > Assign Material from Active
deformableSimulateFrameRange Deformable Scene > Simulate Frame Range
deformableBakeSimulation Deformable Scene > Bake Simulation overwrite: True to skip the question in Maya’s window and bake over another file’s bake
deformableFreeSimulation Deformable Scene > Free Simulation
deformableExtractOutputShapes Deformable Scene > Extract Output Shapes
deformablePreferences Deformable Scene > Preferences…, Deformable Help > License…
deformableUserGuide Deformable Help > User Guide
deformableScriptingReference Deformable Help > Scripting Reference
deformableCopySupportInfo Deformable Help > Copy Support Info
deformableAbout Deformable Help > About Deformable

The create actions return the transforms they made, Extract Output Shapes the meshes it made, Simulate Frame Range and Bake Simulation whether every frame ran, and Free Simulation and Delete how many objects they took.

Runtime commands

The plugin also adds five Maya commands, for MEL and maya.cmds. The actions use them; scripts need them for what the actions do not do, such as waiting for the tools or reading a bake. None of them is undoable, except deformableLoadSplinterImage and deformableAssignMaterialPreset, which change a node.

deformableJobs

The tool jobs: Triangulate, Tetrahedralize, Autocage and Prepare computing in the background.

Flag Short Argument What it does
-list -l Returns the running jobs, oldest first, each as its label and running time, such as Tetrahedralize (pSphere1) 0:42.
-cancel -c Cancels every job. Returns the names of their nodes, which show Cancelled.
-finish -f Brings every tool node up to date: computes each, waits for every job and applies its result, until nothing changes, so a chain of tools computes through.
-apply -a Applies the jobs that finished, as Maya’s window does every tenth of a second.
-update -u Computes the tool nodes named after the flags, or every tool node, once, even those set to Wait or cancelled. As Update Now.
-asynchronous -as on or off Runs the jobs in the background, as Maya’s window does, or at once, as mayapy does. With -query, returns the setting.
-waiting -w With -query: whether a finished job waits to be applied.
python
cmds.deformableJobs(finish=True)
cmds.deformableJobs("pSphere1_deformableTetrahedralize", update=True)

deformableMessages

The messages the nodes queue: each new error or warning of a node, and each new message of a scene. The plugin shows them in the Script Editor and on the Command Line; mayapy and a batch render print them as they happen.

Flag Short Argument What it does
-take -t Returns the messages queued, oldest first, as a flat list of level and text, such as ["WARNING", "Deformable: deformableScene1: Play from the start frame"], and empties the queue.
-playback -p on or off Tells the nodes a playback runs: while it does, each message is queued once, however often the playback loops.

deformableBake

A Deformable Scene’s frame cache and disk bake. Every flag but -frameCacheLimit takes the scene, its transform or its shape, with -scene. Bake with the Bake Simulation action, which writes the record that lets the bake play after a reopen; the -begin and -finish flags it uses write no record.

Flag Short Argument What it does
-scene -sc scene The Deformable Scene.
-begin -bg folder Starts writing a bake into the folder: the frame after the start frame builds the simulation anew, and each frame it steps is written.
-rangeKey -rk text With -begin: the key of the inputs over the range, which the bake keeps in its index.
-owner -ow file path With -begin: the absolute path of the scene file that bakes it, which the bake keeps in its index with its path from the bake folder, so another file that bakes to the same folder leaves the bake alone.
-finish -fi Ends writing the bake. Returns whether a bake was written.
-free -fr Frees the simulation, the frames kept and the bake played or written, and deletes the bake files in -folder.
-folder -fo folder With -free or -enable: the bake folder.
-frames -fm Returns the frames of the bake being written, else of the bake that plays.
-enable -enb on or off Plays the bake in -folder, or the last one begun or played, or stops playing it.
-range -rg on or off Tells the scene that Simulate Frame Range steps the frames, which prints its own lines.
-playing -pl Returns the folder of the bake the scene plays, empty for none.
-worldFrame -wf Returns the frame the scene’s simulation stands at, nothing without one.
-renderWarning -rw Returns what a render of the frame the scene stands at would say: that it shows objects without the simulation. Empty when the frame shows them simulated or baked.
-frameCacheLimit -fcl bytes Sets the memory every Deformable Scene keeps its frames in, now and for scenes made later, as Frame Cache Limit does.
python
cmds.deformableBake(scene="deformableScene1", playing=True)
cmds.deformableBake(frameCacheLimit=4 * 1024**3)

deformableLoadSplinterImage

Reads an image with Maya’s own image readers, any format Maya reads, into a Deformable Splinter, which traces it when its Image Library is Custom. Returns the image’s width and height. Undoable. It refuses a node whose image or file name is connected or locked.

Flag Short Argument What it does
-node -n node The Deformable Splinter.
-file -f path The image file, which becomes the node’s Image File too. Without it, the node’s Image File is read again, as Reload in the Attribute Editor does.
python
cmds.deformableLoadSplinterImage(node="splinters1_deformableSplinter", file="/projects/shot/cracks.png")

deformableAssignMaterialPreset

Gives Deformable Material nodes a preset, its values and its Preset together, in one undoable step, or copies another material’s preset and values. It works on the materials named after the flags, or on the selected ones, and returns the materials it wrote. It refuses a node that is no Deformable Material and a value that is connected or locked. The Attribute Editor’s Preset menu runs it. To give a preset to deformable objects or material regions, use the deformableAssignMaterialPreset action, which finds their materials.

Flag Short Argument What it does
-preset -p name The preset, such as rubber, or Custom, which only marks the values as set by hand.
-source -s material The Deformable Material to copy the preset and the values from.
python
cmds.deformableAssignMaterialPreset("pSphere1_deformableMaterial", preset="glass")

Fracture points

Each deformable object gives one point on each inner face that opens at a frame, on its deformableObject: outputFracturePositions, outputFractureNormals and outputFractureTetrahedrons. The points are in the object’s space, and exist only on the frame their faces open. See The outputs of a deformable object.

To emit dust where an object cracks, emit an nParticle on each point, with an expression that runs on every frame. For the sphere ball of the script above:

  1. Make an nParticle object with nothing selected: in the Script Editor, on a MEL tab, run nParticle -name dust;.

  2. Choose Windows > Animation Editors > Expression Editor, name the expression dustFromCracks, paste this, and click Create:

    text
    // Emits one dust particle on each face of ball that cracks open at this frame.
    float $points[] = `getAttr ball_deformableObject.outputFracturePositions`;
    float $m[] = `getAttr ball.worldMatrix`;
    for ($i = 0; $i < size($points); $i += 4) {
        float $x = $points[$i];
        float $y = $points[$i + 1];
        float $z = $points[$i + 2];
        emit -object dust
            -position ($x * $m[0] + $y * $m[4] + $z * $m[8] + $m[12])
                      ($x * $m[1] + $y * $m[5] + $z * $m[9] + $m[13])
                      ($x * $m[2] + $y * $m[6] + $z * $m[10] + $m[14]);
    }
  3. Go to the start frame and play.

Each point comes as four numbers, x y z w, and the expression moves it into world space with the object’s world matrix. The dust appears where the sphere cracks, at about frame 17, and the nucleus solver moves it on from there. A replayed or baked frame gives the same points, so the dust comes back each time you play from the start frame, and a render of the whole range from the start frame emits it too. Give dust the look you want in its Attribute Editor, such as a short Lifespan and a cloud Particle Render Type.

To read the points from Python at the frame shown, in world space:

python
from maya import cmds
from maya.api import OpenMaya

matrix = OpenMaya.MMatrix(cmds.getAttr("ball.worldMatrix[0]"))
positions = cmds.getAttr("ball_deformableObject.outputFracturePositions") or []
points = [OpenMaya.MPoint(position) * matrix for position in positions]