CommunityBildgithub.com

Blender Live Rigging

Rig, bearbeiten, prüfen und exportieren Sie 3D-Assets live in der geöffneten Blender-Instanz des Benutzers über die offizielle Blender MCP-Socket-Bridge. Nutzbar für Armaturen, Skinning, mechanische/Scharnier-Rigs, Treiber, benutzerdefinierte Property-Steuerungen, Evaluated-Mesh-Verifikation, gebackenen glTF-Export und Rendering nur auf ausdrückliche Anfrage des Besitzers.

Was ist Blender Live Rigging?

Diese Skill ermöglicht es KI-Agenten, direkt mit einer laufenden Blender-GUI-Instanz zu interagieren und Rigging-, Animations- und Exportaufgaben durchzuführen, ohne den Benutzer zu unterbrechen oder Blender zu schließen. Sie nutzt die offizielle MCP-Bridge (bl_ext.blenderlab.mcp) auf 127.0.0.1:9876 und führt jeden Schritt atomar und idempotent aus, wobei Ergebnisse stets durch quantitative Metriken (z. B. Scheitelpunktkoordinaten, Flächenverhältnisse) belegt werden. Die Skill behandelt mechanische Rigs mit starren Teilen und Knochen pro Teil, einschließlich Scharnier- und Scherenmechaniken, und unterstützt Treiberausdrücke, benutzerdefinierte Properties sowie die korrekte Handhabung von Slotted Actions in Blender 5.x. Das Rendern ist standardmäßig deaktiviert und wird nur auf ausdrückliche Anfrage des Benutzers ausgeführt. Hauptplattformen sind Blender 4.x und 5.x (mit Kompatibilitätshilfen für 5.4). Das Repository enthält ausführliche Dokumentationen zu Protokoll, Rigging-Methodik, Verifikation, Rendering und Referenzmaterialien für Roblox-Avatare sowie zur glTF-Qualitätssicherung.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/andypratama3/blender-mcp/tree/HEAD/skills/blender-live-rigging

Installed? Explore more Bild skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht Blender Live Rigging?

Steuern Sie die Blender-Instanz, die der Benutzer bereits betrachtet. Keine Headless-Batches, kein Schließen seiner Anwendung. Jede Behauptung von „erledigt“ muss durch Zahlen untermauert werden, die aus dem evaluierten Depsgraph gelesen wurden. Rendern ist standardmäßig deaktiviert und erfolgt nur, wenn der Besitzer danach fragt.

Repository-Dokumente (lesen Sie diese, wenn Sie Tiefe benötigen, nicht jedes Mal):

  • docs/MCP_BRIDGE.md – Protokoll, Startmodi, Fallstricke, Viewport-Fokus
  • docs/RIGGING_PLAYBOOK.md – vollständige Rigging-Methode und Export-/Wiederherstellungsrezept
  • docs/VERIFICATION.md – Metrikschwellen und Code-Snippets
  • docs/RENDERING.md – Render-Pfad auf Besitzeranfrage
  • reference/roblox-avatar.md – R15-Körpervertrag, In-Place-Walk-IK, FBX-Verifikation
  • reference/blender-5x-api.md – Slotted Actions, gemessene 5.4-API, glTF-Zeitursprung
  • reference/glb-qa.md – renderfreie GLB-Gates, Basislinien, Negativtest-Nachweise
  • docs/CASE_STUDY_KNIGHT.md – gemessener R15-Avatar + Walk-Loop (Projektstamm)

Wenn diese Skill aus andypratama3/blender-mcp installiert wurde, befindet sich der Projektstamm drei Ebenen über dieser Datei (skills/blender-live-rigging/SKILL.md).

