Blender Control Skill (Live GUI + Headless CLI)

Was macht Blender Control Skill (Live GUI + Headless CLI)?

Dieses Workspace steuert Blender 5.2.1 LTS (/Applications/Blender.app/Contents/MacOS/Blender, Python 3.13, Apple M1 Pro 16-Core Metal GPU) in zwei komplementären Modi:

1. Live-GUI-Modus (Standard & Bevorzugt): Sendet Befehle über 127.0.0.1:9876 an blender_control_bridge.py, die im geöffneten Blender.app-Fenster läuft. Objekte, Shader, Animationen und Kameraeinstellungen erscheinen sofort vor dem Benutzer.
2. Headless-CLI-Modus: Führt /Applications/Blender.app/Contents/MacOS/Blender --background für isolierte Batch-Renderings oder schwere Hintergrundaufgaben aus, ohne die aktive GUI-Sitzung zu beeinflussen.

Bevor du bpy-Skripte für Blender 5.2 schreibst, lies blender_5_2_api_guide.md für kritische API-Änderungen in 5.2 (Principled BSDF-Socket-Namen, Slotted Actions channelbag, media_type = 'VIDEO', und Metal-GPU-Einrichtung).

---

Schritt 1: Verbindung zur geöffneten Blender-Anwendung prüfen oder herstellen

Überprüfe immer zuerst die Live-Bridge-Verbindung:

python3 .agents/skills/blender-control/scripts/blender_cli.py ping

Falls ping fehlschlägt (z.B. Blender ist noch nicht geöffnet oder wurde vor der Installation der Startup-Bridge gestartet), führe das Installations-/Verbindungsskript aus:

bash .agents/skills/blender-control/scripts/install_bridge.sh

• Kopiert blender_control_bridge.py in ~/Library/Application Support/Blender/5.2/scripts/startup/, sodass jeder GUI-Start die Bridge automatisch auf 127.0.0.1:9876 startet.
• Stellt sicher, dass die Verbindung zu Blender.app (open -g -a Blender) ohne Fensterfokus-Klau hergestellt oder die App gestartet wird.
• Falls Blender.app bereits eine ungespeicherte .blend-Datei geöffnet hat, aber die Bridge nicht geladen ist, bitte den Benutzer, in der macOS-Menüleiste auf Blender -> System -> Reload Scripts zu klicken.

---

Schritt 2: Live-Szene via blender_cli.py inspizieren und steuern

Verwende blender_cli.py für alle Live-Operationen:

# 1. Aktuelle Objekte, Kameras, Materialien, Frame-Bereich und Render-Engine inspizieren
python3 .agents/skills/blender-control/scripts/blender_cli.py info

# 2. Live-Szene sauber zurücksetzen (entfernt alle Objekte & verwaiste Datenblöcke)
python3 .agents/skills/blender-control/scripts/blender_cli.py reset

# 3. Ein Szenen-Builder-Python-Skript live im Haupt-UI-Thread von Blender ausführen
python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py

# 4. Schnelle Inline-Python-Ausdrücke/Snippets ausführen
python3 .agents/skills/blender-control/scripts/blender_cli.py exec "RESULT = [o.name for o in bpy.data.objects]"

# 5. Den Live-Blender-3D-Viewport auf Materialvorschau oder gerenderte Kameraperspektive umschalten
python3 .agents/skills/blender-control/scripts/blender_cli.py viewport --shading MATERIAL

# 6. .blend-Projektdateien in der Live-GUI speichern oder öffnen
python3 .agents/skills/blender-control/scripts/blender_cli.py save projects/my_scene/scene.blend
python3 .agents/skills/blender-control/scripts/blender_cli.py open projects/my_scene/scene.blend

---

Schritt 3: Standbilder, Viewport-Vorschauen und Animationen rendern

Schnelle Viewport-Vorschau (<0,2s)

Erstelle zuerst einen Viewport-Screenshot, um Kameraperspektive, Objektplatzierung und Clipping zu überprüfen, bevor du ein volles Raytracing-Rendering startest:

python3 .agents/skills/blender-control/scripts/blender_cli.py screenshot /tmp/preview.png

Überprüfe /tmp/preview.png mit read_file, um Komposition und Beleuchtung visuell zu kontrollieren!

Hochwertiges Standbild-Rendering (Cycles Metal GPU oder EEVEE)

# Cycles mit automatischer Apple M1 Pro 16-Core Metal GPU-Beschleunigung
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine CYCLES --samples 64 --width 1920 --height 1080

# Schnelles Echtzeit-PBR-Rendering mit EEVEE
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine BLENDER_EEVEE --samples 32 --width 1920 --height 1080

MP4 (H.264) Animations-Rendering

python3 .agents/skills/blender-control/scripts/blender_cli.py render-anim projects/my_scene/animation.mp4 \
  --engine BLENDER_EEVEE --samples 32 --width 1280 --height 720 --start 1 --end 120 --fps 30

Headless-Batch-Modus (Isolierter Prozess)

Für schwere Rendering-Aufgaben, die den Live-GUI-Viewport nicht blockieren sollen:

python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py --headless

---

Schritt 4: Szenenaufbau und Validierungs-Checkliste

1. In sich geschlossene Builder-Skripte: Lege jedes Projekt in projects/<projektname>/build.py ab, sodass Szenen zu 100 % reproduzierbar und Git-freundlich sind – zusammen mit gerenderten Ausgaben und .blend-Dateien.
2. Kameraausrichtung (TRACK_TO oder Quaternion): Richte die Kamera immer zuverlässig auf ein leeres Zielobjekt oder einen Weltkoordinatenpunkt aus, indem du (target - cam.location).to_track_quat('-Z', 'Y') verwendest und scene.camera = cam setzt.
3. Dreipunkt-/Studio-Beleuchtung und Welt: Lasse niemals einen dunklen Standard-Grau-Hintergrund; konfiguriere World-Shader-Knoten + Area-/Sun-Lichter mit realistischer Wattzahl (100W–1500W je nach Szenengröße) und AgX- oder Filmic-Farbmanagement (scene.view_settings.view_transform = 'AgX', look = 'AgX - Medium High Contrast').
4. Visuelle Überprüfung: Überprüfe gerenderte .png- oder .mp4-Ausgaben immer mit read_file, um Bildausschnitt, Belichtung, Materialien und Bewegung vor dem Abschluss zu bestätigen.
5. GitHub-Sync: Führe nach dem Erstellen oder Aktualisieren von Projekten/Fähigkeiten ./scripts/sync_github.sh "<Commit-Nachricht>" aus, um das lokale Repository und origin/main synchron zu halten.

---

Hinweis: Dieses Skill wurde für die Verwendung auf macOS mit Apple Silicon optimiert und setzt einen funktionierenden Blender 5.2.1 LTS mit aktiviertem Metal-Backend voraus.