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

Blender Plugin

Creating and editing objects

Every action of Object > Deformable that makes or changes a deformable object, its material, its regions, its splinters and its surface, the force fields that push it, and the mesh checks.

On this page

All actions are in the 3D Viewport under Object > Deformable. They work in Object Mode on the selected meshes. A mesh that already has a Deformable modifier is skipped by the create actions.

Each create action adds a Geometry Nodes modifier, and adds a Deformable Scene object when the scene has none. After an action, open the Adjust Last Operation panel at the bottom left of the viewport to change its options.

Once the tools of a new object finish, the Info log and the terminal report it with its tetrahedrons and the total of its scene, such as Deformable: Made Cube: 1,840 tetrahedrons; scene total 2,812. The plugin counts at the start frame, so an object you make on another frame is reported when you go back to it. During the trial, a scene that holds more than the trial allows also says Deformable: Trial limit: the scene simulates 3,120 tetrahedrons; the trial allows 2,500. See The trial. An object that Play would leave out is reported as a warning that says why. See An object stays still at Play.

Which action to use

Your mesh Use Tetrahedrons from Render surface
No mesh yet Create Primitive Object A new primitive The primitive, triangulated
A closed mesh with a simple shape Create Object from Polygon Mesh Your mesh, triangulated The triangulated mesh itself
Any mesh you want to keep exactly as it renders Create Object with Autocage A new cage around the mesh Your mesh
A floor, a wall or a quick test Create Bare Object Depends on the source None: the tetrahedrons show, in orange
A thin sheet or panel Create Bare Object > From Non-Closed Polygon Mesh Your mesh, extruded None: the tetrahedrons show, in orange

You can add a render surface to a bare object later. See Add a surface to a bare object.

Hollow and thin-walled objects

Why a hollow object needs its walls is on Hollow and thin-walled objects. In Blender:

  • From the non-closed polygon mesh: Create Bare Object > From Non-Closed Polygon Mesh, with Thickness set to the wall thickness and Direction to Down.
  • From two layers of the non-closed polygon mesh: Span Layers needs both layers to have the same triangles, so triangulate the mesh before you copy it:
    1. Select the mesh, press Tab for Edit Mode, press A, choose Face > Triangulate Faces, and press Tab to go back to Object Mode.
    2. Press Shift+D to copy the object, and right-click to leave the copy in place.
    3. Press Tab and A, press Alt+S, type the wall thickness as a negative number, such as -0.05, which moves the copy inward when the normals face out, press Enter, and press Tab. Sculpt the copy now if its walls should vary.
    4. Ctrl-click the original mesh in the Outliner, so that both are selected and the original is active, choose Create Bare Object > From Non-Closed Polygon Mesh, and turn on Span Layers in the Adjust Last Operation panel.
  • From a closed mesh with the walls modelled, such as one with an applied Solidify modifier: Create Object from Polygon Mesh.

Or keep the autocage and set Density on the Material panel to the real mass divided by the cage’s volume. To read the volume:

  1. Select the mesh. Create Autocage Mesh takes only a mesh with no Deformable modifier, so on an object that is deformable already, press Shift+D, right-click to leave the copy in place, and remove the copy’s Deformable modifier in the Modifier properties.

  2. Choose Create Autocage Mesh. It adds the cage and selects it. If you changed Target Face Count or Scale Gap on the object’s Autocage panel, set the same values on the cage’s.

  3. Run these lines in the Python Console:

    python
    import bmesh
    cage = bmesh.new()
    cage.from_object(C.object, C.evaluated_depsgraph_get())
    cage.transform(C.object.matrix_world)
    cage.calc_volume()
  4. Delete the cage, and the copy if you made one.

Create Scene

Create Scene adds an object named Deformable Scene with the Deformable Scene modifier, or selects the one the scene already has. It also turns on Render > Lock Interface, because the plugin writes data while a render runs, and sets Playback > Sync to Play Every Frame, because a frame that playback skips is never simulated.

The other create actions call it for you, so you rarely need it. You need it after Add Modifier > Deformable, which does not add a scene. Add Modifier > Deformable > Deformable Scene makes the object a Deformable Scene instead, and sets the same two settings.

Create Primitive Object

