blender-cli

Agent-friendly procedural map generation SDK built on Blender's Python API.

blender-cli provides a Python SDK and a CLI for building 3D scenes declaratively through a project.json file — procedural terrain, PBR materials, object placement with snap/raycast, GPU-instanced scatter, cameras, lights, and Bevy/Blenvy ECS component embedding — then exports to GLB.

Installation

Requires Python 3.13+ and uv.

# Install from source
uv pip install .

# Or run directly with uvx (no install needed)
uvx --from . blender-cli

# From a git repo
uvx --from git+https://github.com/julien-blanchon/blender_cli blender-cli

Quick start

CLI

# Create a project
blender-cli project new --name "Alpine" --profile hd1080p -o project.json

# Add materials
blender-cli material add --project project.json grass --pbr-folder ./textures/grass/ --tiling 4 4

# Build terrain
blender-cli terrain init --project project.json --width 512 --height 512 --seed 42
blender-cli terrain op --project project.json noise type=fbm amp=15 freq=0.008 octaves=6
blender-cli terrain op --project project.json smooth radius=3 iters=1
blender-cli terrain material --project project.json grass

# Place objects (snapped to terrain)
blender-cli project add-object --project project.json Wall \
  --primitive box --primitive-params '{"size":[10,0.3,3]}' \
  --at 50 50 0 --material rock --snap -Z --tags building

# Add camera and light
blender-cli project add-camera --project project.json Main --at 0 -50 30 --lens 35
blender-cli project add-light --project project.json Sun --type SUN --energy 5.0

# Export to GLB
blender-cli project export --project project.json --out scene.glb

# Render a preview
blender-cli render still --glb scene.glb --project project.json --preset iso --out preview.png

Python SDK

from blender_cli import ProjectFile

pf = ProjectFile.new("Alpine", profile="hd1080p")

# Materials
pf.add_material("grass", pbr_folder="./textures/grass/", tiling=[4, 4])
pf.add_material("rock", pbr_folder="./textures/rock/", tiling=[2, 2])

# Terrain
pf.set_terrain(512, 512, seed=42)
pf.terrain_op("noise", type="fbm", amp=12.0, freq=0.008, octaves=6)
pf.terrain_op("smooth", radius=3, iters=1)
pf.terrain_op("erode", type="hydraulic", iterations=40)
pf.set_terrain_material("grass")

# Anchors (named spatial references)
pf.add_anchor("village", [256, 256, 0], annotation="center")

# Objects (snapped to terrain at export)
pf.add_object("Cottage", asset_path="./assets/cottage.glb",
              location=pf.anchor_pos("village"), tags=["building"], snap=True)

# Camera, light
pf.add_camera("Main", location=[0, -50, 30], look_at=[256, 256, 0], lens=35)
pf.add_light("Sun", "SUN", energy=5.0, rotation=[0.5, 0.0, 0.0])

# Export
pf.save("project.json")
pf.export_glb("scene.glb")

Architecture

project.json  ──[export_glb]──►  scene.glb
     ▲                              │
     │                              │
     └────────[import_glb]──────────┘

Everything goes through project.json as the single source of truth. Edit it via the Python SDK (ProjectFile) or the CLI (blender-cli), then export to GLB. You can also import an existing GLB back into a project file.

Features

Terrain

Procedural heightfield terrain built from a chain of operations:

Materials

PBR texture folders (auto-detects diffuse, normal, roughness, AO, displacement) or flat colors with metallic/roughness control.

Objects & Primitives

Primitives: box, plane, cylinder, sphere, cone, torus. Also supports prefab GLB assets and empties.

Snap system — raycast objects onto geometry at export time:

Filter snapping with target_tags and exclude_tags.

Anchors

Named spatial reference points. Place objects, cameras, and lights relative to anchors instead of hardcoded coordinates:

pf.add_anchor("gate", [100, 100, 0])
pf.add_object("Tower", location=pf.anchor_pos("gate", [5, 0, 0]), snap=True)

Instances

GPU-instanced scatter groups for vegetation, rocks, and props with per-point rotation and scale.

Cameras

Static cameras or animated paths (orbit, dolly, flyover). Ghost cameras are excluded from GLB export and used only for debug renders.

Lights

SUN, POINT, SPOT, AREA light types. Ghost lights for debug previews.

Bevy / Blenvy Integration

Embed Bevy ECS components directly in the GLB. The SDK validates component names against a Bevy registry.json:

blender-cli blenvy set-registry --project project.json assets/registry.json
blender-cli blenvy add-component --project project.json Ground RigidBody Static
blender-cli blenvy validate --registry assets/registry.json --project project.json

Render & Debug

Render stills from named cameras or presets (top, iso). Supports:

• Tag-based show/hide (--hide-tag ceiling for dollhouse views)
• Wireframe mode
• Highlight + ghost mode
• Decomposition render (flat colors per object/tag)
• Multi-pass (beauty, depth, normal)

Session

Undo/redo with named snapshots.

REPL

Interactive prompt for exploring scenes:

blender-cli repl --project project.json

Render profiles

CLI reference

blender-cli [--project FILE] [--json] COMMAND

Pass --json for machine-readable JSON output on all commands.

Development

# Install dev dependencies
uv sync --group dev

# Run tests
uv run pytest

# Type check
uv run pyright

License

MIT