﻿---
title: Command line and scripting
description: Install, simulate and render from a terminal, and build Deformable scenes with Python scripts in Blender.
url: https://help.tangerina.io/deformable/v0.3.1/user-guides/blender/command-line-and-scripting/
---

# Command line and scripting – Blender Plugin – Deformable v0.3.1

Everything in the **Object > Deformable** menu is a Blender operator, so you can run it from a Python script, and
Blender can simulate and render a scene without opening its window. This page is for pipeline work: render farms,
batch jobs and scene-building scripts.

## Install from a terminal

Install and enable the plugin in your user Blender, with the `.zip` file you downloaded, such as
`deformable-blender-v0.1.0-linux-x64.zip`:

```sh
blender --command extension install-file -r user_default -e deformable-blender-v0.1.0-linux-x64.zip
```

Restart Blender after you reinstall the plugin: a running Blender keeps the version it loaded.

## Render from a terminal

Background mode (`-b`) runs Blender without a window. The plugin simulates each frame as the render reaches it, and
a baked scene renders its bake:

```sh
blender -b scene.blend -a
```

Render the whole range from the start frame. To render part of the range from a saved bake, see
[Render from the command line](https://help.tangerina.io/deformable/v0.3.1/user-guides/blender/playback-and-baking/#from-the-command-line).

The plugin prints what it does, each line starting with `Deformable:`, so a render log shows it:

| Line | When |
|---|---|
| `Deformable: Scene: frame 12 of 48 in 2.41 s · Deformable Scene step 2.30 s, mean 2.35 s` | A frame was simulated, in that many seconds. Each Deformable Scene that stepped follows, with how long its step took and the mean step since the start frame. |
| `Deformable: Scene: 47 frames simulated in 113.20 s` | The simulation reached its end frame. |
| `Deformable: Scene: Frame 10 renders Cube without the simulation: render from frame 1, or bake first` | The render starts where the simulation cannot reach, and the named objects are not baked. |
| `Deformable: Sphere: Deformable Tetrahedralize: <message>` | A node shows a new error or warning. |
| `Deformable: Scene: <message>` | The status bar would show a new message, such as **Play from the start frame**. See [Troubleshooting](https://help.tangerina.io/deformable/v0.3.1/user-guides/blender/troubleshooting/). |
| `Deformable: Created Sphere: 212 tetrahedrons; scene total 218` | A create action's object was counted, once its tools finished. |
| `Deformable: Scene: Left out of the simulation: Bolt (its tetrahedrons are too small). See Troubleshooting.` | Play left the named objects out and simulates the others. See [An object stays still at Play](https://help.tangerina.io/deformable/v0.3.1/user-guides/blender/troubleshooting/#an-object-stays-still-at-play). |

A message is printed when it appears, not again on each frame.

## Simulate from a terminal

`--python-expr` runs a line of Python after the file loads. This command plays every frame from the start frame to
the end frame, as **Simulate Frame Range** does:

```sh
blender -b scene.blend --python-expr "import bpy; bpy.ops.object.deformable_simulate_frame_range()"
```

The cache lives only in memory, so this command saves nothing. Use it to time a simulation, or to check that a file
simulates on a render node before you render it. It prints a line for each frame, with about how long the frames left
take, and one for the whole range:

```text
Deformable: Scene: frame 1 of 48 in 0.04 s · less than a minute left
Deformable: Scene: frame 2 of 48 in 2.61 s · about 1 min left
…
Deformable: Scene: frame 48 of 48 in 2.38 s
Deformable: Scene: Simulated frames 1–48 in 1 min 55 s
```

It stops where the status bar would show a message that stops the simulation, prints where and why, such as
`Deformable: Scene: Stopped at frame 1: No Deformable Scene: choose Object > Deformable > Create Scene`, and returns
`{'CANCELLED'}`. Advice, such as objects that no Deformable Scene takes, is printed and the range goes on.

## Build a scene with a script

This script builds the scene of [Getting started](https://help.tangerina.io/deformable/v0.3.1/user-guides/blender/getting-started/): a brick sphere that
falls onto a floor. It sets one modifier setting, simulates 48 frames, prints what the sphere looks like at the end,
and saves the file. Save it as `drop_sphere.py` and run it in background mode:

```sh
blender -b --python drop_sphere.py
```

```python
import os

import bpy


def set_input(blender_object, name, value):
    """Set the Deformable modifier setting with this name, as on the modifier panel."""
    for modifier in blender_object.modifiers:
        if modifier.type != "NODES" or modifier.node_group is None:
            continue
        for item in modifier.node_group.interface.items_tree:
            if item.item_type == "SOCKET" and item.in_out == "INPUT" and item.name == name:
                getattr(modifier.properties.inputs, item.identifier).value = value
                return
    raise KeyError(f"{blender_object.name} has no setting {name}")


# Start from an empty scene, 48 frames long.
bpy.ops.wm.read_homefile(use_empty=True)
scene = bpy.context.scene
scene.frame_end = 48

# A UV sphere 3 m up, in an autocage, made of brick.
bpy.ops.mesh.primitive_uv_sphere_add(location=(0.0, 0.0, 3.0))
sphere = bpy.context.active_object
bpy.ops.object.deformable_create_object_with_autocage()
bpy.ops.object.deformable_assign_material_preset(preset="brick")

# A 20 m floor, extruded 0.2 m down, that does not move, rendered with the plane's materials.
bpy.ops.mesh.primitive_plane_add(size=20.0)
bpy.ops.object.deformable_create_bare_object(source="NON_CLOSED_POLYGON_MESH", thickness=0.2, direction="Down")
bpy.ops.object.deformable_use_tetrahedral_mesh_as_surface_mesh()
bpy.ops.object.deformable_set_type(type="Kinematic")

# The first create action added the Deformable Scene object.
set_input(bpy.data.objects["Deformable Scene"], "Substeps", 10)

# Let the plugin run its tools, then simulate every frame.
for _ in range(10):
    for blender_object in scene.objects:
        blender_object.update_tag()
    bpy.context.view_layer.update()
scene.frame_set(scene.frame_start)
bpy.ops.object.deformable_simulate_frame_range()

evaluated = sphere.evaluated_get(bpy.context.evaluated_depsgraph_get())
surface = evaluated.to_mesh()
lowest = min((evaluated.matrix_world @ vertex.co).z for vertex in surface.vertices)
print(f"Frame {scene.frame_current}: lowest point {lowest:.2f} m, {len(surface.polygons)} faces")
evaluated.to_mesh_clear()

bpy.ops.wm.save_as_mainfile(filepath=os.path.abspath("drop_sphere.blend"))
```

After the plugin's line for each frame, it prints a line such as this one. The sphere lies broken on the floor, and
its surface has gained the faces of the cracks:

```text
Frame 48: lowest point -0.02 m, 4495 faces
```

A few things to know when you script the plugin:

- **The actions work on the selection.** Each create action selects what it made, so the next action applies to it.
  Bake Simulation and Free Simulation are the exceptions: they act on every deformable object of the scene.
- **The tools run after a change.** In Blender's window, the plugin runs its tools in the background once your script
  returns, so build the scene in a script, then play. In background mode, it runs them only when Blender updates
  the scene, which is why the script tags every object and updates the view layer a few times before it simulates.
- **A saved file needs no update.** The plugin stores every tool output in the file. A script that opens a saved file
  can simulate or render right away, as in the commands above.
- **Settings live on the modifier.** `set_input` finds a setting by the name the modifier panel shows. A name used
  by two panels, such as **Run**, sets the first one.

## The actions as operators

Every action is in `bpy.ops.object`. Its options match the fields of the **Adjust Last Operation** panel.

| Action | Operator | Options |
|---|---|---|
| Create Scene | `deformable_create_scene` | |
| Create Primitive Object | `deformable_create_primitive_object` | `primitive`: `CUBE`, `SPHERE`, `CYLINDER`, `CONE`, `PYRAMID` or `ICOSPHERE` |
| Create Object from Polygon Mesh | `deformable_create_object_from_polygon_mesh` | `maximum_area`, `quality`, `maximum_edge_length`, `anisotropy_scale`, `anisotropy_direction` |
| Create Object with Autocage | `deformable_create_object_with_autocage` | `scale_gap`, `target_face_count`, `maximum_edge_length`, `breakable` |
| Create Bare Object | `deformable_create_bare_object` | `source`: `POLYGON_MESH`, `POLYGON_MESH_WITH_AUTOCAGE`, `TRIANGLE_MESH`, `TETRAHEDRAL_MESH` or `NON_CLOSED_POLYGON_MESH`; `thickness`; `direction`: `Both`, `Up` or `Down`; `span_layers` |
| Create Autocage Mesh | `deformable_create_autocage_mesh` | |
| Add Surface Mesh to Object | `deformable_add_surface_mesh` | `breakable` |
| Use Tetrahedral Mesh as Surface Mesh | `deformable_use_tetrahedral_mesh_as_surface_mesh` | |
| Create Splinters from Image | `deformable_create_splinters_from_image` | `image_library`, `image_file`, `allow_nonconvex` |
| Import Splinter Mesh | `deformable_import_splinter_mesh` | `mesh_name` |
| Add Splinters to Object | `deformable_add_splinters_to_object` | |
| Make Breakable, Make Unbreakable | `deformable_set_breakable` | `breakable`: `True` or `False` |
| Make Dynamic, Make Kinematic | `deformable_set_type` | `type`: `Dynamic` or `Kinematic` |
| Enable, Disable | `deformable_set_enabled` | `enabled`: `True` or `False` |
| Wait on Update, Don't Wait on Update | `deformable_set_wait` | `wait`: `True` or `False` |
| Update Now | `deformable_update_now` | |
| Duplicate Object | `deformable_duplicate_object` | |
| Assign Material Preset | `deformable_assign_material_preset` | `preset`, such as `"rubber"` |
| Assign Material from Active | `deformable_assign_material_from_active` | |
| Add Glue Region | `deformable_add_glue_region` | |
| Add New Region | `deformable_add_region` | `kind`: `PASSIVE`, `MATERIAL` or `DENSITY`; `preset` for a material region |
| Make Mesh into Region | `deformable_make_mesh_into_region` | `kind`: `PASSIVE`, `GLUE`, `MATERIAL` or `DENSITY`; `preset` for a material region |
| Verify Mesh | `deformable_verify_mesh` | `angle_threshold_degrees`, `gap_threshold`, `planar_threshold`, `check_uv_consistency`, `uv_threshold`, `same_uv`, `convex`, `closed_boundary`, `self_intersection`: `SKIP`, `PER_ISLAND` or `FULL` |
| Check Co-located Vertices | `deformable_check_co_located_vertices` | |
| Find Intersecting Objects | `deformable_find_intersecting_objects` | |
| Keep Intersecting Objects in Selection | `deformable_keep_intersecting_objects` | |
| Simulate Frame Range | `deformable_simulate_frame_range` | |
| Bake Simulation | `deformable_bake_simulation` | |
| Free Simulation | `deformable_free_simulation` | |
| Extract Output Shapes | `deformable_extract_output_shapes` | |
| Properties > Add Modifier > Deformable | `deformable_add_modifier` | `entry`: the menu entry's name, such as `"Deformable Object (Autocage)"` |

An action that cannot run with the current selection raises a `RuntimeError` that says what to select, such as
**Select one or more deformable objects**. One that refuses its input, such as a mesh that fails the check, reports a
warning and returns `{'CANCELLED'}`. Most actions report what they did, such as **Made 2 objects Kinematic**, and
Blender prints a report in the terminal as `Info: Made 2 objects Kinematic`.