Create Primitive Object adds a primitive at the 3D cursor and makes it a deformable object. The submenu lists Cube, Sphere, Cylinder, Cone, Pyramid and Icosphere. The sphere is a UV sphere with 16 segments and 8 rings.

The primitive uses the node defaults: Maximum Area 1, Quality 20 and Maximum Edge Length 1. These give the same count every time:

Primitive Tetrahedrons
Cube about 24
Sphere about 650
Cylinder about 690
Cone about 30
Pyramid about 14
Icosphere about 20

One of each fits in the trial’s 2,500 tetrahedrons together.

Create Object from Polygon Mesh

Create Object from Polygon Mesh makes each selected mesh a deformable object. The modifier is Deformable Object (Polygon Mesh): Deformable Triangulate turns your mesh into the cage, Deformable Tetrahedralize fills it, and the triangulated cage is also the render surface. The surface keeps your materials, normals and UV maps.

Options:

Option Default What it does
Maximum Area 10,000 Largest triangle area of the cage. The default is so large that the cage keeps your mesh’s own resolution.
Quality 20 Smallest triangle angle, in degrees, from 1 to 20.
Maximum Edge Length 100 A size limit for the tetrahedrons inside the cage. The default is so large that the cage’s triangles set the tetrahedron size. On a coarse cage, a smaller value changes nothing: lower Maximum Area for more tetrahedrons. See Tetrahedralize.
Anisotropy Scale 1 Element size along the anisotropy direction, as a factor from 0.02 to 50.
Anisotropy Direction (1, 1, 1) The direction the anisotropy scale applies along.

The mesh must be closed. Its own triangles set the tetrahedron count, so a dense mesh gives a heavy simulation. For a dense mesh, use Create Object with Autocage instead.

Create Object with Autocage

Create Object with Autocage makes each selected mesh a deformable object inside an autocage: a new, light, closed cage around the mesh. The modifier is Deformable Object (Autocage). The cage is filled with tetrahedrons, and your mesh stays the render surface, exactly as you modelled it.

This is the best choice for a detailed model: the simulation cost depends on the cage, not on your mesh.

Your mesh Autocage

The autocage itself wraps any mesh, but the action still checks that your mesh is clean and closed. For an non-closed mesh, such as a model with separate eyes or holes, turn off the mesh check first.

Options:

Option Default What it does
Scale Gap 1 Size of the gaps the cage bridges, as a factor from 0.1 to 10.
Target Face Count 100 Number of cage triangles to aim for. More triangles follow the shape more closely and make more tetrahedrons.
Maximum Edge Length 100 A size limit for the tetrahedrons inside the cage. The cage’s triangles set the tetrahedron size, so raise Target Face Count for more tetrahedrons.
Breakable On On: the surface cracks open where the object breaks. Off: the surface stays whole.

To bring the cage closer to the mesh later, raise Target Face Count on the object’s Autocage panel. See The surface and contact.

Create Bare Object

Create Bare Object makes each selected mesh a deformable object with no render surface. The object shows its simulated tetrahedrons in see-through orange, with their wire, so a cage stands out from a finished object. The orange is the Deformable Cage material, and it renders too.

The action keeps your mesh as it was, in a copy named <mesh>_original. The copy holds the mesh and its materials. It is a child of the object, hidden in the viewport and in renders. The object itself works on its own copy of the mesh, which becomes the cage. The plugin never deletes the copy.

To render the object, give it a surface. Use Tetrahedral Mesh as Surface Mesh gives the cage the original’s materials. To use the original itself as the surface, show it with Alt+H or its eye in the Outliner, then use Add Surface Mesh to Object. Both take the orange away. See Add a surface to a bare object. Or pick a material in the Material properties: it replaces the orange.

The submenu picks the source:

Entry The mesh is The modifier
From Polygon Mesh A closed polygon mesh Deformable Object (Bare Polygon Mesh)
From Polygon Mesh with Autocage Any mesh, wrapped in an autocage Deformable Object (Bare Polygon Mesh with Autocage)
From Triangle Mesh A closed mesh that is already a clean triangle cage, such as one from Create Autocage Mesh Deformable Object (Triangle Mesh)
From Tetrahedral Mesh A tetrahedral mesh, stored as 4 triangles per tetrahedron Deformable Object (Tetrahedral Mesh)
From Non-Closed Polygon Mesh A non-closed polygon mesh, such as a plane Deformable Object (Non-Closed Polygon Mesh)

