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

Engine

How the engine works

Deformable objects, the Deformable Scene, the tools, the start frame and the units, explained once for the plugins and the SDKs.

On this page

This page explains the ideas that the plugins and the C, Rust and Python SDKs share. Read it once before you build your own scenes. The Engine guide names things as the plugins show them; each section ends with links to where the idea lives in each plugin and each SDK.

Deformable objects

A deformable object is a mesh that the simulation moves. It has three parts:

Part What it is
Tetrahedral mesh The volume the simulation moves: a mesh of small tetrahedrons that fills the object.
Prepared surface What you see and render: your mesh, attached to the tetrahedrons by the Prepare tool. It follows the tetrahedrons every frame and keeps its UVs, normals and materials.
Material How the object behaves: stiffness, weight, toughness and more. See Materials.
Tetrahedral Mesh Prepared Surface Mesh Deformable Object

The tetrahedrons come from your mesh through the mesh tools. A closed mesh is filled by Tetrahedralize. Its outer shell, the cage, comes from Triangulate (your mesh, triangulated) or Autocage (a new closed cage around any mesh). A thin object, such as a sheet or a floor, comes from Extrude or Span Layers. See Preparing meshes.

An object with no prepared surface is a bare object. It shows its simulated tetrahedrons instead of a surface. Bare objects are fine for floors, walls and quick tests.

The simulation starts from the object’s shape at the start frame. So the tools read your mesh as it stands at the start frame: an animated rig or deformer before them gives the object its start frame’s shape, and play is never slowed by the tools.

See it in: Blender · Maya · C · Rust · Python

The Deformable Scene

A Deformable Scene holds one simulation: its objects, gravity, units, substeps and glue. The first create action adds one for you.

You need at least one Deformable Scene. Without one, nothing moves. Objects in different Deformable Scenes do not collide. See Simulation settings.

See it in: Blender · Maya · C · Rust · Python

The tools

Seven tools turn meshes into simulation input:

Tool What it does
Triangulate Triangulates a polygon mesh into a cage of well-shaped triangles.
Tetrahedralize Fills a closed triangle cage with tetrahedrons.
Extrude Extrudes a triangle mesh into one layer of tetrahedrons.
Span Layers Fills the space between two layers with the same triangles.
Autocage Wraps any mesh in a closed triangle cage.
Prepare Clips a render surface to the tetrahedrons and attaches it to them.
Splinter Makes a splinter cage from a line drawing or from a mesh, for Prepare.

A tool runs when one of its inputs changes, and the plugin stores its output in the scene file. When you reopen a file, nothing computes again.

Triangulate, Tetrahedralize, Autocage and Prepare can take a while on a dense mesh, so they run in the background and the program stays responsive. You can cancel them. A cancelled tool keeps its last output until one of its inputs changes, or until you choose Update Now.

Every tool but Splinter has a Run setting:

  • Auto computes on every change. This is the default.
  • Wait keeps the last output until you ask for an update with Update Now.

Wait helps with a heavy mesh: change several settings, then compute once. Wait on Update and Don’t Wait on Update switch every tool of the selected objects at once.

A tool that fails shows its error, and its output is empty. Tools after it may show an error too: fix the first one in the chain.

See it in: Blender · Maya · C · Rust · Python

The start frame

The simulation starts at the start frame of its Deformable Scene.

  • At the start frame, every deformable object shows its rest shape. Nothing simulates.
  • When you play from the start frame, the plugin builds the simulation from the start frame and steps it once per frame.
  • Every frame is cached as it plays. Scrubbing back replays the cache, and nothing simulates again. The start frame keeps the cache too, until you change something the simulation reads.
  • A baked scene plays its bake, from the start frame too, and does not simulate.
Cached frames Start frame Play Scrub back

So the rules are:

  1. Play from the start frame. If you jump ahead without playing, the plugin says Play from the start frame.
  2. After you change a setting, return to the start frame and play again. Until then, the plugin says Return to the start frame to apply changes.
  3. Play every frame. A frame that playback skips to keep up is never simulated, so set the playback to play every frame. The create actions set it for you.

See it in: Blender · Maya · C · Rust · Python

When animated values are read

The simulation follows animated values: Kinematic objects, passive regions, driven vertices and keyed settings. When it reads them depends on the interface:

Units and axes

By default, 1 scene unit is 1 simulation unit, and the simulation unit reads as 1 metre: gravity is 9.81 down the scene’s up axis. Material values, such as Young’s modulus and density, are in simulation units. If your scene uses another unit, change Scale on the Deformable Scene. See Scale.

See it in: Blender · Maya · C · Rust · Python