Harte Regeln

  1. Nur Live-GUI. Bestätigen Sie bpy.app.background == False. Beenden Sie Blender niemals, während der Benutzer arbeitet; falls Sie wegen eines Portkonflikts neu starten müssen, speichern Sie zuerst .blend und öffnen Sie dieselbe Datei erneut.
  2. Kein Rendern, es sei denn, der Besitzer fragt danach. Standard-Verifikation ist numerisch: Scheitelpunkt- koordinaten, Breiten, Flächen, Verhältnisse. Wenn der Besitzer explizit ein Rendern anfordert, führen Sie es in der Live-Sitzung durch (siehe Rendern auf Anfrage).
  3. Fokussieren Sie den Viewport auf das, was Sie bearbeiten, vor und nach der Änderung: Wählen Sie das Objekt/die Bones aus, setzen Sie eines aktiv, führen Sie view3d.view_axis + view3d.view_selected aus. Wählen Sie die Achse, die der Asset-Ebene entspricht (FRONT für flache XZ-Assets).
  4. Verwenden Sie das Evaluated Mesh, niemals das Original: obj.evaluated_get(depsgraph).to_mesh().
  5. Erzwingen Sie die Treiberauswertung mit scene.frame_set(f) – view_layer.update() reicht nicht.
  6. Speichern Sie inkrementell mit bpy.ops.wm.save_as_mainfile(filepath=..., compress=True) bei jedem Meilenstein; halten Sie die Ergebnisse im Projektordner.
  7. Ein execute = ein atomarer, idempotenter Schritt, der die Metriken zurückgibt, die ihn belegen.
  8. Messen Sie, was den Boden berührt, am Mesh, nicht am Bone. Ein Bone-Tail kann 0,4 Stud über der Sohle sitzen, sodass ein Bone-Tail-Gate bestanden wird, während der Stiefel durch den Boden sinkt. Verwenden Sie den niedrigsten Weltscheitelpunkt des Evaluated Mesh.

1. Verbinden

Die Bridge ist das offizielle Add-on bl_ext.blenderlab.mcp auf 127.0.0.1:9876.

lsof -nP -iTCP:9876 -sTCP:LISTEN          # muss vor dem Start frei sein
open -a Blender --args --online-mode "/abs/path/file.blend"   # macOS
sleep 8 && lsof -nP -iTCP:9876 -sTCP:LISTEN

--online-mode ist zwingend erforderlich (Autostart benötigt bpy.app.online_access), und verwenden Sie niemals --factory-startup (es deaktiviert die Erweiterung). Dann:

python3 scripts/blender_mcp.py 'import bpy
result = {"gui": not bpy.app.background, "file": bpy.data.filepath}'

2. Das Asset inspizieren

Importieren Sie glTF, backen Sie matrix_world in Mesh-Daten, entfernen Sie leere Eltern, verschweißen Sie Duplikate (remove_doubles(1e-5)), zählen Sie verbundene Schalen, und geben Sie eine ASCII-Silhouette aus, um die Ebene, den Drehpunkt und die beweglichen Teile zu finden:

blender -b --factory-startup --python scripts/inspect_glb.py -- "/path/asset.glb"

3. Die Rig-Topologie festlegen

Für mechanische Assets: starre Teile, starre Gewichtungen, ein Bone pro Teil. Für Scheren-/Zangenformen, koppeln Sie Teile diagonal (linker Griff + rechte Backenhälfte), sodass Griffe und Backen sich gemeinsam öffnen; ein Mittellinienschnitt lässt die Backen schließen, während die Griffe sich öffnen.

Setzen Sie den Scharnierdrehpunkt dort, wo die Griffe aufeinandertreffen, setzen Sie den Schnitt ebenfalls dorthin, und richten Sie den Bone so aus, dass rotation_euler.x exakt die Welt-Scharnierachse ist:

d = (Vector(b.tail) - Vector(b.head)).normalized()
b.align_roll(Vector((d.z, 0.0, -d.x)))   # lokales X == Welt Y

4. Das Mesh vorbereiten

Bisezieren Sie an jeder Grenze starrer Teile mit use_fill=True, versetzen Sie die Kappen um ~0,0004, um Z-Fighting zu vermeiden, kippen Sie nur die Kappenflächen (behalten Sie glTF-Custom-Split-Normals), weisen Sie Vertex- Gruppen pro Teil vor dem Zusammenfügen zu, und parenten Sie dann mit einem ARMATURE-Modifier.

5. Steuerungen und Animation

Eine benutzerdefinierte Property (open, 0–1) treibt jeden Bone durch einfache Treiberausdrücke, plus LIMIT_ROTATION als Sicherheitsnetz. Setzen Sie rotation_mode = "XYZ", bevor Sie rotation_euler treiben. Keyframen Sie die Property – nicht die Bones – für die Loop-Aktion, und setzen Sie BEZIER + AUTO_CLAMPED.

6. Verifizieren (Gate vor der Erfolgsmeldung)

MetrikSchwelle
Abweichung der Ruheposition vs. Quell-Mesh< 1e-5
Loop-Naht (letzter Frame vs. erster)0
Flächenverhältnis offen/geschlossen0,99–1,01
Griff und Backe bewegen sich beide nach außen> 0
Gewichtete Scheitelpunkte100 %
Nicht-manifold/Null-Flächen0
Niedrigster deformierter Scheitelpunkt vs. Boden≥ −0,006, Standfuß 0 ± 0,006

scripts/verify_rig_glb.py importiert das exportierte GLB in einem separaten Blender-Prozess neu (stört niemals die Live-Sitzung) und gibt Knoten-/Skin-/Animationsanzahlen sowie Breiten bei den Frames 1/15/30/60 aus.