A tetrahedral mesh is what Extract Output Shapes writes as <object>_extracted_tetrahedral_mesh. See Extract Output Shapes.

Thin objects: From Non-Closed Polygon Mesh

From Non-Closed Polygon Mesh turns a non-closed polygon mesh into one layer of tetrahedrons with the Extrude tool: its Thickness, 0.1 by default, and its Direction, Both by default, are the action’s options. With its third option, Span Layers, it fills the space between two meshes with the Span Layers tool instead.

With Span Layers, select two meshes and make the one that gets the object active. Both meshes must be made of triangles, with the same vertices and faces: triangulate the first mesh, then copy it.

  1. Select the first mesh, press Tab, press A and choose Face > Triangulate Faces. Press Tab again.
  2. Press Shift+D and move the copy up.
  3. Bend or sculpt the copy as you like, but do not add, delete or reorder its vertices or faces.
  4. Click the copy, then Shift+click the first mesh so that it is active. Choose Object > Deformable > Create Bare Object > From Non-Closed Polygon Mesh and turn on Span Layers in the Adjust Last Operation panel.

The action refuses:

  • any other selection, with Span Layers needs exactly two selected meshes, one of them active;
  • a mesh with a face that is not a triangle, with Span Layers needs triangles: triangulate the mesh (Face > Triangulate Faces) before you copy it;
  • two meshes with different numbers of vertices or faces, with Span Layers needs two meshes with the same vertices and faces, such as a mesh and a moved copy of it.

Two meshes triangulated one at a time can get different triangles. The object is then made, but its Deformable Span Layers node shows Span Layers needs two layers with the same triangles, such as a triangulated mesh and a moved copy of it. For that and for the last two refusals, triangulate the first mesh as in step 1, delete the copy, copy the first mesh again with Shift+D and redo your change to the copy.

Create Autocage Mesh

Create Autocage Mesh adds the autocage of each selected mesh as a child object named <mesh>_autocage, drawn in see-through magenta. Unlike the other helpers, it renders. It makes no deformable object.

The <mesh>_autocage object is a triangle mesh cage. To simulate a cage you made or edited, use Create Bare Object > From Triangle Mesh, never From Polygon Mesh with Autocage, which would wrap the cage in another cage.

Use it to see a cage before you commit to it, or to shape a cage by hand:

  1. Select the <mesh>_autocage object and choose Object > Parent > Clear and Keep Transformation.
  2. Choose Object > Convert > Mesh. The cage is now a plain mesh that you can edit. Keep it closed and made of triangles.
  3. Choose Object > Deformable > Create Bare Object > From Triangle Mesh.
  4. In the Object properties, set Viewport Display > Display As to Textured. A helper object starts see-through.
  5. Select your model, Shift-click the cage object, and choose Object > Deformable > Add Surface Mesh to Object. With Breakable on, the action refuses a model that is not a clean, closed mesh: turn it off for such a model. See Add a surface to a bare object.

Add a surface to a bare object

Two actions give a bare object a render surface. Both take its orange away.

Add Surface Mesh to Object makes another mesh the render surface, such as the hidden <mesh>_original:

  1. Select the mesh that should render. To use the original, show it first with Alt+H.
  2. Shift-click the bare object, so it is selected and active.
  3. Choose Object > Deformable > Add Surface Mesh to Object.

The mesh becomes a child of the object, hidden in the viewport and in renders. With Breakable on, the default, the surface cracks open where the object breaks, and the action checks that the mesh is clean and closed first.

Use Tetrahedral Mesh as Surface Mesh gives each selected bare object a surface made of its own cage, or of the outer faces of its tetrahedrons when it has no cage, such as an extruded plane. The surface always breaks with the object. The outer faces of the tetrahedrons are shaded flat.

The surface takes the materials of the original, unless you picked a material for the object. From Polygon Mesh and From Triangle Mesh keep each face’s material. The other sources show the first material on every face.

Add Modifier > Deformable

