blender-interactive

Blender Interactive Socket Server

A skill for real-time manipulation of Blender via TCP socket-based bidirectional communication. Runs on MiniPC's headless Blender 5.0.1.

Architecture

┌─────────────┐     nodes.run      ┌──────────────────────┐
│  Clawdbot   │ ──────────────────>│  MiniPC              │
│  (맥스튜디오)│                     │                      │
│             │     blender_client  │  ┌────────────────┐  │
│             │ ──────────────────>│  │ Blender 5.0.1  │  │
│             │     TCP :9876       │  │ (headless)     │  │
│             │ <──────────────────│  │                │  │
│             │     JSON response   │  │ socket_addon   │  │
└─────────────┘                     │  └────────────────┘  │
                                    └──────────────────────┘

Relationship with Existing Skills

Skill	Purpose	Pattern
blender-pipeline	Batch conversion, spritesheet, procedural	One-off script execution
blender-interactive	Real-time manipulation, scene construction, status query	Resident socket server

Selection criteria:

Simple conversion/batch → blender-pipeline
Complex scene construction, repetitive manipulation, status checking needed → blender-interactive

Quick Start

1. Start server (MiniPC)

# nodes.run으로 서버 시작
nodes.run(node="MiniPC", command=[
    "bash", "-c",
    "blender -b --factory-startup --python $HOME/blender-interactive/blender_socket_addon.py -- --port 9876 &"
])

# 또는 start_server.sh 사용
nodes.run(node="MiniPC", command=[
    "bash", "$HOME/blender-interactive/scripts/start_server.sh", "--background"
])

2. Send command

# ping
nodes.run(node="MiniPC", command=[
    "python3", "$HOME/blender-interactive/scripts/blender_client.py",
    "ping"
])

# 씬 정보 조회
nodes.run(node="MiniPC", command=[
    "python3", "$HOME/blender-interactive/scripts/blender_client.py",
    "get_scene_info", "--pretty"
])

# 오브젝트 생성
nodes.run(node="MiniPC", command=[
    "python3", "$HOME/blender-interactive/scripts/blender_client.py",
    "create_object", "--params", "{\"type\":\"SPHERE\",\"name\":\"Earth\",\"location\":[0,0,0]}"
])

# 머티리얼 설정
nodes.run(node="MiniPC", command=[
    "python3", "$HOME/blender-interactive/scripts/blender_client.py",
    "set_material", "--params", "{\"object_name\":\"Earth\",\"color\":[0.2,0.4,0.8],\"metallic\":0.0,\"roughness\":0.7}"
])

# 렌더링 프리뷰
nodes.run(node="MiniPC", command=[
    "python3", "$HOME/blender-interactive/scripts/blender_client.py",
    "render_preview", "--params", "{\"output_path\":\"/tmp/preview.png\",\"resolution_x\":512,\"resolution_y\":512,\"samples\":32}"
])

3. Stop server

nodes.run(node="MiniPC", command=[
    "bash", "$HOME/blender-interactive/scripts/start_server.sh", "--stop"
])

Command Reference

System

Command	Parameter	Description
`ping`	—	Check server status + command list

Scene Query

Command	Parameter	Description
`get_scene_info`	—	Full scene status (objects, camera, lights, resolution, etc.)
`get_object_info`	`name`	Specific object details (mesh, material, bounding box)

Object Manipulation

Command	Parameter	Description
`create_object`	`type`, `name?`, `location?`, `scale?`	Create basic mesh (CUBE/SPHERE/PLANE/CYLINDER/CONE/TORUS/MONKEY)
`delete_object`	`name`	Delete object
`modify_object`	`name`, `location?`, `rotation?`, `scale?`, `visible?`	Modify transform

Material

Command	Parameter	Description
`set_material`	`object_name`, `color?`, `metallic?`, `roughness?`, `material_name?`	Set PBR material

Rendering

Command	Parameter	Description
`render_preview`	`output_path?`, `resolution_x?`, `resolution_y?`, `samples?`, `engine?`	Quick preview (512x512, 32 samples)
`render_to_file`	`output_path`, `format?`, `resolution_x?`, `resolution_y?`, `samples?`, `engine?`	High-quality render

File Management

Command	Parameter	Description
`save_blend`	`filepath`	Save .blend
`load_blend`	`filepath`	Load .blend
`import_model`	`filepath`, `format?`	Import model (glTF/FBX/OBJ/STL/PLY)
`export_model`	`filepath`, `format?`, `selected_only?`	Export model
`clear_scene`	`keep_camera?`, `keep_lights?`	Reset scene

Code Execution

Command	Parameter	Description
`execute_code`	`code`	Execute arbitrary Python code (maximum flexibility)

Poly Haven Asset Integration