Bewegen Sie bei Locomotion die Beine mit Zwei-Bone-IK gegen ein Fußgelenk-Ziel, anstatt Gelenkwinkel von Hand zu keyframen, und messen Sie dann jeden Frame:

low = min((ev.matrix_world @ v.co).z for v in ev.to_mesh().vertices)  # pro Frame

Wenn ein Bone-Gate und ein Mesh-Gate sich widersprechen, hat das Mesh-Gate Recht.

6d. Renderfreie GLB-Qualitätssicherung

python3 scripts/glb_qa.py export/model.glb --loop --max-tris 20000
python3 scripts/glb_qa.py export/tool.glb --manifold

Nur Standardbibliothek, kein Blender: Es liest den GLB-Container direkt und prüft Header-Länge, Accessor-Grenzen, Gewichtssummen, ungewichtete Scheitelpunkte, Joint-Indizes, Bind-Pose-Anzahlen, Keyframe-Reihenfolge, Quaternionen-Norm, Loop-Schließung, NaN und (mit --manifold) Randkanten. Exit 1 bei jedem Fehler. verify_rig_glb.py behält die Messung der Bewegungsbreite beweglicher Teile. Gates, Basislinien und die fünf absichtlich defekten Dateien, die sie aufdeckten: reference/glb-qa.md.

6b. Ein Multi-File-Projekt-Skript live ausführen

Skripte, die eigene Module importieren, müssen innerhalb der Live-Sitzung über den Pfad geladen werden:

import importlib.util, sys
spec = importlib.util.spec_from_file_location("walk_cycle", "/abs/project/walk_cycle.py")
mod = importlib.util.module_from_spec(spec)
sys.modules["walk_cycle"] = mod          # sonst sehen Dataclasses/Imports ein Duplikat
spec.loader.exec_module(mod)
result = mod.main(save=True)             # gibt ein Dict der gemessenen Gates zurück

Behalten Sie __main__ für den Headless-Durchlauf (blender -b file.blend --python walk_cycle.py -- --save) und rufen Sie main() von der Bridge aus auf, sodass ein Skript beiden Pfaden dient.

6c. Aktionen in Blender 5.x (Slotted)

Action.fcurves, Action.groups und Action.id_root existieren in 5.4 nicht. Verwenden Sie die Hilfsfunktionen anstatt den Channelbag-Durchlauf neu zu tippen, und binden Sie den Slot explizit:

# Live-Sitzung (cwd = dieser Skill-Ordner); gibt das Audit als `result` zurück
python3 scripts/blender_mcp.py "import sys; sys.path.insert(0, 'scripts')
import action_compat
result = action_compat.audit()"

# Headless; Exit 1, wenn ein Slot nicht gebunden ist
blender -b file.blend --python scripts/action_compat.py
from action_compat import iter_fcurves, ensure_fcurve, assign_action
slot = assign_action(obj, action)                 # alleiniges Zuweisen lässt action_slot None
ensure_fcurve(action, slot, 'pose.bones["Head"].rotation_euler', 1, group_name="HeadTwist")

Gemessene Fehlerart: Das Zuweisen einer Aktion, die bereits einen Slot zu einer anderen ID hat, hinterlässt animation_data.action_slot is None und das Rig bleibt in Ruhestellung ohne Fehler (Kopf bei 4.0 statt animierten 3.92). Gate: action_compat.py meldet slot_assigned: true und slot_fcurves > 0 für jedes animierte Objekt. Außerdem channelbag.fcurves.new(..., group_name=...), niemals action_group=.

Details und der Rest der gemessenen API: reference/blender-5x-api.md.

7. glTF exportieren

glTF hat keine Treiber, benutzerdefinierten Properties oder Constraints. Backen Sie sie:

  1. Benennen Sie die Quellaktion um (*_src), damit die gebackene Aktion einen sauberen Namen erhält.
  2. Entfernen Sie das Custom-Shape-Widget-Objekt, sonst wird es zu einem leeren Knoten.
  3. Löschen Sie die Aktion, pose_bone.driver_remove(...), keyframen Sie rotation_euler[0] an den Pose-Extremen.
  4. Exportieren Sie mit export_skins=True, export_animations=True, export_animation_mode="ACTIONS", export_yup=True.
  5. Stellen Sie wieder her: Weisen Sie die Aktion neu zu, löschen Sie den Bake, verknüpfen Sie das Widget neu, fügen Sie die Treiber wieder hinzu, frame_set(1), speichern.

