You are viewing the documentation for Deformable v0.6.0, an older version. Read the latest, v0.9.0

Blender Plugin

How the plugin works

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.

On this page

This page shows how the Blender plugin puts the ideas of 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.

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. 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.

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.

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.