﻿---
title: How the plugin works
description: How the Blender plugin builds deformable objects from geometry nodes and modifiers, where each setting is, the compute nodes, the start frame and the helper data.
url: https://help.tangerina.io/deformable/v0.6.0/user-guides/blender/how-the-plugin-works/
---

# How the plugin works – Blender Plugin – Deformable v0.6.0

This page shows how the Blender plugin puts the ideas of
[How the engine works](https://help.tangerina.io/deformable/v0.6.0/user-guides/engine/how-the-engine-works/) into Blender: node trees, modifiers, the
status bar and the timeline.

## Deformable objects

A deformable object is a mesh object with a Geometry Nodes modifier whose tree holds a **Deformable Object** node.
That node takes three inputs:

| Input | What it is |
|---|---|
| **Tetrahedral Mesh** | The tetrahedrons, from a Deformable Tetrahedralize, Extrude or Span Layers node. |
| **Prepared Surface Mesh** | The render surface, from a **Deformable Prepare** node. A bare object leaves it unlinked. |
| **Material** | The material, from a **Deformable Material** node. Unlinked uses the default material. |

The tools read your mesh as it reaches the Deformable modifier, so the modifiers above it in the stack count. A
Decimate modifier there makes a coarser cage, and a Subdivision Surface modifier a smoother surface. Modifiers below
the Deformable modifier change only what the object shows, not what is simulated. Apply a bound modifier, such as Mesh
Deform, Surface Deform, Laplacian Deform or Corrective Smooth with **Bind**, before you make the object deformable: the
tools read your mesh as if it were not bound.

The tools of an object with modifiers above the Deformable modifier update at the start frame. An animated modifier,
such as an Armature with an animated rig, a Wave or an animated Hook, then gives the object its start frame's shape. A
change you make at another frame, such as a setting, the mesh, a modifier or a moved Hook target, is read once you
return to the start frame. **Play** from the start frame,
**Simulate Frame Range** and
**Bake Simulation** compute these tools at the start
frame first.

The render surface keeps each face's material slot, every UV map with the active and the render map, and each
corner's normal, custom normals included.

## The Deformable Scene

A **Deformable Scene** node holds one simulation. The first create action in a Blender scene adds an object named
**Deformable Scene** that holds this node, with the Deformable Scene modifier. It shows a small gravity arrow in the
viewport and nothing in renders. **Object > Deformable >**
**Create Scene** makes one, or selects the one the scene
has.

The scene's settings are on that modifier's panel. Gravity defaults to (0, 0, −9.81), down Blender's Z axis. The
**Objects** setting is a collection. When it is empty, the simulation takes every deformable object of the Blender
scene that no other Deformable Scene claims. The **Force Fields** setting is a collection too: when it is empty, every
force field of the view layer pushes the objects. See
[Force fields](https://help.tangerina.io/deformable/v0.6.0/user-guides/blender/creating-objects/#force-fields).

### More than one Deformable Scene

To split the objects of a scene between two Deformable Scenes:

1. Select the **Deformable Scene** object and press **Shift+D** to copy it.
2. Put the objects of each Deformable Scene in a collection of their own.
3. Set each collection as the **Objects** of one of the two Deformable Scene objects.

Set **Objects** on both. A Deformable Scene with an empty Objects collection takes every object that no other scene
claims.

## The nodes

**Add > Deformable** in the Geometry Node Editor lists 13 nodes:

| Node | What it does |
|---|---|
| Deformable Triangulate | Runs the Triangulate tool. |
| Deformable Tetrahedralize | Runs the Tetrahedralize tool. |
| Deformable Extrude | Runs the Extrude tool. |
| Deformable Span Layers | Runs the Span Layers tool. |
| Deformable Autocage | Runs the Autocage tool. |
| Deformable Prepare | Runs the Prepare tool, for a Deformable Object. |
| Deformable Splinter | Makes a splinter cage, for Deformable Prepare. |
| Deformable Material | Holds the ten material values, with a Preset menu. |
| Deformable Scene | Holds one simulation: the deformable objects that collide with each other. |
| Deformable Object | Makes the mesh a deformable object of the simulation. |
| Deformable Glue Region | Glues the member objects that touch inside a convex mesh. |
| Deformable Material Region | Gives the tetrahedrons inside a convex mesh their own material. |
| Deformable Density Region | Changes the tetrahedron size inside a mesh. |

The tools are explained in [How the engine works](https://help.tangerina.io/deformable/v0.6.0/user-guides/engine/how-the-engine-works/#the-tools). You
rarely add these nodes by hand. The **Object > Deformable** actions and the **Add Modifier > Deformable** entries build
the trees for you.

## Where the settings are

Every setting of a tree is on its modifier panel in the Properties editor, in one panel per node, named after it:
**Triangulate**, **Tetrahedralize** (with **Anisotropy** below Triangulate and Tetrahedralize), **Autocage**,
**Extrude**, **Span Layers**, **Prepare**, **Material** and **Object**, with **Surface** inside Object. The
**Material** and **Object** panels start open, and the others start closed. A region's settings are on its own
modifier, and the scene's on the Deformable Scene object's.

The settings that take objects are collections: **Objects** and **Force Fields** on the scene, **Density Regions** on
Tetrahedralize, and **Passive Regions** and **Material Regions** on the Object panel.

## Compute nodes

Seven nodes run a tool: Triangulate, Tetrahedralize, Extrude, Span Layers, Autocage, Prepare and Splinter. The
plugin stores their output in the .blend file.

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

- the status bar shows them with how long each has run, such as **Deformable: Tetrahedralize (Sphere) 0:42**, and a
  **Cancel** button;
- the node shows **Computing**.

**Cancel** stops them. A cancelled node shows **Cancelled**.

A node shows its error or warning on the node itself. A new error or warning also goes, once, to Blender's Info log and
to the terminal, with the object and the node it belongs to.

### Run: Auto or Wait

Every tool node except Splinter has a **Run** menu. A node set to **Wait** shows **Waiting**. To switch every tool of
the selected objects, use **Object > Deformable > Wait on Update** or **Don't Wait on Update**. To compute the waiting
tools once, and the cancelled ones again, choose **Object > Deformable >**
**Update Now**.

## The start frame

The start frame is the **Frame Start** of the Blender scene, or the start of a custom **Simulation Range** when you
set one in the Scene properties. See
[The start and end frames](https://help.tangerina.io/deformable/v0.6.0/user-guides/blender/playback-and-baking/#the-start-and-end-frames).

When a rule stops the simulation, the status bar says so:

- **Deformable: Play from the start frame** when you jump ahead without playing;
- **Deformable: Return to the start frame to apply changes** after you change a setting;
- **Deformable: Set Playback > Sync to Play Every Frame: a dropped frame is never simulated** when you play with
  another **Playback > Sync** setting.
  **Create Scene** sets Play Every Frame for you.

### Animated values are read one frame late

The simulation reads animated values one frame late: frame 10 uses what frame 9 showed. A Kinematic object that you
animate is one frame behind its keys, a keyed material value applies one frame late, and an object released at frame
20 starts to move one frame later, at frame 21.

## Units and axes

By default, 1 Blender unit is 1 simulation unit, and gravity is 9.81 down the Z axis. If your scene uses another
unit, change **Scale** on the Deformable Scene. See
[Scale](https://help.tangerina.io/deformable/v0.6.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 Info log names the new object with its count and the scene's
  total, such as **Deformable: Created Cube: 1,840 tetrahedrons; scene total 2,812**.
- The status bar shows the count of the active object and its scene's total, such as
  **Deformable: Cube: 1,840 tetrahedrons; scene total 2,812**. With the Deformable Scene object active, it shows the
  scene's total alone.

To count the output of one tool instead:

1. Open a Geometry Node Editor and pick the object's modifier tree.
2. Ctrl+Shift+click the **Deformable Tetrahedralize** node, or the **Deformable Extrude** or **Deformable Span
   Layers** node. Blender adds a Viewer node.
3. Open a Spreadsheet. Its **Face** count is 4 times the tetrahedron count: the plugin stores each tetrahedron as 4
   triangles.

A bare object shows its tetrahedrons, so the viewport **Statistics** overlay also works: divide its face count by 4.

## The outputs of Deformable Object

The Deformable Object node has three outputs. The modifier trees show the first one, or the third one for a bare
object.

| Output | What it holds |
|---|---|
| Surface Mesh | The deformed render surface, with your materials, UV maps and normals. |
| Fracture Points | One point on each inner face that opened at this frame. Each point has the attributes `normal` (the face's outward direction) and `tetrahedron` (its index). |
| Tetrahedral Mesh | The simulated tetrahedrons, 4 triangles each on points they share, with the face attributes `island` (the piece it belongs to), `strain_measure` (how much it is stretched) and `flags`. |

Build on **Fracture Points** in the object's node tree, after the Deformable Object node, for example to instance
dust or sparks on them.

## Driven vertices and forces

A node tree marks the vertices to hold and pushes others. The simulation reads two point attributes from what flows
into the **Tetrahedral Mesh** input of the **Deformable Object** node, on every frame:

| Attribute | Type | What it does |
|---|---|---|
| `driven` | Boolean, on points | A vertex set to true follows the object's animation, as inside a passive region. |
| `force` | Vector, on points | A force on the vertex, in newtons in simulation units, added on each frame to the force fields' push. A held vertex takes none, as from a field: once released, it takes the force from its first free frame. |

To add one:

1. Open a Geometry Node Editor and pick the object's modifier tree.
2. Find the link into the **Tetrahedral Mesh** input of the **Deformable Object** node.
3. Add a **Store Named Attribute** node on that link (**Add > Attribute > Store Named Attribute**).
4. Set its type to **Boolean** for `driven` or **Vector** for `force`, its domain to **Point**, and its **Name** to
   `driven` or `force`.
5. Feed its **Value**, and its **Selection** if you want, from other nodes.

For example, to hold the top of a 2 m cube centered at the object's origin, feed the **Value** of a `driven`
attribute from a **Compare** node: **Position** Z, **Greater Than**, 0.9.

A force acts on each vertex that has it, so the total grows with the vertex count. For example, a force of 20,000 along
X on every vertex of a 2 m cube made with

**Create Object from Polygon Mesh** and the default material pushes it about 2.8 m along X by frame 20.

The simulation reads the attribute values on every frame, but not the node settings. Keyframing a value on these
nodes stops the simulation, and the status bar says **Deformable: Return to the start frame to apply changes**. To
change the attributes over time, compute them from a **Scene Time** node instead. For example, compare its **Frame**
output with 20 to hold vertices until frame 20.

Do not move the points in this part of the tree. The **Deformable Prepare** node must see the same tetrahedrons as the
**Deformable Object** node, or the object shows **Deformable Prepare and Deformable Object take different
tetrahedrons**.

## One tree per object

Each deformable object needs its own node tree. When two objects share a tree, for example after **Shift+D**, the
plugin copies the tree, so each object gets its own. **Object > Deformable >**
**Duplicate Object** does the same and also
keeps the copy in the same collections as the source, such as a glue region's members.

## Helper data

The plugin keeps some helper data in the .blend file: objects named **.Deformable Probe** and **.Deformable
Result**, and node groups whose names start with **.Deformable**. They are not in any scene, and the leading dot
keeps them out of Blender's pickers. They hold the tool outputs. Do not delete them.