In the Properties editor, Add Modifier > Deformable adds the same trees to the active mesh, with no options:

  • Deformable Object (Polygon Mesh), Deformable Object (Autocage), Deformable Object (Tetrahedral Mesh) and Deformable Object (Non-Closed Polygon Mesh);
  • Deformable Scene and Deformable Splinter;
  • Deformable Glue Region, Deformable Material Region and Deformable Density Region.

These entries do not check the mesh and do not add a Deformable Scene. Run Object > Deformable > Create Scene once if the scene has none.

Mesh checks before creating

By default, every create action checks each mesh first and refuses one that is not clean and closed. The warning names the mesh and the problems, such as Not verified: Sphere: non closed boundary (12). From Non-Closed Polygon Mesh checks the mesh too, but it may be non-closed.

The action also refuses an object with a mirrored or flat transform, such as a negative scale or a scale of 0. Apply the scale with Object > Apply > Scale, or set it to a positive value.

To find and fix the problems, see Verify Mesh. To turn the check off, see Preferences.

Duplicate Object

Duplicate Object copies each selected deformable object. The copy gets its own node tree and keeps the tool outputs, so nothing computes again. It joins every collection of the source, including a scene’s Objects collection and a glue region’s members.

Verify Mesh

Object > Deformable > Verify Mesh checks the one selected mesh. When it finds a problem, it switches to Edit Mode and selects every problem it found. A clean mesh stays in Object Mode. Its options, in the Adjust Last Operation panel, and what each problem means are on Verify Mesh.

The fixes in Blender, in Edit Mode:

Problem Fix
inverted normal, inward normals Mesh > Normals > Recalculate Outside.
co located vertices, near vertices Mesh > Clean Up > Merge by Distance.
degenerate edge, degenerate face Mesh > Clean Up > Delete Loose and Degenerate Dissolve.
non planar Face > Triangulate Faces.

Check Co-located Vertices

Object > Deformable > Check Co-located Vertices runs Verify Mesh with a gap threshold of 0.001. Fix what it finds with Mesh > Clean Up > Merge by Distance.

Find Intersecting Objects

Object > Deformable > Find Intersecting Objects adds to the selection every deformable object that overlaps a selected one, and Keep Intersecting Objects in Selection deselects the selected objects that overlap no other selected one. See Overlapping objects.

Assign a material

The material’s values are on the Material panel of the object’s modifier, with a Preset menu.

  1. Select one or more deformable objects or material regions.
  2. Choose Object > Deformable > Assign Material Preset and pick a preset, such as rubber or glass.

To copy one object’s material to others, select them, Shift-click the object to copy from so it is active, and choose Object > Deformable > Assign Material from Active.

Both actions need the object’s Material input to come from a Deformable Material node. When another node feeds it, the action names the object: Material must come from Deformable Material: <object>.

To keyframe a value, hover over it on the Material panel and press I.

Make Dynamic and Make Kinematic

These actions set the Object panel’s settings for all selected objects at once:

Action Sets
Object > Deformable > Make Dynamic Type to Dynamic
Object > Deformable > Make Kinematic Type to Kinematic
Object > Deformable > Enable Disabled off
Object > Deformable > Disable Disabled on

To animate a Kinematic object:

  1. Go to the start frame. Select the object and press I to keyframe its location.
  2. Go to a later frame, move the object, and press I again.
  3. Return to the start frame and play.

To release an object, set Type on the Object panel of its modifier to Kinematic at the start frame, hover over the field and press I; then set it to Dynamic at the frame of the release and press I again. See Release an object.

Make Breakable and Make Unbreakable

Object > Deformable > Make Breakable and Make Unbreakable set Clip Mode on the Prepare panel of the selected objects. See Make Breakable and Make Unbreakable.

Regions

Object > Deformable > Add New Region adds a region to the selected deformable objects: Passive, Material (with a submenu of presets) or Density. Add Glue Region adds a glue region around the selected objects. Make Mesh into Region makes a mesh of your own a region: select it, Shift-click the deformable object so it is active, and pick Passive, Glue, Material or Density.

Region What the action adds Where the object reads it
Passive A cube named Deformable Passive Region at the center of the selected objects, 1 unit wide The collection <object> Passive Regions, the Passive Regions setting on the Object panel
Material A cube named Deformable Material Region, 1 unit wide, with the Deformable Material Region modifier and a Material panel set to the preset The collection <object> Material Regions, the Material Regions setting on the Object panel
Density A cube at each object’s center, as a child, so the region moves with the object The collection <object> Density Regions, which the object’s Tetrahedralize reads
Glue A box named Deformable Glue Region that covers the selected objects Its own Members setting, a new collection Glue Members that holds the selected objects

