blender

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: blender
description: 'Remote-control a running Blender by Python script through a small local bridge — build and edit 3D scenes live: mesh and curve modeling with bmesh and modifiers, materials and shader node graphs, geometry nodes, lighting and cameras, keyframe animation, rigging, physics simulation, Grease Pencil, the video sequencer, and EEVEE/Cycles rendering, then measure the result, grab viewport screenshots, and export glTF / FBX / USD / Alembic / OBJ / STL. Use whenever the user wants to create or edit a 3D scene, model, animation, product shot, or .blend file, render an image or video, convert or export a 3D asset, or says "Blender", "3D model", "render this", "make a 3D animation", "Blender scene", "export to glTF" — even if they don''t mention scripting.'
summary: "remote-control a running Blender by Python via a local bridge — bmesh/modifier modeling, shader and geometry nodes, animation, rigging, physics, Grease Pencil and the VSE, EEVEE/Cycles stills and video, glTF/FBX/USD/OBJ/STL export"
category: 3d
risk: medium
tags:
    - blender
    - 3d
    - rendering
    - animation
    - modeling
    - scripting
---

# Blender Control

Blender (`/Applications/Blender.app`) is scriptable in **Python** against `bpy`, `bmesh` and
`mathutils`. Drive it through the **Blender Bridge** — a script running inside a *running*
Blender GUI that executes whatever build script is POSTed to `127.0.0.1:8736`. Because it
runs in the live session on the main thread, `bpy.data` writes are legal, the viewport
updates as you build, and viewport screenshots work. Everything documented here was executed
and verified on **Blender 5.2.0 LTS** (bundled Python 3.13).

- [scripts/blender-bridge.py](scripts/blender-bridge.py) — the bridge to run inside Blender.
- [scripts/blender-send.sh](scripts/blender-send.sh) — send a `.py` file (or `-c 'inline'`)
  and print its captured output; `--ping` checks it's up, `--state` dumps the scene as JSON.
- [scripts/example-product-shot.py](scripts/example-product-shot.py) — model → material →
  three-point light → camera → measure → render.
- [scripts/example-animated-logo.py](scripts/example-animated-logo.py) — text → keyframes →
  geometry-nodes scatter → frame sequence → video.

**Read [references/gotchas.md](references/gotchas.md) before writing anything.** Blender's
API changed substantially in 5.x and most of what a model has memorised — `action.fcurves`,
`scene.node_tree`, `mod["Socket_2"]`, `BLENDER_EEVEE_NEXT` — is now wrong.

## The control loop

1. **User starts the bridge** (one-time). This cannot be done remotely — if
   `bash scripts/blender-send.sh --ping` gets no answer, ask the user to do one of:
   - copy [scripts/blender-bridge.py](scripts/blender-bridge.py) to
     `~/Library/Application Support/Blender/5.2/scripts/startup/blender_bridge.py` and
     restart Blender — it then starts automatically on every launch (**recommended**), or
   - open the **Scripting** workspace, paste the file into the text editor, press
     **Run Script** (⌥P) — lasts for that session, or
   - install it as an add-on via Preferences ▸ Add-ons ▸ Install.

   A successful ping returns
   `{"ok": true, "bridge": "blender", "version": "5.2.0 LTS", "file": null, ...}`.
2. **Look before you build**: `bash scripts/blender-send.sh --state` returns objects and
   types, collections, materials, node groups, frame range, resolution, engine and whether
   the file has unsaved changes — cheaper than writing a script to ask.
3. **Write a build script** to the scratchpad, starting from the cheatsheet below and the
   right reference file.
4. **Send it**: `OUT=/path/to/outdir bash scripts/blender-send.sh /path/build.py`. The bridge
   runs it in the live session and returns the script's **captured stdout**; on error it
   returns the **traceback** and the sender exits non-zero. `BLENDER_SEND_TIMEOUT=900`
   (seconds) for heavy renders and bakes.
5. **Feedback**: returned stdout first; `metrics(...)` for structured g