Search/download CC0 free assets (HDRI, textures, 3D models).

# 텍스처 카테고리 조회
nodes.run(node="MiniPC", command=[
    "python3", "$HOME/blender-interactive/scripts/polyhaven.py",
    "categories", "textures"
])

# 벽돌 텍스처 검색
nodes.run(node="MiniPC", command=[
    "python3", "$HOME/blender-interactive/scripts/polyhaven.py",
    "search", "--type", "textures", "--categories", "brick"
])

# 텍스처 다운로드 (1k 해상도)
nodes.run(node="MiniPC", command=[
    "python3", "$HOME/blender-interactive/scripts/polyhaven.py",
    "download", "rock_wall_08", "--type", "textures", "--resolution", "1k",
    "--output", "/tmp/polyhaven/textures/"
])

# HDRI 다운로드
nodes.run(node="MiniPC", command=[
    "python3", "$HOME/blender-interactive/scripts/polyhaven.py",
    "download", "meadow", "--type", "hdris", "--resolution", "2k",
    "--format", "hdr", "--output", "/tmp/polyhaven/hdri/"
])

# 3D 모델 다운로드
nodes.run(node="MiniPC", command=[
    "python3", "$HOME/blender-interactive/scripts/polyhaven.py",
    "download", "food_apple_01", "--type", "models", "--resolution", "1k",
    "--format", "gltf", "--output", "/tmp/polyhaven/models/"
])

Poly Haven + Blender Integration Workflow

# 1. 텍스처 다운로드
polyhaven.py download rock_wall_08 --type textures --resolution 1k --output /tmp/ph/

# 2. Blender에서 평면 생성 + 텍스처 적용 (execute_code 사용)
blender_client.py execute_code --params '{
  "code": "import bpy\nimport os\n\n# 평면 생성\nbpy.ops.mesh.primitive_plane_add(size=10)\nplane = bpy.context.active_object\nplane.name = \"Ground\"\n\n# 머티리얼 + 텍스처\nmat = bpy.data.materials.new(\"RockWall\")\nmat.use_nodes = True\nnodes = mat.node_tree.nodes\nlinks = mat.node_tree.links\n\nbsdf = nodes[\"Principled BSDF\"]\ntex = nodes.new(\"ShaderNodeTexImage\")\ntex.image = bpy.data.images.load(\"/tmp/ph/rock_wall_08_Diffuse_1k.jpg\")\nlinks.new(tex.outputs[\"Color\"], bsdf.inputs[\"Base Color\"])\n\nplane.data.materials.append(mat)"
}'

Protocol Details

Request Format

{
  "type": "command_name",
  "params": {
    "key": "value"
  }
}

Response Format

{
  "status": "success",
  "result": { ... }
}

{
  "status": "error",
  "message": "Error description"
}

Communication Method

Transport: TCP socket, JSON over TCP
Port: 9876 (default)
Timeout: 300 seconds (to account for rendering, etc.)
Thread safety: Commands run on the Blender main thread (bpy.app.timers)
Concurrency: Supports multiple clients (sequential processing)

MiniPC Deployment

File Transfer (Mac Studio → MiniPC)

# 1. 스킬 폴더를 MiniPC에 복사
# nodes.run으로 base64 전송 또는 scp
scp -r skills/blender-interactive/ <user>@<MINIPC_IP>:$HOME/blender-interactive/

Auto-start (systemd)

# $HOME/.config/systemd/user/blender-socket.service
[Unit]
Description=Blender Interactive Socket Server
After=network.target

[Service]
Type=simple
ExecStart=/snap/bin/blender -b --factory-startup --python $HOME/blender-interactive/blender_socket_addon.py -- --port 9876
ExecStop=/bin/kill -TERM $MAINPID
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable blender-socket
systemctl --user start blender-socket

Limitations

Headless Limitations

Viewport screenshots not possible — instead, render_previewrenders with Cycles CPU (slower but accurate)
EEVEE not possible — requires GPU in headless. Use Cycles CPU only
No real-time preview — check with the render result

Performance

MiniPC (8GB RAM) — low-poly scenes recommended. Complex scenes may run out of memory
Cycles CPU rendering — 512x512, 32 samples ≈ 5-15초
Large Poly Haven assets — 4k textures strain RAM. 1k-2k recommended

Security

execute_codecan execute arbitrary code — OK in our environment (controlled MiniPC)
When exposed externally, --host 127.0.0.1binds to local only

File Structure

blender-interactive/
├── SKILL.md                       # 이 문서
├── blender_socket_addon.py        # Blender 소켓 서버 (핵심)
└── scripts/
    ├── blender_client.py          # 명령 전송 클라이언트
    ├── polyhaven.py               # Poly Haven API 클라이언트
    └── start_server.sh            # 서버 시작/중지 스크립트