A mesh made into a glue region gets a Members collection that holds the active object. Add the other objects to the collection in the Outliner.

Each kind of region shares one material, such as Deformable Glue Region, linked to the object, so a mesh you make into a region keeps its own materials under the color. A bare object takes its orange on its own copy of the mesh, and a hidden copy keeps your materials. See Create Bare Object.

A passive region does not follow the object on its own. When the object moves, parent the region to it: select the region, Shift-click the object, and choose Object > Parent > Object.

Two cubes made with Add New Region have the same mesh size however you scale them. To overlap material regions, scale the cube in Edit Mode, or apply its scale with Object > Apply > Scale.

For a density region, set Maximum Edge Length on the object’s Tetrahedralize panel first, then Density Scale on the cube’s modifier. See Density regions.

An object in a Material Regions collection that is not a material region is named on the Deformable Object node, and one in a Density Regions collection that is not a density region on the Tetrahedralize node.

Force fields

Blender’s force fields push deformable objects, as they push particles. Add one with Add > Force Field in the 3D Viewport, or turn a mesh into one in the Physics properties, and set it up there.

The Force Fields setting of the Deformable Scene is a collection. When it is empty, every force field of the view layer pushes the scene’s objects, as a cloth’s Effector Collection does. Set it to a collection to push with that collection’s fields only. Which fields push follows Blender’s own rule for its particles and cloth, in the viewport with Disable in Viewports and in a render with Disable in Renders:

  • With no collection, a field pushes nothing when it is disabled, or when every collection that holds it is disabled or excluded from the view layer, itself or through a parent collection.
  • With a collection, a field pushes nothing when that collection is disabled, or when every collection inside it that holds the field is. The field’s own setting and the view layer do not count.
  • Hiding a field or its collection in the viewport (the eye) leaves it pushing.

A field pushes every vertex of the tetrahedral mesh, inside and out, but those held by a Kinematic object, a passive region or the driven attribute. A held vertex saves nothing up: once released, it takes the field’s push from its first free frame. The simulation reads the fields on every frame, so keys on a field’s settings and on its object play, one frame late like every animated value. A field never pushes the object that holds it.

The plugin works out each field’s force with Blender’s own rules, from each vertex’s position and velocity in Blender units, as Blender does for a particle. The force is in newtons in simulation units, and the scene’s Scale never changes it, as it never changes Gravity. It adds up with the force attribute (see Driven vertices and forces). Like that attribute, a field pushes each vertex, so an object of real density needs a Strength in the thousands: a Wind field of Strength 20,000 with Flow 0 pushes as a force of 20,000 along the wind.

These settings apply: Shape (Point, Line, Plane, Surface, Every Point), Strength, Flow, Noise Amount, Seed, Affect Location, and every Falloff setting (Sphere, Tube or Cone, Z Direction, Power, Min and Max Distance, and the Tube’s and Cone’s own). A vertex has no rotation, so Affect Rotation does nothing. Wind Factor does nothing either, as for a particle: it weakens a push along a cloth’s surface. Nor does Absorption: Blender’s collision objects do not shield a deformable object from a field.

Field Supported Note
Force Yes Away from the field, or toward it with a negative Strength. Gravitation divides it by the squared distance.
Wind Yes Along the field’s Z axis. With Flow above 0, the object speeds up until it moves at Strength ÷ Flow.
Vortex Yes Around the field’s Z axis. A Point vortex pushes harder farther out; the other shapes also pull vertices in and hold them to the swirl’s speed.
Magnetic Yes Sideways to each vertex’s velocity: it bends the path of what moves and leaves still vertices alone.
Harmonic Yes Toward the field like a spring, to Rest Length from it, slowed by Damping.
Texture Yes By the texture as Blender samples it: along 0.5 less its color (RGB), down the slope of its intensity (Gradient) or along the curl of its color (Curl), measured over Nabla. A texture of an intensity alone, such as Clouds in Greyscale, pushes down its slope in every mode.
Turbulence Yes Each place its own way, by noise of Size, around the field object or in world space with Global. The noise stays where it is: move or animate the field to make it churn.
Drag Yes Against the velocity: Linear times the speed plus Quadratic times its square, each at most 2. Each follows its label, although Blender’s own particles swap the two.
Curve Guide No It sets a particle’s path over its lifetime, and a vertex has no lifetime.
Boid No It steers boid particles only.
Fluid Flow No It reads the velocity of a fluid domain’s grid, which Blender computes for its own solvers and gives no call to sample.
Charge No It acts by a particle’s own charge, which a vertex does not have, so it pushes no cloth either.
Lennard-Jones No It acts by a particle’s own size, which a vertex does not have, so it pushes no cloth either.

