﻿---
title: Command line and scripting
description: 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.
url: https://help.tangerina.io/deformable/v0.2.1/user-guides/maya/command-line-and-scripting/
---

# Command line and scripting – Maya Plugin – Deformable v0.2.1

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](https://help.tangerina.io/deformable/v0.2.1/user-guides/maya/getting-started/#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](https://help.tangerina.io/deformable/v0.2.1/user-guides/maya/playback-and-baking/#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](https://help.tangerina.io/deformable/v0.2.1/user-guides/maya/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](https://help.tangerina.io/deformable/v0.2.1/user-guides/maya/troubleshooting/#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](https://help.tangerina.io/deformable/v0.2.1/user-guides/maya/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`. A refusal of the license prints the license's message as an error 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 make 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](https://help.tangerina.io/deformable/v0.2.1/user-guides/maya/how-the-plugin-works/#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]
```
