Skip to content

Installation

agentwood runs inside Blender's bundled Python, not a normal virtualenv — because the whole DSL is built on Blender's bpy module, which only exists in Blender's own interpreter.

The one rule that trips everyone up

Every DSL script is run by Blender in headless mode, and Python dependencies must be installed into Blender's Python, not your system python3 or a .venv. Mixing these up is the most common setup mistake.

1. Install Blender

Download Blender 4.0+ (tested on 5.x). On macOS, add a convenient alias:

echo 'alias blender="/Applications/Blender.app/Contents/MacOS/Blender"' >> ~/.zshrc && source ~/.zshrc

2. Find Blender's Python

blender --background --python-expr "import sys; print(sys.executable)"
# e.g. /Applications/Blender.app/Contents/Resources/5.1/python/bin/python3.13

3. Install dependencies into that Python

# use the path step 2 printed
/Applications/Blender.app/Contents/Resources/5.1/python/bin/python3.13 -m pip install numpy openai

How imports get found

dsl/bootstrap.py prepends your user site-packages to sys.path, so a pip install --user is also visible to Blender. dsl/actors.py imports it before importing openai.

4. Set your OpenAI key (dialog only)

export OPENAI_API_KEY=your_key_here

Only shots with dialog (.say(...)) need this — TTS audio is generated via OpenAI's speech API and cached on disk by a hash of the text, so re-runs are free. Most scenes need no key.

5. Get the assets and set files

Character rigs, the shared animation library, audio packs, HDR maps, and the set .blend files are large binaries tracked via Git LFS (or downloadable as a bundle).

git lfs install
git lfs pull

The assets/ folder is gitignored; download the asset bundle and unzip so the layout matches:

assets/characters/*.fbx          assets/bgm/   assets/sfx/
assets/animation_library.blend   assets/env_lights/
+ the four *_descriptions.json files

Then add the set's .blend — set.json already ships in the repo, so drop the heavy set.blend beside it:

sets/apartment_complex/set.blend

Verify it works

Run the fastest smoke test — one actor, one frame, no API key:

cd /path/to/agentwood
blender --background --python tests/test_int_solo.py

If it renders a frame into renders/… without errors, your pipeline is healthy.

Editing has lighter requirements

The post-production edit layer is pure ffmpeg (no Blender) — it only needs ffmpeg on your PATH, plus Pillow for captions. It can run under a plain python3.

Next: Your First Scene