A zot extension and Blender add-on that let an agent build and inspect 3D scenes through Blender's Python API. The bridge exposes structured operations instead of arbitrary Python execution.

The extension registers these tools:

• blender_scene_info
• blender_create_primitive
• blender_transform_object
• blender_sculpt_mesh
• blender_voxel_remesh
• blender_add_modifier
• blender_set_material
• blender_create_camera
• blender_create_light
• blender_delete_object
• blender_undo
• blender_save
• blender_render_preview

Rendered previews are returned to zot as images, so the agent can inspect a result and iterate.

blender_sculpt_mesh applies one or more deterministic brush dabs using world-space points. It supports inflate, smooth, grab, flatten, and pinch brushes, configurable falloff and iterations, and optional X symmetry. grab uses a world-space direction; flatten uses a world-space plane normal.

blender_voxel_remesh rebuilds topology before or between sculpting passes. Its voxel size is measured in object-space Blender units, so apply or account for object scale when choosing a value. Both operations participate in Blender's undo stack.

Example request:

{
  "object": "Head",
  "brush": "grab",
  "points": [[0.35, -0.8, 2.2]],
  "radius": 0.3,
  "strength": 0.5,
  "direction": [0.0, -0.08, 0.0],
  "symmetry_x": true
}

• zot with extension support
• Blender 3.6 or newer
• Python 3.9 or newer for the zot-side process

No third-party Python packages are required.

Install the extension directly from GitHub:

zot ext install https://github.com/patriceckhart/zot-blender
zot ext list

The zot ext list output shows the local installation directory. You will use the blender_addon.py file from that directory when setting up Blender.

1. Open Blender.
2. Open Edit > Preferences > Add-ons.
3. Choose Install from Disk and select blender_addon.py from the installation directory shown by zot ext list.
4. Enable Zot Blender Bridge.
5. In a 3D View, open the sidebar with N, select Zot, and confirm that it is listening on 127.0.0.1:8765.

The bridge only binds to localhost. Blender API operations are queued onto Blender's main thread because bpy is not thread-safe.

Restart zot after installation, then ask it something like:

Use Blender to create a low-poly pedestal from cubes, give it a stone material, add a camera and area light, then render a preview.

After updating the extension, reinstall or reload blender_addon.py in Blender as well. Restarting only the bridge does not reload Python source.

The listener accepts only local connections, but any process running as your user could connect to the default unauthenticated port. To require a shared token:

1. Set Shared token in Blender under Preferences > Add-ons > Zot Blender Bridge.
2. Click Restart Bridge in the Zot sidebar.
3. Start zot with the same value:

ZOT_BLENDER_TOKEN='choose-a-long-random-value' zot

Do not commit the token. The extension also recognizes:

• ZOT_BLENDER_HOST, default 127.0.0.1
• ZOT_BLENDER_PORT, default 8765
• ZOT_BLENDER_TIMEOUT, default 55 seconds

The Blender add-on deliberately binds only to 127.0.0.1. ZOT_BLENDER_HOST exists for controlled forwarding setups, but changing the add-on bind address requires code changes.

• The agent cannot execute arbitrary Python through this extension.
• Saving an unnamed scene requires an absolute path ending in .blend.
• Saving can overwrite an existing .blend file at the requested path.
• Model changes use Blender's undo stack where Blender supports it.
• Preview renders use a temporary PNG that is deleted after it is returned.
• Closing or disabling the add-on stops the local server.

Keep important scenes under versioned backups and review tool calls before allowing file saves.

The zot-side bridge and wire protocol can be tested without Blender:

python3 -m unittest discover -s tests -v
python3 -m py_compile zot_blender.py blender_addon.py

A complete integration test still requires Blender because blender_addon.py imports bpy and performs all scene changes on Blender's main thread.

MIT