﻿---
title: How the plugin works
description: How the Maya plugin builds deformable objects from nodes in their history, the shapes it adds, the Attribute Editor, the tool nodes, the start frame, Maya's history commands and the locked Deformable Scene.
url: https://help.tangerina.io/deformable/v0.4.0/user-guides/maya/how-the-plugin-works/
---

# How the plugin works – Maya Plugin – Deformable v0.4.0

This page shows how the Maya plugin puts the ideas of
[How the engine works](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/how-the-engine-works/) into Maya: nodes, shapes, the Attribute
Editor and the Time Slider.

## Deformable objects

A deformable object is a mesh transform whose shapes are fed by a **deformableObject** node in its history. The create
actions build the whole network for you. For a mesh `pSphere1` made with **Create Object with Autocage**, it is:

![The network of pSphere1: pSphere1Shape, now an intermediate object, feeds pSphere1_deformableAutocage, then pSphere1_cage, then pSphere1_deformableTetrahedralize, and also feeds pSphere1_deformablePrepare. The tetrahedral mesh goes to pSphere1_deformablePrepare and pSphere1_deformableObject, the prepared surface mesh goes to pSphere1_deformableObject, and pSphere1_deformableMaterial feeds it too. pSphere1_deformableObject hands its object data to deformableSceneShape1 and gets back states, and sends the surface mesh to pSphere1_surfaceMesh.](https://help.tangerina.io/deformable/v0.4.0/images/maya-node-network.svg)

| Node | What it does |
|---|---|
| **Tool nodes** | Turn your mesh into tetrahedrons and a prepared render surface: here Autocage, Tetrahedralize and Prepare. See [Tool nodes](#tool-nodes). |
| **deformableMaterial** | Holds the ten material values, with a **Preset** menu. |
| **deformableObject** | Makes the mesh a deformable object of the simulation, and holds its settings: **Type**, **Disabled**, **Self Collision**, **Never Sleep**, **Show Inner Faces** and **Start Splintered**. |
| **deformableScene** | Simulates its objects together. Each object hands it its rest data, and it hands each object back its state on every frame. |

The tools read your mesh as it stands at the start frame, history included. A deformer or an animated rig before
them, such as a skinCluster or a blendShape, gives the object its start frame's shape, and play is never slowed by
the tools. You can edit the mesh or a tool at any frame: the tools compute again, and the next play from the start
frame uses what they make.

Make every change to the transform before you create the object. Freeze its transformations then, with
**Modify > Freeze Transformations**, if you want to. After **Create Object**, freezing would move the shapes the
deformableObject feeds but not the mesh its tools read, so the object refuses it with **Freeze Transformations does not
apply to a deformable object: undo it, and freeze before Create Object**. Undo it with **Ctrl+Z**.

The render surface keeps each face's shading group, every UV set with the current one, and each corner's normal,
locked normals included. See [Shading](#shading).

### The shapes of an object

The network adds shapes under the object's transform. The shaded one comes first, so the Attribute Editor and the
Channel Box show it when you select the transform:

| Shape | What it shows | Shown |
|---|---|---|
| `pSphere1_surfaceMesh` | The deformed render surface. A bare object has none. | Yes |
| `pSphere1Shape` | Your mesh, as you made it, with its history. The tools read it. | No: an intermediate object |
| `pSphere1_cage` | The cage a Triangulate or an Autocage made, which Tetrahedralize fills. | No: a template |
| `pSphere1_drivenTetrahedralMesh` | The tetrahedrons at rest, which a Kinematic object and its driven vertices follow. Deform or key it to drive the object. See [Paint Driven Vertices](https://help.tangerina.io/deformable/v0.4.0/user-guides/maya/creating-objects/#paint-driven-vertices). | No: a template |
| `pSphere1_simulatedTetrahedralMesh` | The simulated tetrahedrons, with the colour sets `island` and `strain`. A bare object shows it, in orange. Others get it the first time you show it. | No, but on a bare object |

**Edit Deformable > Show Shape** and **Hide Shape** show and hide them for the selected objects: **Surface Mesh**,
**Input Surface Mesh** (the mesh the surface is made from), **Cage**, **Driven Tetrahedral Mesh**, **Simulated
Tetrahedral Mesh**, **Splinters** and **Regions**. Hide Shape makes the input surface mesh an intermediate object
again.

### Disassemble and detach

**Edit Deformable > Disassemble Object** takes each selected object apart into the meshes it was made of: it leaves its
Deformable Scene, its network is deleted, and your mesh shows again with its own history. Its splinter cages, an added
surface mesh and the regions under it move beside it. The report says how many it took apart, such as
**Disassembled 1 object**.

**Edit Deformable > Detach** takes one part off each selected object:

| Item | What it does |
|---|---|
| **Surface Mesh** (shelf: **Detach Surface Mesh**) | Takes the render surface away: the object becomes a bare object and shows its tetrahedrons in orange. A surface mesh you added moves beside it. |
| **Splinters** (shelf: **Detach Splinters**) | Takes the splinter cages off its Prepare, and moves them beside it. |
| **Fields** | Stops the fields selected with it pushing it, or every field when none is selected. See [Detach Fields](https://help.tangerina.io/deformable/v0.4.0/user-guides/maya/creating-objects/#detach-fields). |

When nothing has the part, it warns **Nothing to detach**.

## The Deformable Scene

A **Deformable Scene** holds one simulation: a locator transform `deformableScene1` with the shape
`deformableSceneShape1`. The first create action makes one, or **Deformable Scene > Create Scene**, or
**Create Scene** on the shelf, which selects the one
the Maya scene has. It draws a small arrow along gravity, in the viewport only, never in renders. Its settings are in
the Attribute Editor: **Start Frame**, **Gravity**, **Scale**, **Substeps**, **Disable**, and the **Glue All** section.
See [Simulation settings](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/simulation-settings/).

Gravity defaults to (0, −9.81, 0), down Maya's Y axis. A new object joins the first Deformable Scene by name, at the
scene's next free element.

The Deformable Scene is locked, so Maya's own history commands on one object cannot delete it or reach the other
objects through it. Maya's **Delete** refuses it, with **Cannot delete locked node 'deformableScene1'**. Use
**Deformable Scene > Delete Scene** instead. See [Delete](#delete).

### More than one Deformable Scene

Each Deformable Scene simulates its own objects. To split the objects of a Maya scene between two:

1. Choose **Deformable Scene > Create New Scene**. It makes `deformableScene2`, with its shape
   `deformableSceneShape2`, on Maya's time, locked like the first. **Create Scene** only selects the scene the Maya
   scene has, and Maya's **Duplicate** gives a copy that is not on Maya's time.
2. Select the objects to move, then the Deformable Scene they should join.
3. Choose **Edit Deformable > Move to Scene**.

Each object leaves the scene it was in and joins the selected one, with the fields that push it. The report names the
scene, such as **Moved 2 objects to deformableScene2**. Without a Deformable Scene selected, the objects move to the
one new objects join.

An object in no Deformable Scene does not simulate. The plugin names it once, such as
**Deformable: Add to a Deformable Scene to simulate: pCube1**.

### Object order

A Deformable Scene takes its objects in the order of its `objects` elements, which is the order you made them in. A
rename never changes it, so a scene simulates the same before and after you rename objects or reopen the file. The
same holds for an object's regions.

## The Attribute Editor

Select a deformable object and open the Attribute Editor (**Ctrl+A**). Its tabs show the surface shape, then the
nodes upstream of it: **pSphere1_deformableObject**, its tools and its **pSphere1_deformableMaterial**. The Channel
Box lists them under **INPUTS**. To go straight to one node, choose **Edit Deformable > Select > Deformable Scene**,
**Deformable Object** or **Deformable Material**, or **Deformable Material > Select Material Node**.

| Node | Attribute Editor sections |
|---|---|
| deformableObject | **Status**; **Object Attributes**: Type, Disabled, Self Collision, Never Sleep; **Surface**: Show Inner Faces, Start Splintered |
| deformableMaterial | **Material Attributes**: the **Preset** menu, then the ten values. See [Materials](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/materials/). |
| deformableScene | **Status**; **Scene Attributes**: Start Frame, Gravity, Scale, Substeps, Disable; **Glue All**; **Fields**; **Bake**: Bake Directory |
| deformableTriangulate | **Status**; **Triangulate Attributes**: Maximum Area, Quality, Closed Boundary, Run; **Anisotropy** |
| deformableTetrahedralize | **Status**; **Tetrahedralize Attributes**: Maximum Edge Length, Run; **Anisotropy** |
| deformableExtrude | **Status**; **Extrude Attributes**: Thickness, Direction, Run |
| deformableSpanLayers | **Status**; **Span Layers Attributes**: Run |
| deformableAutocage | **Status**; **Autocage Attributes**: Scale Gap, Target Face Count, Target Tetrahedron Count, Run |
| deformablePrepare | **Status**; **Prepare Attributes**: Clip Mode, UV Scale, Inner Group Id, Run |
| deformableSplinter | **Status**; **Splinter Attributes**: Source, Image Library, Image File, Mesh Library, Mesh File, Size, Origin, Allow Nonconvex |

What each setting does is on [Preparing meshes](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/preparing-meshes/),
[Render surfaces](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/render-surfaces/) and
[Fracture and splinters](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/fracture-and-splinters/).

The **Status** section shows **Compute State** (Ready, Waiting, Computing or Cancelled), **Error Message**, **Warning
Message** and, on the nodes that make tetrahedrons, **Tetrahedron Count**. The Deformable Scene's **Status Message**
shows what the scene says now, empty when nothing is wrong.

In the Attribute Editor's **Help** menu, **Help on** a Deformable node type opens its section of this guide.

## Node types

The plugin registers ten node types. You rarely make them by hand: the actions build and connect them.

| Node type | What it does |
|---|---|
| deformableTriangulate | Runs the Triangulate tool: your mesh, triangulated into a cage. |
| deformableTetrahedralize | Runs the Tetrahedralize tool: fills a closed triangle cage with tetrahedrons. |
| deformableExtrude | Runs the Extrude tool: one layer of tetrahedrons under a triangle mesh. |
| deformableSpanLayers | Runs the Span Layers tool: tetrahedrons between two layers with the same triangles. |
| deformableAutocage | Runs the Autocage tool: a new closed cage around any mesh. |
| deformablePrepare | Runs the Prepare tool: clips a render surface to the tetrahedrons and attaches it to them. |
| deformableSplinter | Makes a splinter cage from a line drawing or a mesh, for Prepare. |
| deformableMaterial | Holds the ten material values, with a Preset menu. |
| deformableObject | Makes a mesh a deformable object of a Deformable Scene. |
| deformableScene | Holds one simulation: the deformable objects that collide with each other. |

The tools are explained in [How the engine works](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/how-the-engine-works/#the-tools).

## Tool nodes

Seven nodes run a tool: Triangulate, Tetrahedralize, Extrude, Span Layers, Autocage, Prepare and Splinter. The plugin
stores their output in the scene file, so a reopened file computes nothing again. Prepare is the exception: its
output is not stored, and it prepares the surface again the first time the file shows it.

While Triangulate, Tetrahedralize, Autocage or Prepare run in the background:

- the progress bar at the bottom of Maya's window shows them, with how long each has run, such as
  **Deformable: Tetrahedralize (pSphere1) 0:42**;
- their **Compute State** shows **Computing**.

Press **Esc** while the progress bar shows them to cancel them all. A cancelled node shows **Cancelled** and keeps its
last output until one of its inputs changes.

A node shows its error or warning in the **Status** section of its Attribute Editor. A new error or warning also goes,
once, to the Script Editor and the Command Line, with the object and the node it belongs to, such as
**Deformable: pSphere1: Deformable Tetrahedralize: INVALID_CAGE: …**. In mayapy and in a batch render, the tools run
as Maya asks for them, without the progress bar.

### Run: Auto or Wait

Every tool node but Splinter has a **Run** attribute. A node set to **Wait** shows **Waiting**. To switch every tool of
the selected objects, choose **Edit Deformable > Wait on Update** or **Don't Wait on Update**. To compute the waiting
tools once, and the cancelled ones again, choose **Edit Deformable > Update Now**, or click
**Update Now** on the shelf. Update Now also computes
the tools of a selected Autocage Mesh or splinter cage.

When you open a file whose tools wait, the plugin says which, such as **Deformable: 2 tools wait for Update Now:
pSphere1_deformableTetrahedralize, pSphere1_deformablePrepare**.

## The start frame

The start frame is the **Start Frame** of the Deformable Scene, in the **Scene Attributes** section. **Create Scene**
sets it to the start of the playback range. It does not follow the Time Slider afterwards: change it on the scene when
your shot starts elsewhere. **Simulate Frame Range** and **Bake Simulation** run from the start frame to the end of the
playback range.

The tool nodes read their inputs at the start frame. **Play** from the start frame waits for the tools still
computing first, with Maya's busy cursor, and says so: **Deformable: Play waits for the start frame to compute**, with
the tools it waits for. **Simulate Frame Range** and **Bake Simulation** also finish every tool first.

When a rule stops the simulation, the Script Editor and the Command Line say so, once, with the scene's name:

- **Deformable: deformableScene1: Play from the start frame** when you jump ahead without playing;
- **Deformable: deformableScene1: Return to the start frame to apply changes** after you change what the world is
  built from, such as an object's mesh, the scene's Gravity or a region's place;
- **Deformable: deformableScene1: Set Playback speed to Play every frame: a dropped frame is never simulated** when
  playback skips frames. **Create Scene** sets **Play every frame** for you.

See [Play](https://help.tangerina.io/deformable/v0.4.0/user-guides/maya/playback-and-baking/#play).

### Animated values are read at the frame

The simulation reads animated values at the frame it computes: frame 10 uses what frame 10 shows. A Kinematic object
follows its keys on the same frame, a keyed material value applies at its frame, and an object whose **Type** turns
Dynamic at frame 20 first moves at frame 20.

The values read on every frame are the object's **Type**, the scene's **Disable**, every material value, the
transform and the driven tetrahedral mesh of each object, which Kinematic objects and driven vertices follow, the
passive regions and the fields. Keys on them play with the simulation. Any other change asks you to return to the
start frame.

## Units and axes

Maya stores lengths in centimetres, but the simulation reads one Maya unit as one metre, as Maya's own nCloth does.
Gravity is 9.81 down Y. So leave Maya's working unit at centimetre and treat one unit as one metre: a sphere of radius
1 is a 2 m ball.

To model at real size in centimetres, set **Scale** on the Deformable Scene to `0.01`. Set it to `0.01` too if you
change the working unit to metre in **Windows > Settings/Preferences > Preferences > Settings**: Maya still stores
centimetres, so a 1 m cube reaches the simulation as 100 units. See
[Scale](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/simulation-settings/#scale).

## Count the tetrahedrons

The plugin counts the tetrahedrons at the start frame:

- After a create action, once its tools finish, the Script Editor names the new object with its count and the
  scene's total, such as **Deformable: Created pCube1: 94 tetrahedrons; scene total 2,006**. Under the Free license, a
  scene over the limit adds the limit to that line, as a warning.
- The **Tetrahedron Count** in the **Status** section of the object's deformableObject, and of its Tetrahedralize,
  Extrude or Span Layers node, shows the count of that node.

A bare object shows its tetrahedrons, 4 triangles each, so Maya's **Display > Heads Up Display > Poly Count** also
works on it: divide its triangle count by 4.

## The outputs of a deformable object

The deformableObject node gives these outputs. The first three feed the object's shapes; scripts read the others.

| Output | What it holds |
|---|---|
| `outputSurfaceMesh` | The deformed render surface, with your shading, UV sets and normals, in the object's space. Feeds `_surfaceMesh`. |
| `outputTetrahedralMesh` | The simulated tetrahedrons, 4 triangles each on points they share, with the face colour sets `island` (the piece each belongs to) and `strain` (how much it is stretched). Feeds `_simulatedTetrahedralMesh`. |
| `outputRestTetrahedralMesh` | The tetrahedrons at rest. Feeds `_drivenTetrahedralMesh`. |
| `outputIslands`, `outputStrainMeasures`, `outputTetrahedronFlags` | One value per tetrahedron: its island, its strain measure and its flags. |
| `outputFracturePositions`, `outputFractureNormals`, `outputFractureTetrahedrons` | One point on each inner face that opened at this frame, in the object's space: its position, its outward direction and the index of its tetrahedron. |

To emit dust or sparks where an object cracks, see
[Fracture points](https://help.tangerina.io/deformable/v0.4.0/user-guides/maya/command-line-and-scripting/#fracture-points).

To see the pieces, choose **Edit Deformable > Show Shape > Simulated Tetrahedral Mesh**, select that shape, and pick
its `island` colour set in **Mesh Display > Color Set Editor**, in the **Modeling** menu set.

## Shading

The render surface keeps the shading of the mesh it is made from, face by face, through every fracture, and every UV
set, with the one current on your mesh. Each corner keeps the normal your mesh shows, hard or soft, locked normals
included. A bare object's tetrahedrons, and a surface that **Use Tetrahedral Mesh as Surface Mesh** made from an
autocage or from the outer faces of tetrahedrons, are shaded as a whole, with the first shading group of the mesh.

The inner faces that a crack opens take the first shading group of the surface, unless you give them their own with
[Assign Inner Material](https://help.tangerina.io/deformable/v0.4.0/user-guides/maya/creating-objects/#assign-inner-material).

Maya does not pass a shading change of your mesh down to the surface. After you assign other materials to the mesh,
select the object and choose **Edit Deformable > Refresh Surface Mesh**. See
[Change the surface](https://help.tangerina.io/deformable/v0.4.0/user-guides/maya/creating-objects/#change-the-surface).

## History and the locked scene

Maya's own history commands reach through the network, so use the plugin's instead:

| Instead of | Use | Why |
|---|---|---|
| **Edit > Delete by Type > History** on a deformable object | **Edit Deformable > Delete History** | Maya's deletes the mesh the object was made from and freezes its surface where it stands, so the object no longer follows the simulation. |
| **Modify > Freeze Transformations** after Create Object | Freeze before you create the object | The object refuses it with an error until you undo it. |
| **Edit > Duplicate** | **Edit Deformable > Duplicate Object** | Maya's copies the shapes without the network that moves them. See [Duplicate Object](https://help.tangerina.io/deformable/v0.4.0/user-guides/maya/creating-objects/#duplicate-object). |
| **Edit > Delete** on the Deformable Scene | **Deformable Scene > Delete Scene** | The scene is locked against Maya's Delete. |
| **Edit > Duplicate** on the Deformable Scene | **Deformable Scene > Create New Scene** | Maya's copy is not on Maya's time, so it never steps. |

If you used one of Maya's by mistake, undo it with **Ctrl+Z**.

### Delete History

**Edit Deformable > Delete History** deletes the construction history of the meshes the selected objects are made
from, such as a polySphere node or a deformer, and keeps their networks, their Deformable Scene and the other objects.
The report says how many, such as **Deleted the history of 1 object**.

### Delete

**Edit Deformable > Delete** deletes the selected deformable objects, each with the nodes it alone is made of, and the
selected Deformable Scenes. **Deformable Scene > Delete Scene** is the same action. A deleted scene's objects stay, in
no scene. The report says what it deleted, such as **Deleted 1 object and 1 Deformable Scene**.

Maya's own **Delete** of a deformable object's transform, or of a group that holds it, also takes its deformableObject,
its tools and its own materials, and takes it out of its scene. One undo brings it all back. What other objects share
stays, such as a region or a material.
