BlockSmith

Generate block-based 3D models from text prompts using AI

BlockSmith is a powerful Python library for generating block-style 3D models that are perfect for games, art, and procedural content.

Features

🎨 Text-to-3D: Generate block models from simple text descriptions
🖼️ Image-to-3D: Generate from reference images (local files or URLs)
💻 CLI + SDK: Use from command line or Python code
🧱 True Block Geometry: Perfect cube geometry, not just "blocky-looking" models
🚀 Lightweight: Minimal dependencies, optimized for performance
🔄 Multiple Formats: Export to GLB, GLTF, BBModel (Blockbench), JSON, or Python DSL
📊 Session Tracking: Monitor token usage and costs
🤖 Agent-Friendly: Clean API perfect for AI coding assistants
🎮 Game-Ready: Optimized for engines like Hytopia, Minecraft mods, and more

What You Can Do

Generate from anything:

# Text to 3D model
blocksmith generate "a castle" -o castle.glb

Castle Example

Tip: You can view your generated GLB/GLTF files for free at sandbox.babylonjs.com.

Bring it to life:

# Generate a character
blocksmith generate "a blocky robot" -o robot.py

# Animate it
blocksmith animate "walk cycle" -m robot.py -o walk.py

# Link together
blocksmith link -m robot.py -a walk.py -o robot_animated.glb

# Image to 3D model
blocksmith generate "blocky version" --image photo.jpg -o model.glb

Convert between formats:

# Import existing models and convert them
blocksmith convert model.glb model.bbmodel      # GLB → Blockbench
blocksmith convert tree.gltf tree.json         # GLTF → BlockJSON
blocksmith convert castle.bbmodel castle.glb   # Blockbench → GLB

Use it from Python:

from blocksmith import Blocksmith

bs = Blocksmith()

# Generate and save in any format
bs.generate("a tree").save("tree.bbmodel")       # Blockbench
bs.generate("a car").save("car.glb")             # Game-ready GLB
bs.generate("a robot").save("robot.json")        # BlockJSON schema
bs.generate("a house").save("house.py")          # Python DSL code

# Generate with images
bs.generate("turn this into blocks", image="photo.jpg").save("model.glb")

# Track your usage and costs
result = bs.generate("a spaceship")
print(f"Tokens: {result.tokens.total_tokens}")
print(f"Cost: ${result.cost:.4f}")

Why BlockSmith?

✅ No manual modeling - Describe what you want, get a 3D model
✅ Perfect for games - True block geometry, not approximations
✅ Multiple output formats - Works with Blender, Blockbench, game engines
✅ Import existing models - Convert your GLB/GLTF files to other formats
✅ Track your costs - Know exactly how much each generation costs
✅ Fast iteration - Regenerate until you get what you want

Installation

Note: This is an alpha release (v0.0.1). Not yet published to PyPI.

Requirements: Python 3.12+

1. Clone and Install

# Clone the repository
git clone https://github.com/gbusto/blocksmith.git
cd blocksmith

# Create virtual environment
python3.12 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode
pip install -e .

# Updating to latest version:
# git pull origin main
# pip install -e .  # Re-run if dependencies changed
# If you hit weird import errors:
# deactivate && source .venv/bin/activate

2. Set Up API Key

BlockSmith uses Gemini 2.5 Pro by default (best quality for block models).

Get a free API key:

Visit Google AI Studio
Click "Create API Key" in the top left and follow the instructions
Copy your key

If you need help with this, let me know. OR, just use OpenAI, or even a free and local model if you want. If you run into a lot of issues with 429/rate limit errors, it's worth adding your billing info to get more use out of Gemini.

Set the environment variable:

# macOS/Linux - Add to ~/.bashrc or ~/.zshrc
export GEMINI_API_KEY="your-key-here"

# Or set for current session only
export GEMINI_API_KEY="your-key-here"

# Windows (PowerShell)
$env:GEMINI_API_KEY="your-key-here"

# Windows (Command Prompt)
set GEMINI_API_KEY=your-key-here

Verify it's set:

echo $GEMINI_API_KEY  # Should print your key

3. Install Blender (Optional)

Skip this if you only need BBModel, JSON, or Python DSL formats!

BlockSmith uses Blender's GLTF exporter for GLB/GLTF output. Install if you need 3D game-ready formats.

I recommend installing it straight from their site, and noting it's location on disk. OR, use one of the methods below to install it:

macOS:

brew install --cask blender

Linux:

sudo apt install blender  # Ubuntu/Debian

Windows: Download from blender.org/download

Verify Blender is installed:

blender --version  # Should print Blender version

