kjaylee/blender-pipeline

Blender Headless Game Asset Pipeline

게임 개발에 필요한 3D 에셋 제작/가공을 Blender Python API(bpy)로 자동화하는 스킬.

설치

Linux (MiniPC / 서버)

# 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

설치 확인

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

헤드리스 실행 패턴

기본 구조

# 스크립트 실행 (새 씬)
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

인자 순서 중요!

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

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

GPU 렌더링 (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

스크립트 사용법

1. 포맷 변환 (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. 스프라이트 시트 렌더링 (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_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_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 임포트 (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

워크플로우

워크플로우 1: Mixamo → Blender → 게임엔진

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

워크플로우 2: 프로시저럴 에셋 → 스프라이트 시트

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

워크플로우 3: 에셋 배치 파이프라인

#!/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

MiniPC에서 실행 (nodes.run)

Clawdbot에서 MiniPC로 실행

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

MiniPC에 Blender 설치

# 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

파일 전송

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

제한사항 / 주의사항

렌더링 엔진

| 엔진 | Headless 지원 | GPU 필요 | 비고 | |------|:---:|:---:|------| | Cycles | ✅ 완전 지원 | 선택 | CPU/GPU 모두 가능. 기본 선택. | | EEVEE | ⚠️ Linux만 | 필수 | Linux 3.4+ GPU 필수. macOS/Windows headless 불가. | | Workbench | ⚠️ Linux만 | 필수 | EEVEE와 같은 제한. |

알려진 제한

• EEVEE headless: Linux + GPU + display 환경 필요. Xvfb로 가상 디스플레이 생성 가능:

  sudo apt install xvfb
  xvfb-run blender -b scene.blend -E BLENDER_EEVEE -f 1
  

• GPU 자동 감지 안 됨: headless 모드에서 GPU를 수동으로 활성화해야 함 (위 gpu_setup.py 참조)
• bpy 단일 임포트: Python에서 import bpy는 프로세스당 한 번만 가능. 여러 작업은 서브프로세스로 분리.
• 메모리: 복잡한 씬은 상당한 RAM 필요. MiniPC(8GB)에서는 로우폴리 위주.
• Grease Pencil: headless GPU 없는 환경에서 렌더 불가.
• Snap 경로: snap으로 설치 시 pip install 경로가 제한적. 추가 패키지 필요 시 tarball 설치 권장.
• Blender 버전 호환: bpy API는 버전 간 변경 가능. 스크립트는 Blender 4.x 기준.

성능 팁

• --factory-startup: 불필요한 사용자 설정 로드 방지
• --threads N: CPU 스레드 수 지정 (0 = 전체)
• 로우폴리 에셋은 Cycles보다 Workbench가 빠름
• 배치 작업은 xargs/parallel로 병렬화 가능

레퍼런스

• references/bpy-api.md — Blender Python API 핵심 레퍼런스
• references/rigging.md — 리깅 가이드 (Rigify, Mixamo)
• references/procedural.md — 프로시저럴 모델링 패턴
• references/rendering.md — 스프라이트 시트/렌더링 가이드