You are viewing the documentation for Deformable v0.4.0, an older version. Read the latest, v0.9.0
Engine
Troubleshooting
What to check, by symptom, when nothing moves, an object is left out, a mesh is refused, objects behave oddly or a render looks wrong.
On this page
- Nothing moves when I play
- An object stays still at Play
- The create action refuses my mesh
- A tool shows an error
- Objects jump apart, or stick together, at the start
- Objects pass through each other
- An object rests above the floor
- An object rests a little into the floor
- Stacked objects slowly sink into each other
- It breaks too much, or not at all
- Cracks show before the object breaks
- My object is too heavy
- The surface looks faceted
- The simulation is slow
- The render shows the rest shape or the wrong frame
- Get help
Most problems show a message: after an action, on the tool or the object it belongs to, or while you play. Start there. This page lists the common problems by symptom, and what to change in the scene. Each plugin’s own troubleshooting page lists its messages and where it shows them.
Nothing moves when I play
Check these in order:
- Is there a Deformable Scene, and does it take the object? Nothing simulates without a Deformable Scene, and an object that no Deformable Scene takes does not move. The plugin names such objects, five at most.
- Did you play from the start frame, frame by frame? Jumping ahead does not simulate the frames in between, and a frame that playback skips is never simulated. After a change, return to the start frame and play again. See The start frame.
- Is a substep too long? Raise Substeps on the Deformable Scene: 2 or more at 24 frames per second. See Substeps.
- Is a tool still running, waiting or cancelled? Wait for it, or choose Update Now. See The tools.
- Is the object held? Type must be Dynamic and Disabled off. Check Disable on the Deformable Scene, and its keys.
- Was the object left out? The plugin leaves out an object it cannot simulate, and the object hangs still. See An object stays still at Play.
- Is it over the Free license’s limit? Under the Free license, a Deformable Scene simulates up to 2,500 tetrahedrons. The objects that do not fit stay still, the rest of the scene runs, and the plugin says Free license: the scene would simulate 3,120 tetrahedrons; the limit is 2,500 per scene. See Use fewer tetrahedrons.
See it in: Blender · Maya · C · Rust · Python
An object stays still at Play
An object that hangs in mid-air while the others fall was left out of the simulation. The plugin names each object left out, from every Deformable Scene, and says why, such as Left out of the simulation: Bolt (its tetrahedrons are too small). See Troubleshooting. The other objects simulate, and Simulate Frame Range and Bake Simulation go on without it. A create action warns you as it makes such an object: Created Bolt: 2,258 tetrahedrons; scene total 2,258. Play will leave it out: its tetrahedrons are too small. See Troubleshooting.
| The reason | Fix |
|---|---|
| its tetrahedrons are too small | The object is small and detailed, such as a bolt or a bevelled cube under about 2.5 cm, and its tetrahedrons are too small to simulate. See the fixes below. |
| it has flat tetrahedrons | The two layers of a bare object made with Span Layers touch. Move them apart, or use Create Object with Autocage. |
| it has inside-out tetrahedrons | The extruded shell of a bare object made from a non-closed polygon mesh is too thick where the mesh bends sharply. Lower Thickness on its Extrude, or use Create Object with Autocage. |
| three tetrahedrons share a face | The tetrahedral mesh is broken. Make the tetrahedrons with the plugin’s tools, or use Create Object with Autocage. |
| it has no tetrahedrons | The tools before the object made none. Fix the first error in the chain. |
| its scale is negative or zero | Freeze or apply the object’s scale, or set it positive. |
For tetrahedrons that are too small, try these. They were checked on 1 cm cubes and on a 2 cm cube with a 2 mm bevel, which Create Object from Polygon Mesh makes too small (a 2 cm cube with a 4 mm bevel simulates):
- Use an autocage with fewer faces. Choose Create Object with Autocage. If Play would leave it out too, lower Target Face Count, such as to 50 or 20: a coarser cage makes larger tetrahedrons, and a higher count makes smaller ones. Then play from the start frame.
- Simplify the mesh. Decimate it, then create the object. A decimated mesh can have thin triangles that the create action refuses, such as small angle (9): then use an autocage with fewer faces instead.
- Raise Scale on the Deformable Scene, such as to 10. The simulation then sees every object ten times larger, so the whole scene falls and bounces like one ten times its size. Modelling the scene larger and lowering Scale to match does not help: the simulation sees the same sizes. See Scale.
See it in: Blender · Maya · C · Rust · Python
The create action refuses my mesh
A create action checks each mesh first and names its problems, such as Not verified: Sphere: non closed boundary (12). Fix them, or wrap the mesh in an autocage. Verify Mesh selects every problem it finds. The full list of problems and fixes is in Verify Mesh.
The action also refuses an object with a mirrored or flat transform, such as a negative scale or a scale of 0.
For a model that is not meant to be closed, such as a character with separate eyes, wrap it in an autocage and turn off Verify Meshes Before Creating Objects in the plugin’s preferences.
See it in: Blender · Maya · C · Rust · Python
A tool shows an error
A tool with an error shows it, and its output is empty, so the object may show nothing. Tools after it may show an error too: fix the first one in the chain.
| Message | Tool | Fix |
|---|---|---|
| INVALID_CAGE: cage not closed, outward and free of self-intersections | Tetrahedralize | The cage has holes, faces pointing inward or faces that cross. Fix the mesh, or use an autocage. |
| Tetrahedralize needs a triangle cage | Tetrahedralize | Put a Triangulate or an Autocage before it. |
| Extrude needs a triangle mesh | Extrude | Put a Triangulate with Closed Boundary off before it. |
| Span Layers needs two layers with the same triangles, such as a triangulated mesh and a moved copy of it | Span Layers | Triangulate the first mesh, delete the copy, copy the first mesh again and redo your change to the copy. |
| The world matrix is mirrored or flat (determinant ≤ 0) | The object | The object has a negative or zero scale. Set it positive. |
| Free license: this would simulate 3,120 tetrahedrons; the limit is 2,500 per scene | The object | Under the Free license, the object would take its scene past 2,500 tetrahedrons, so it stays still. Use fewer tetrahedrons, or activate a license. See The tetrahedron limit. Once an activation or a renewal succeeds, it simulates again by itself. |
| Developer trial ended — Buy license | The license status of a program built with an SDK | The program’s Developer trial key ended, and the program runs under the Free license, with its limit. Start the program again with a full Developer license key. See Developer license. |
See it in: Blender · Maya · C · Rust · Python
Objects jump apart, or stick together, at the start
Deformable objects that overlap at the start frame push apart hard, or get glued when Glue All is on. Find Intersecting Objects selects every object that overlaps the selected one. Then move them apart.
To glue objects on purpose, make them overlap a little and use Glue All or a glue region.
See it in: Blender · Maya · C · Rust · Python
Objects pass through each other
Objects in different Deformable Scenes do not collide. Check which Deformable Scene takes each object. See More than one Deformable Scene.
An object rests above the floor
The tetrahedrons collide, not your mesh. An autocage sits a little outside the mesh, so the mesh can rest a few centimetres up. Raise Target Face Count on its Autocage. See The surface and contact.
See it in: Blender · Maya · C · Rust · Python
An object rests a little into the floor
Resting objects keep a small overlap with a floor or a Kinematic object they rest on, which keeps resting contact calm. The overlap is about 2 cm, or less on an object whose tetrahedrons are thinner than about 4 cm: a 5 cm cube rests about 1.3 cm in, and a 2 cm cube about 5 mm. A large object hides it. A small prop shows it. To fix it:
- Raise Scale on the Deformable Scene, such as to 10. The overlap is about 0.02 simulation units (2 cm at Scale 1), so at Scale 10 it is about 2 mm in your scene. The simulation then sees every object ten times larger, so the whole scene falls and bounces like one ten times its size. Modelling the scene ten times larger at Scale 1 does the same. Modelling it larger and lowering Scale to match does not help: the simulation sees the same sizes. See Scale.
- Raise the floor under objects of about 10 cm and more, which rest 2 cm in: move the Kinematic floor up 2 cm, hide it in renders, and render a plain plane where its top was.
See it in: Blender · Maya · C · Rust · Python
Stacked objects slowly sink into each other
This is how resting contact between two moving objects works: only a Kinematic object pushes an object back out of an overlap, so two Dynamic objects resting on each other slow each other down but slowly sink in. Make the bottom one Kinematic, or glue them. See Kinematic objects and Glue regions.
See it in: Blender · Maya · C · Rust · Python
It breaks too much, or not at all
- Too much: raise Toughness, or pick a tougher preset. To keep the surface whole, choose Make Unbreakable.
- Not at all: lower Toughness. Check that it is not 0 and that the preset does not start with
unbreakable_. - Too few, too coarse cracks: use more, smaller tetrahedrons. Make a finer cage with a higher Target Face Count or a lower Maximum Area, or add a density region where it breaks and lower Maximum Edge Length as that section shows.
See it in: Blender · Maya · C · Rust · Python
Cracks show before the object breaks
Show Inner Faces is on, on the object. Turn it off. Start Splintered also shows the cut faces of splinters from the start.
See it in: Blender · Maya · C · Rust · Python
My object is too heavy
An autocage is filled solid, so a hollow object made with Create Object with Autocage, such as a cup, a box or a pipe, weighs as much as its whole outline, and nothing can fall into it. Make it from its walls instead, or keep the autocage and set Density to the real mass divided by the cage’s volume. See Hollow and thin-walled objects.
See it in: Blender · Maya · C · Rust · Python
The surface looks faceted
Use Tetrahedral Mesh as Surface Mesh and bare objects show flat faces. For a smooth surface, use your own mesh as the render surface: Create Object with Autocage, or Add Surface Mesh to Object. See Render surfaces.
See it in: Blender · Maya · C · Rust · Python
The simulation is slow
- Count the tetrahedrons. The cost grows with them. A few hundred per object is often enough. See How many tetrahedrons.
- Time the steps. From the command line, each simulated frame prints how long each Deformable Scene’s step took.
- Lower Substeps if your scene allows it. The default, 8, suits most scenes.
- Turn off Self Collision on objects that never fold or break, such as floors.
- Fill the cache in one go with Simulate Frame Range, then scrub freely, the start frame included. Change nothing the simulation reads, or the next play simulates again.
- While you edit a heavy mesh, choose Wait on Update, change what you need, then Update Now.
See it in: Blender · Maya · C · Rust · Python
The render shows the rest shape or the wrong frame
A render simulates only when it starts at the start frame and runs frame by frame. To render one frame, or part of the range, bake first and save the file.
A render that starts where the simulation cannot reach says so, such as Frame 10 renders Cube without the simulation: render from frame 1, or bake first. It names only the objects that Bake Simulation has not baked up to that frame.
Get help
If you are stuck, email support@tangerina.io. To report a bug, include what Report a bug lists: the versions, your steps, the messages you see and a small scene file. Copy Support Info in each plugin copies the versions and the license status for you: paste them at the top of your email.