Warnungen wegen „Baking animation because of unsupported constraints“ sind zu erwarten.

Rendern auf Anfrage (nur Besitzer)

Auslöser: Der Besitzer sagt explizit „render“ oder fordert ein Vorschaubild/Video an. Rendern Sie nicht aus eigener Initiative und nicht als Verifikation.

Blender 5.4 zeigt EEVEE als BLENDER_EEVEE an (nicht BLENDER_EEVEE_NEXT), wählen Sie also aus der Aufzählung, anstatt einen versionsspezifischen Namen fest zu codieren. glTF-Szenen haben keine Kamera und keine Lichter – erstellen Sie sie zuerst in einer Render_Setup-Sammlung.

import bpy, math, os

scene = bpy.context.scene
engines = [i.identifier for i in bpy.types.RenderSettings.bl_rna.properties["engine"].enum_items]
scene.render.engine = next(e for e in ("BLENDER_EEVEE", "BLENDER_EEVEE_NEXT") if e in engines)

if scene.camera is None:
    cam_data = bpy.data.cameras.new("Preview_Cam")
    cam_data.type = "ORTHO"
    cam_data.ortho_scale = 1.0
    cam = bpy.data.objects.new("Preview_Cam", cam_data)
    scene.collection.objects.link(cam)
    cam.location = (0.0, -2.0, -0.055)
    cam.rotation_euler = (math.radians(90), 0.0, 0.0)
    scene.camera = cam

if not any(o.type == "LIGHT" for o in bpy.data.objects):
    light_data = bpy.data.lights.new("Preview_Key", "AREA")
    light_data.energy = 300
    light_data.size = 2.0
    light = bpy.data.objects.new("Preview_Key", light_data)
    scene.collection.objects.link(light)
    light.location = (1.5, -2.0, 1.5)
    light.rotation_euler = (math.radians(55), 0.0, math.radians(35))

scene.render.resolution_x = 1920
scene.render.resolution_y = 1080
scene.render.resolution_percentage = 100
scene.render.image_settings.file_format = "PNG"
scene.render.filepath = "/abs/project/render/preview.png"
bpy.ops.render.render(write_still=True)
result = {"image": scene.render.filepath,
          "size": os.path.getsize(scene.render.filepath),
          "engine": scene.render.engine, "camera": scene.camera.name}

Regeln für diesen Pfad: Speichern Sie zuerst .blend, schreiben Sie in <projekt>/render/, melden Sie den absoluten Pfad und die Dateigröße, erhöhen Sie das Client-Timeout, und starten Sie niemals einen Headless-Render einer Datei mit ungespeicherten Änderungen.

Blender 5.4 Fallstricke

SymptomUrsacheBehebung
Treiber ändert nichtsDepsgraph nicht evaluiertscene.frame_set(f)
Action.fcurves fehltSlotted Actionsact.layers[0].strips[0].channelbags[*].fcurves, oder scripts/action_compat.py
Rig bewegt sich nicht, kein FehlerZugewiesene Aktion hat keinen Slot, der an diese ID gebunden istassign_action() / setze animation_data.action_slot
fcurves.new(action_group=...) TypeError5.4 Keyword ist group_namecb.fcurves.new(path, index, group_name="...")
asset.mark() poll schlägt fehlOperator liest Outliner-Auswahlobj.asset_mark() API
Property-Keyframes werden ignoriertfalscher Datenpfad'["open"]'
.001 AktionssuffixNamenskonfliktQuellaktion zuerst umbenennen
Widget in GLBObjekt noch in einer SzenenkollektionWährend des Exports entfernen
Unrecognized command--factory-startup / Erweiterung ausNeu starten mit Online-Modus
Autostart stillPort belegtPort freigeben, neu starten (kein Wiederholungsversuch)
Render-Enum-FehlerFalscher Engine-NameBLENDER_EEVEE aus der Aufzählung wählen
enum "OCTAHEDRAL" not foundArmature-Anzeige ist Daten, nicht Objektrig.data.display_type = "OCTAHEDRAL"
bpy.context.window ist NoneHintergrundbuild hat kein FensterMit window_manager.windows absichern
FBX-Reimport lässt die Figur schwebenImporter markiert die Wurzel als verbundenen Bone und verwirft ihre TranslationDatei mit scripts/inspect_fbx.py verifizieren, nicht den Roundtrip

Ergebnisse

  • .blend – maßgebliches Rig, gespeichert im Ruheframe, mit einem README_RIG-Textblock.
  • .glb – geskinnt + animiert, durch Re-Import verifiziert.
  • README.md im Projektordner mit Drehpunkt, Bones, Property, Winkeln, Zahlen.

Verwandte Skills