blender-pipeline

Blender Headless Game Asset Pipeline

A skill that automates the creation/processing of 3D assets needed for game development with the Blender Python API (bpy).

Installation

Linux (MiniPC / server)

# Snap (권장 — 최신 버전)
sudo snap install blender --classic

# APT (구버전일 수 있음)
sudo apt install blender

# 직접 다운로드 (가장 유연)
wget https://download.blender.org/release/Blender4.4/blender-4.4.0-linux-x64.tar.xz
tar xf blender-4.4.0-linux-x64.tar.xz
sudo ln -s $(pwd)/blender-4.4.0-linux-x64/blender /usr/local/bin/blender

macOS

# Homebrew
brew install --cask blender

# 또는 직접 다운로드
# CLI 경로: /Applications/Blender.app/Contents/MacOS/Blender

Verify installation

blender --version
blender -b --python-expr "import bpy; print('bpy OK:', bpy.app.version_string)"

Headless execution pattern

Basic structure

# 스크립트 실행 (새 씬)
blender -b --python script.py

# .blend 파일 로드 후 스크립트 실행
blender -b scene.blend --python script.py

# 인자 전달 (-- 이후)
blender -b --python script.py -- --arg1 value1 --arg2 value2

# 팩토리 설정으로 실행 (사용자 설정 무시)
blender --factory-startup -b --python script.py

# 애드온 활성화
blender -b --addons "rigify,io_scene_gltf2" --python script.py

Argument order matters!

# ✅ 올바름: blend 로드 → 출력 설정 → 렌더
blender -b scene.blend -o /tmp/output -F PNG -f 1

# ❌ 잘못됨: 출력 설정이 blend 로드 전
blender -b -o /tmp/output scene.blend -f 1

GPU rendering (headless)

# gpu_setup.py — headless에서 GPU 활성화
import bpy
prefs = bpy.context.preferences.addons['cycles'].preferences
prefs.compute_device_type = 'CUDA'  # 또는 OPTIX, HIP, METAL
prefs.get_devices()
for device in prefs.devices:
    device.use = True
bpy.context.scene.cycles.device = 'GPU'

blender -b scene.blend -E CYCLES -P gpu_setup.py -f 1 -- --cycles-device CUDA

Script usage

1. Format conversion (convert_format.py)

# FBX → glTF
blender -b --python scripts/convert_format.py -- \
  --input model.fbx --output model.glb --format GLB

# OBJ → FBX
blender -b --python scripts/convert_format.py -- \
  --input model.obj --output model.fbx --format FBX

# glTF → OBJ
blender -b --python scripts/convert_format.py -- \
  --input model.gltf --output model.obj --format OBJ

# 배치 변환 (폴더 내 모든 FBX → glTF)
blender -b --python scripts/convert_format.py -- \
  --input-dir ./models/ --output-dir ./converted/ \
  --input-ext .fbx --format GLB

2. Sprite sheet rendering (render_sprite_sheet.py)

# 8방향 스프라이트 시트
blender -b character.blend --python scripts/render_sprite_sheet.py -- \
  --angles 8 --size 128 --output sprites/character.png

# 아이소메트릭 뷰 (카메라 각도 지정)
blender -b character.blend --python scripts/render_sprite_sheet.py -- \
  --angles 8 --size 256 --camera-angle 30 --output sprites/iso_char.png

# 애니메이션 스프라이트 시트 (모든 프레임)
blender -b character.blend --python scripts/render_sprite_sheet.py -- \
  --angles 4 --size 64 --animated --output sprites/anim_sheet.png

3. Procedural prop generation (procedural_props.py)

# 나무 생성
blender -b --python scripts/procedural_props.py -- \
  --type tree --style low-poly --seed 42 --output props/tree.glb

# 바위 생성
blender -b --python scripts/procedural_props.py -- \
  --type rock --style low-poly --count 5 --output props/rocks.glb

# 상자/크레이트
blender -b --python scripts/procedural_props.py -- \
  --type crate --style wooden --output props/crate.glb

# 건물 외형
blender -b --python scripts/procedural_props.py -- \
  --type building --floors 3 --style medieval --output props/building.glb

4. Simple rigging (simple_rig.py)

# Rigify 메타리그로 자동 리깅
blender -b character.blend --python scripts/simple_rig.py -- \
  --target CharacterMesh --type rigify --output rigged_character.blend

# 심플 본 리그 (2D 게임용)
blender -b character.blend --python scripts/simple_rig.py -- \
  --target CharacterMesh --type simple --bones spine,arm_l,arm_r,leg_l,leg_r \
  --output rigged_simple.blend

5. Mixamo import (mixamo_import.py)

# 단일 Mixamo FBX 임포트 + glTF 변환
blender -b --python scripts/mixamo_import.py -- \
  --input mixamo_character.fbx --output character.glb --fix-scale --fix-rotation

# 여러 Mixamo 애니메이션 병합
blender -b --python scripts/mixamo_import.py -- \
  --input-dir ./mixamo_anims/ --merge-animations \
  --output character_animated.glb