If blender command not found, add Blender to your PATH or set BLENDER_PATH:

# macOS
export BLENDER_PATH="/Applications/Blender.app/Contents/MacOS/Blender"

# Linux (if not in PATH)
export BLENDER_PATH="/usr/bin/blender"

Quick Start

CLI (Easiest)

# Generate a model from text
blocksmith generate "a medieval castle" -o castle.bbmodel

# With reference image
blocksmith generate "turn this into blocks" --image photo.jpg -o model.glb

# Convert between formats
blocksmith convert castle.bbmodel castle.glb

# Animation Workflow
blocksmith animate "wave hand" -m steve.py -o wave.py
blocksmith link -m steve.py -a wave.py -o steve_animated.glb

Python SDK

from blocksmith import Blocksmith

# Initialize (reads GEMINI_API_KEY from environment)
bs = Blocksmith()

# Generate a model
bs.generate("a medieval castle").save("castle.bbmodel")

That's it! You now have a 3D model ready to use.

Usage

CLI Usage

Generate models:

# Basic generation
blocksmith generate "a car" -o car.glb

# With different model (faster/cheaper)
blocksmith generate "a tree" -o tree.bbmodel --model gemini/gemini-2.5-flash-lite

# With reference image (local or URL)
blocksmith generate "blocky version" --image photo.jpg -o model.glb
blocksmith generate "turn this into blocks" --image https://example.com/car.jpg -o car.glb

# Show detailed stats
blocksmith generate "a castle" -o castle.glb --verbose

Convert formats:

# Convert between any supported formats
blocksmith convert model.glb model.bbmodel
blocksmith convert castle.json castle.gltf
blocksmith convert tree.bbmodel tree.json

Get help:

blocksmith --help
blocksmith generate --help
blocksmith --help
blocksmith generate --help
blocksmith convert --help
blocksmith animate --help
blocksmith link --help

Animation Workflow

1. Generate Animation Code:

# Creates a Python file containing just the animation logic
blocksmith animate "make it run" -m model.py -o run.py

2. Link to Model:

# Merges the model and animation(s) into a GLB
blocksmith link -m model.py -a run.py -o final.glb

# You can stick multiple animations together!
blocksmith link -m model.py -a walk.py -a run.py -a jump.py -o final.glb

⚠️ Animation Caveats & Best Practices

Note (Beta): The Animation system currently exports to GLB/GLTF only (not BBModel). To add animations to a model, you must link them during the generation process using the source files (.py/.json). You cannot yet "append" an animation to an existing compiled GLB file.

Pro Tip: Since animations are just Python code, you can manually tweak keyframes in walk.py or paste the code into an LLM to request changes (e.g. "make the bounce 2x higher").

Centered Pivots: If you want an object to rotate around its center (like a floating cube), the Model must have a Group pivot at its geometric center.
- Bad: A cube at [0,0,0] will rotate around the bottom-left corner.
- Good: A cube inside a Group at [0, 0.5, 0] will rotate around its center.
- Fix: Ask the generator for "a cube centered at 0,0,0 ready for rotation".
Speed: LLMs tend to generate very fast animations (1.0s). For smooth loops, try asking for "slow, smooth rotation" or specifically "2 to 4 seconds duration".
Forward Direction: In BlockSmith, North is -Z.
- Arms raising "Forward" will rotate towards -Z.
- The LLM knows this, but sometimes needs reminders for complex moves.

Python SDK Usage

Basic generation:

from blocksmith import Blocksmith

bs = Blocksmith()

# Generate and save directly
bs.generate("a car").save("car.glb")

# Access generation results and metadata
result = bs.generate("a tree")
print(result.dsl)     # Python DSL code
print(result.tokens)  # TokenUsage(prompt=13720, completion=2909, total=16629)
print(result.cost)    # 0.046 (USD) or None for local models
print(result.model)   # "gemini/gemini-2.5-pro"

# Explicitly convert DSL to BlockJSON
block_json = result.to_json()
print(block_json["entities"])

Save Multiple Formats

result = bs.generate("a spaceship")

# Save in different formats from the same generation
result.save("spaceship.glb")      # Binary GLB (requires Blender)
result.save("spaceship.gltf")     # GLTF JSON (requires Blender)
result.save("spaceship.bbmodel")  # Blockbench format
result.save("spaceship.json")     # BlockJSON schema
result.save("spaceship.py")       # Python DSL source

Advanced Features

Use different LLM models:

# Use Gemini Flash Lite (fastest, cheapest)
bs = Blocksmith(default_model="gemini/gemini-2.5-flash-lite")

# Use OpenAI (requires OPENAI_API_K

Blocksmith

Install / Use

README