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-Fokusdocs/RIGGING_PLAYBOOK.md– vollständige Rigging-Methode und Export-/Wiederherstellungsrezeptdocs/VERIFICATION.md– Metrikschwellen und Code-Snippetsdocs/RENDERING.md– Render-Pfad auf Besitzeranfragereference/roblox-avatar.md– R15-Körpervertrag, In-Place-Walk-IK, FBX-Verifikationreference/blender-5x-api.md– Slotted Actions, gemessene 5.4-API, glTF-Zeitursprungreference/glb-qa.md– renderfreie GLB-Gates, Basislinien, Negativtest-Nachweisedocs/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
- 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.blendund öffnen Sie dieselbe Datei erneut. - 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).
- 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_selectedaus. Wählen Sie die Achse, die der Asset-Ebene entspricht (FRONTfür flache XZ-Assets). - Verwenden Sie das Evaluated Mesh, niemals das Original:
obj.evaluated_get(depsgraph).to_mesh(). - Erzwingen Sie die Treiberauswertung mit
scene.frame_set(f)–view_layer.update()reicht nicht. - Speichern Sie inkrementell mit
bpy.ops.wm.save_as_mainfile(filepath=..., compress=True)bei jedem Meilenstein; halten Sie die Ergebnisse im Projektordner. - Ein
execute= ein atomarer, idempotenter Schritt, der die Metriken zurückgibt, die ihn belegen. - 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)
| Metrik | Schwelle |
|---|---|
| Abweichung der Ruheposition vs. Quell-Mesh | < 1e-5 |
| Loop-Naht (letzter Frame vs. erster) | 0 |
| Flächenverhältnis offen/geschlossen | 0,99–1,01 |
| Griff und Backe bewegen sich beide nach außen | > 0 |
| Gewichtete Scheitelpunkte | 100 % |
| Nicht-manifold/Null-Flächen | 0 |
| 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:
- Benennen Sie die Quellaktion um (
*_src), damit die gebackene Aktion einen sauberen Namen erhält. - Entfernen Sie das Custom-Shape-Widget-Objekt, sonst wird es zu einem leeren Knoten.
- Löschen Sie die Aktion,
pose_bone.driver_remove(...), keyframen Sierotation_euler[0]an den Pose-Extremen. - Exportieren Sie mit
export_skins=True,export_animations=True,export_animation_mode="ACTIONS",export_yup=True. - 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
| Symptom | Ursache | Behebung |
|---|---|---|
| Treiber ändert nichts | Depsgraph nicht evaluiert | scene.frame_set(f) |
Action.fcurves fehlt | Slotted Actions | act.layers[0].strips[0].channelbags[*].fcurves, oder scripts/action_compat.py |
| Rig bewegt sich nicht, kein Fehler | Zugewiesene Aktion hat keinen Slot, der an diese ID gebunden ist | assign_action() / setze animation_data.action_slot |
fcurves.new(action_group=...) TypeError | 5.4 Keyword ist group_name | cb.fcurves.new(path, index, group_name="...") |
asset.mark() poll schlägt fehl | Operator liest Outliner-Auswahl | obj.asset_mark() API |
| Property-Keyframes werden ignoriert | falscher Datenpfad | '["open"]' |
.001 Aktionssuffix | Namenskonflikt | Quellaktion zuerst umbenennen |
| Widget in GLB | Objekt noch in einer Szenenkollektion | Während des Exports entfernen |
Unrecognized command | --factory-startup / Erweiterung aus | Neu starten mit Online-Modus |
| Autostart still | Port belegt | Port freigeben, neu starten (kein Wiederholungsversuch) |
| Render-Enum-Fehler | Falscher Engine-Name | BLENDER_EEVEE aus der Aufzählung wählen |
enum "OCTAHEDRAL" not found | Armature-Anzeige ist Daten, nicht Objekt | rig.data.display_type = "OCTAHEDRAL" |
bpy.context.window ist None | Hintergrundbuild hat kein Fenster | Mit window_manager.windows absichern |
| FBX-Reimport lässt die Figur schweben | Importer markiert die Wurzel als verbundenen Bone und verwirft ihre Translation | Datei mit scripts/inspect_fbx.py verifizieren, nicht den Roundtrip |
Ergebnisse
.blend– maßgebliches Rig, gespeichert im Ruheframe, mit einemREADME_RIG-Textblock..glb– geskinnt + animiert, durch Re-Import verifiziert.README.mdim Projektordner mit Drehpunkt, Bones, Property, Winkeln, Zahlen.