A field whose force is not a finite number at some vertex of an object it reaches, held vertices and Kinematic objects included, such as one whose Strength is so large that the push overflows, pushes no vertex at all on that frame. Its Deformable Scene says A field gives a force that is not a finite number, so it pushes nothing, with the field’s name. It says so once, and again only when the fields it names change.

Splinters

  1. Select the deformable object. It needs a render surface: for example, make it with Create Object with Autocage.
  2. Choose Object > Deformable > Create Splinters from Image. In the Adjust Last Operation panel, pick an Image Library pattern, such as cracked_glass. Or choose Object > Deformable > Import Splinter Mesh and pick a mesh, such as glass_shards.
  3. The action adds an object named Splinters, drawn in see-through cyan and hidden in renders, with the Deformable Splinter modifier. Its cells cover the bounding box of the selected objects, with a little to spare on every side. With one object selected, Splinters becomes its child, so it moves with it.
  4. Shift-click the deformable object, so both are selected.
  5. Choose Object > Deformable > Add Splinters to Object.
  6. Return to the start frame and play.

One Splinters object can serve several objects: select it and all of them in step 4.

The settings are on the Splinter panel of the Splinters object’s modifier. See Splinter settings. In Blender, a Mesh Library of Custom reads the node’s Mesh input, which you link in the node tree, and the box’s Origin is its smallest X, smallest Y and largest Z. A line drawing lies flat, as seen in the Top view, and its cells reach down from Origin Z by Size Z.

For an upright wall, the pattern should face the Front view instead. Select the Splinters object and set its Rotation X to 90°, with its location at 0. Then, on its Splinter panel, set Size and Origin to a box around the wall:

  • Size to one and a half times the wall’s width along X and its height along Z, and a little more than its thickness along Y;
  • Origin to the wall’s smallest X less a quarter of its width, its smallest Z less a quarter of its height, and minus its smallest Y plus half the extra thickness.

For a wall 4 m wide, 3 m high and 0.6 m thick, standing on the floor and centered on the origin, that is Size (6, 4.5, 0.8) and Origin (-3, -0.75, 0.4).

Start Splintered is in the Surface sub-panel of the Object panel.

Draw your own pattern

  1. Select the deformable object and choose Object > Deformable > Create Splinters from Image.
  2. In the Adjust Last Operation panel, set Image Library to Custom and pick your file in Image File. Any image format that Blender opens works, such as PNG or BMP.
  3. Continue from step 4 of Splinters.

With Custom and no file, the action stops with Image Library is Custom and no Image File is set. When the trace fails, the Deformable Splinter node shows why.

Inner material

  1. Make a material for the inside, such as raw stone or wood grain.
  2. On the object’s Prepare panel, pick it in Inner Material.

To check it without breaking the object, turn on Show Inner Faces in the Surface sub-panel of the Object panel. See Inner faces.

Change the surface

Edit the mesh at the start frame, in Edit Mode, as usual. When you go back to Object Mode, Deformable Prepare runs again, and the next play uses the new surface. While it runs, the status bar shows Deformable: Prepare (<object>) with how long it has run, such as 0:12, and a Cancel button.

To swap the surface of an object that has its own Deformable Prepare, edit the node tree: feed the Surface Mesh input of the Deformable Prepare node from another mesh, for example with an Object Info node set to Relative.

Before you play

  • Objects must not overlap at the start. Select an object and choose Object > Deformable > Find Intersecting Objects to select every object that overlaps it.
  • Keep an eye on the tetrahedron count. The status bar shows the count of the active object and its scene. See Count the tetrahedrons.