# Mixamo → NLA 트랙 정리
blender -b --python scripts/mixamo_import.py -- \
  --input-dir ./mixamo_anims/ --nla-tracks \
  --output character_nla.blend

Workflow

Workflow 1: Mixamo → Blender → game engine

1. Mixamo에서 캐릭터 리깅 + 애니메이션 다운로드 (FBX)
2. mixamo_import.py로 Blender에 임포트 (스케일/회전 보정)
3. 필요시 애니메이션 NLA 트랙 정리
4. convert_format.py로 glTF/GLB 변환
5. 게임엔진(Godot/Unity)에서 임포트

Workflow 2: Procedural assets → sprite sheet

1. procedural_props.py로 3D 에셋 생성
2. 또는 기존 .blend 파일의 모델 사용
3. render_sprite_sheet.py로 다방향 스프라이트 시트 생성
4. 2D 게임에서 스프라이트 시트 사용

Workflow 3: Asset batch pipeline

#!/bin/bash
# batch_pipeline.sh — 전체 파이프라인 자동화

INPUT_DIR="./raw_models"
OUTPUT_DIR="./game_assets"

# 1. 모든 FBX를 glTF로 변환
blender -b --python scripts/convert_format.py -- \
  --input-dir "$INPUT_DIR" --output-dir "$OUTPUT_DIR/models" \
  --input-ext .fbx --format GLB

# 2. 각 모델의 스프라이트 시트 생성
for blend in "$OUTPUT_DIR"/models/*.glb; do
  name=$(basename "$blend" .glb)
  blender -b --python scripts/render_sprite_sheet.py -- \
    --import "$blend" --angles 8 --size 128 \
    --output "$OUTPUT_DIR/sprites/${name}_sheet.png"
done

Running on the MiniPC (nodes.run)

Running from Clawdbot on the MiniPC

# nodes.run으로 Blender 스크립트 실행
nodes.run(node="MiniPC", command=[
    "blender", "-b", "--factory-startup",
    "--python", "/path/to/script.py",
    "--", "--arg1", "value1"
])

Installing Blender on the MiniPC

# MiniPC SSH 접속 후
sudo snap install blender --classic

# 또는 직접 다운로드
wget https://download.blender.org/release/Blender4.4/blender-4.4.0-linux-x64.tar.xz
tar xf blender-4.4.0-linux-x64.tar.xz
echo 'export PATH="$HOME/blender-4.4.0-linux-x64:$PATH"' >> ~/.bashrc

File transfer

# MiniPC → 맥스튜디오 (HTTP 서버)
# MiniPC에서:
cd /output/dir && python3 -m http.server 9877
# 맥스튜디오에서:
curl -O https://<MINIPC_IP>:9877/output_file.glb

Limitations / Caveats

Render engine

Engine	Headless support	GPU required	Notes
Cycles	✅ Fully supported	Optional	Both CPU/GPU possible. Default choice.
EEVEE	⚠️ Linux만	Required	Linux 3.4+ GPU required. macOS/Windows headless not possible.
Workbench	⚠️ Linux만	Required	Same limitations as EEVEE.

Known limitations

EEVEE headless: Requires Linux + GPU + display environment. Xvfbcan create a virtual display:
```
sudo apt install xvfb
xvfb-run blender -b scene.blend -E BLENDER_EEVEE -f 1
```
GPU not auto-detected: In headless mode the GPU must be manually enabled (see gpu_setup.py above)
Single bpy import: In Python, import bpyis possible only once per process. Separate multiple tasks into subprocesses.
Memory: Complex scenes require substantial RAM. On a MiniPC (8GB), focus on low-poly.
Grease Pencil: Cannot render in an environment without a headless GPU.
Snap path: When installed via snap, the pip install path is restricted. If additional packages are needed, tarball installation is recommended.
Blender version compatibility: The bpy API may change between versions. Scripts are based on Blender 4.x.

Performance tips

--factory-startup: Avoid loading unnecessary user settings
--threads N: Specify the number of CPU threads (0 = all)
For low-poly assets, Workbench is faster than Cycles
Batch jobs can be parallelized with xargs/parallel

References

references/bpy-api.md — Core reference for the Blender Python API
references/rigging.md — Rigging guide (Rigify, Mixamo)
references/procedural.md — Procedural modeling patterns
references/rendering.md — Sprite Sheet/Rendering Guide

About this skill

Installation

Linux (MiniPC / server)

macOS

Verify installation

Headless execution pattern

Basic structure

Argument order matters!

GPU rendering (headless)

Script usage

1. Format conversion (convert_format.py)

2. Sprite sheet rendering (render_sprite_sheet.py)

3. Procedural prop generation (procedural_props.py)

4. Simple rigging (simple_rig.py)

5. Mixamo import (mixamo_import.py)

Workflow

Workflow 1: Mixamo → Blender → game engine

Workflow 2: Procedural assets → sprite sheet

Workflow 3: Asset batch pipeline

Running on the MiniPC (nodes.run)

Running from Clawdbot on the MiniPC

Installing Blender on the MiniPC

File transfer

Limitations / Caveats

Render engine

Known limitations

Performance tips

References