CommunityImagegithub.com

Blender Live Rigging

Rig, éditer, vérifier et exporter des assets 3D en direct dans l'application Blender ouverte via le socket bridge MCP officiel de Blender.

Qu'est-ce que Blender Live Rigging ?

Cette compétence permet de piloter une session Blender active pour le rigging, l'édition, la vérification et l'exportation d'assets 3D. Elle est conçue pour les utilisateurs qui travaillent déjà dans l'interface graphique de Blender et ne nécessite pas de processus en arrière-plan. La compétence s'appuie sur le pont MCP officiel `bl_ext.blenderlab.mcp` (127.0.0.1:9876) et exige que Blender soit lancé en mode `--online-mode`. L'utilisateur peut ainsi modifier des armatures, des skinning, des mécanismes à charnière, des drivers, des contrôles par propriétés personnalisées, et vérifier l'exportation en glTF. Le rendu est désactivé par défaut ; il ne s'effectue que sur demande explicite du propriétaire. La vérification se fait par métriques numériques (coordonnées, aires, ratios) sur le maillage évalué, et non sur les os. La compétence prend en charge les actions à slots de Blender 5.4 et fournit des aides pour la compatibilité. Les scripts d'inspection et de vérification sont exécutés dans des processus séparés pour ne pas perturber la session en cours.

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

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait Blender Live Rigging ?

Pilotez l'instance Blender que l'utilisateur a déjà sous les yeux. Pas de traitements en arrière-plan, pas de fermeture de son application. Chaque affirmation de « terminé » doit être étayée par des nombres lus depuis le graphe de dépendances évalué. Le rendu est désactivé par défaut et ne se produit que lorsque le propriétaire le demande.

Documentation du dépôt (à lire lorsque vous avez besoin de profondeur, pas à chaque fois) :

  • docs/MCP_BRIDGE.md — protocole, modes de lancement, pièges, focus sur la vue
  • docs/RIGGING_PLAYBOOK.md — méthode complète de rigging et recette d'exportation/restauration
  • docs/VERIFICATION.md — seuils métriques et extraits
  • docs/RENDERING.md — chemin de rendu sur demande du propriétaire
  • reference/roblox-avatar.md — corps R15, IK de marche sur place, vérification FBX
  • reference/blender-5x-api.md — actions à slots, API mesurée 5.4, origine temporelle glTF
  • reference/glb-qa.md — portes de validation GLB sans rendu, bases de référence, preuves de tests négatifs
  • docs/CASE_STUDY_KNIGHT.md — avatar R15 mesuré + boucle de marche (racine du dépôt)

Si cette compétence a été installée depuis andypratama3/blender-mcp, la racine du dépôt se trouve trois niveaux au-dessus de ce fichier (skills/blender-live-rigging/SKILL.md).

Règles strictes

  1. Interface graphique uniquement. Confirmez bpy.app.background == False. Ne tuez jamais Blender pendant que l'utilisateur travaille ; si vous devez redémarrer pour un conflit de port, sauvegardez d'abord .blend et rouvrez le même fichier.
  2. Pas de rendu sauf si le propriétaire le demande. La vérification par défaut est numérique : coordonnées des sommets, largeurs, aires, ratios. Quand le propriétaire demande explicitement un rendu, faites-le dans la session en direct (voir Rendu sur demande).
  3. Concentrez la vue sur ce que vous éditez, avant et après le changement : sélectionnez l'objet/les os, rendez-en un actif, exécutez view3d.view_axis + view3d.view_selected. Choisissez l'axe correspondant au plan de l'asset (FRONT pour les assets plats en XZ).
  4. Utilisez le maillage évalué, jamais l'original : obj.evaluated_get(depsgraph).to_mesh().
  5. Forcez l'évaluation des drivers avec scene.frame_set(f) — view_layer.update() ne suffit pas.
  6. Sauvegardez de manière incrémentale avec bpy.ops.wm.save_as_mainfile(filepath=..., compress=True) à chaque étape ; conservez les livrables dans le dossier du projet.
  7. Un execute = une étape atomique et idempotente qui renvoie les métriques qui la prouvent.
  8. Mesurez ce qui touche le sol sur le maillage, pas sur l'os. L'extrémité d'un os peut se trouver à 0,4 stud au-dessus de la semelle, donc une porte basée sur l'extrémité de l'os passe alors que la botte s'enfonce dans le sol. Utilisez le sommet le plus bas du maillage évalué dans le monde.

1. Connexion

Le pont est l'extension officielle bl_ext.blenderlab.mcp sur 127.0.0.1:9876.

lsof -nP -iTCP:9876 -sTCP:LISTEN          # doit être libre avant le lancement
open -a Blender --args --online-mode "/chemin/absolu/fichier.blend"   # macOS
sleep 8 && lsof -nP -iTCP:9876 -sTCP:LISTEN

--online-mode est obligatoire (le démarrage automatique nécessite bpy.app.online_access), et n'utilisez jamais --factory-startup (cela désactive l'extension). Ensuite :

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

2. Inspecter l'asset

Importez le glTF, bakez matrix_world dans les données du maillage, supprimez les parents vides, soudez les doublons (remove_doubles(1e-5)), comptez les coques connectées et affichez une silhouette ASCII pour trouver le plan, le pivot et les pièces mobiles :

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

3. Décider la topologie du rig

Pour les assets mécaniques : pièces rigides, poids rigides, un os par pièce. Pour les formes de ciseaux/pinces, associez les pièces en diagonale (poignée gauche + moitié de mâchoire droite) pour que les poignées et les mâchoires s'ouvrent ensemble ; une séparation médiane fait que les mâchoires se ferment quand les poignées s'ouvrent.

Placez le pivot de la charnière là où les poignées se rencontrent, placez-y aussi la coupe de jointure, et alignez l'os de sorte que rotation_euler.x soit exactement l'axe de la charnière dans le monde :

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

4. Préparer le maillage

Bissectez à chaque frontière de pièce rigide avec use_fill=True, décalez les capuchons d'environ 0,0004 pour éliminer le z-fighting, retournez uniquement les faces des capuchons (conservez les normales de split personnalisées glTF), assignez les groupes de sommets par pièce avant de joindre, puis parentez avec un modificateur ARMATURE.

5. Contrôles et animation

Une propriété personnalisée (open, 0–1) pilote chaque os via des expressions de driver simples, avec LIMIT_ROTATION comme filet de sécurité. Définissez rotation_mode = "XYZ" avant de piloter rotation_euler. Keyframez la propriété — pas les os — pour l'action de boucle, et définissez BEZIER + AUTO_CLAMPED.

6. Vérifier (porte avant de déclarer le succès)

MétriqueSeuil
Déviation au repos vs maillage source< 1e-5
Couture de boucle (dernière trame vs première)0
Rapport d'aire des faces ouvert/fermé0,99–1,01
La poignée et la mâchoire bougent toutes deux vers l'extérieur> 0
Sommets pondérés100%
Faces non-manifold / d'aire nulle0
Sommet déformé le plus bas vs sol≥ −0,006, pied d'appui 0 ± 0,006

scripts/verify_rig_glb.py réimporte le GLB exporté dans un processus Blender séparé (ne perturbe jamais la session en direct) et affiche les comptages de nœuds/peau/animations ainsi que les largeurs aux trames 1/15/30/60.

Pour la locomotion, résolvez les jambes avec une IK à deux os contre une cible à la cheville plutôt que de keyframer manuellement les angles articulaires, puis mesurez chaque trame :

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

Si une porte basée sur un os et une porte basée sur un maillage sont en désaccord, c'est la porte du maillage qui a raison.

6d. QA GLB sans rendu

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

Bibliothèque standard uniquement, pas de Blender : il lit le conteneur GLB directement et vérifie la longueur d'en-tête, les bornes des accesseurs, les sommes des poids, les sommets non pondérés, les indices d'articulations, les comptages de pose de liaison, l'ordre des trames clés, la norme des quaternions, la fermeture de boucle, les NaN et (avec --manifold) les arêtes de bordure. Code de sortie 1 en cas d'échec. verify_rig_glb.py conserve la mesure des largeurs des pièces mobiles. Portes, bases de référence et les cinq fichiers délibérément cassés qu'elles ont détectés : reference/glb-qa.md.

6b. Exécuter un script multi-fichier en direct

Les scripts qui importent leurs propres modules doivent être chargés par chemin dans la session en direct :

import importlib.util, sys
spec = importlib.util.spec_from_file_location("walk_cycle", "/abs/projet/walk_cycle.py")
mod = importlib.util.module_from_spec(spec)
sys.modules["walk_cycle"] = mod          # sinon les dataclasses/imports voient un doublon
spec.loader.exec_module(mod)
result = mod.main(save=True)             # renvoie un dict des portes mesurées

Conservez __main__ pour l'exécution sans interface (blender -b fichier.blend --python walk_cycle.py -- --save) et appelez main() depuis le pont, de sorte qu'un seul script serve les deux chemins.

6c. Actions sur Blender 5.x (à slots)

Action.fcurves, Action.groups et Action.id_root n'existent pas dans la 5.4. Utilisez les aides au lieu de retaper la navigation dans les channelbags, et liez le slot explicitement :

# session en direct (cwd = dossier de cette compétence) ; renvoie l'audit dans `result`
python3 scripts/blender_mcp.py "import sys; sys.path.insert(0, 'scripts')
import action_compat
result = action_compat.audit()"

# sans interface ; code de sortie 1 quand un slot n'est pas lié
blender -b fichier.blend --python scripts/action_compat.py
from action_compat import iter_fcurves, ensure_fcurve, assign_action
slot = assign_action(obj, action)                 # assigner seul laisse action_slot à None
ensure_fcurve(action, slot, 'pose.bones["Head"].rotation_euler', 1, group_name="HeadTwist")

Mode d'échec mesuré : assigner une action qui a déjà un slot à un ID différent laisse animation_data.action_slot is None et le rig reste au repos sans erreur (la tête à 4.0 au lieu de 3.92 animé). Porte : action_compat.py rapporte slot_assigned: true et slot_fcurves > 0 pour chaque objet animé. Utilisez aussi channelbag.fcurves.new(..., group_name=...), jamais action_group=.

Détails et le reste de l'API mesurée : reference/blender-5x-api.md.

7. Exporter en glTF

glTF n'a ni drivers, ni propriétés personnalisées, ni contraintes. Baked les :

  1. Renommez l'action source (*_src) pour que l'action bakeée reçoive un nom propre.
  2. Dissociez l'objet widget de forme personnalisée, sinon il devient un nœud vide.
  3. Effacez l'action, pose_bone.driver_remove(...), keyframez rotation_euler[0] aux extrêmes de la pose.
  4. Exportez avec export_skins=True, export_animations=True, export_animation_mode="ACTIONS", export_yup=True.
  5. Restaurez : réassociez l'action, supprimez le bake, reliez le widget, rajoutez les drivers, frame_set(1), sauvegardez.

Les avertissements concernant « Baking animation because of unsupported constraints » sont attendus.

Rendu sur demande (propriétaire uniquement)

Déclencheur : le propriétaire dit explicitement « rendu » ou demande une image/vidéo d'aperçu. Ne faites pas de rendu de votre propre initiative, et n'utilisez pas le rendu comme vérification.

Blender 5.4 expose EEVEE sous le nom BLENDER_EEVEE (pas BLENDER_EEVEE_NEXT), donc choisissez depuis l'énumération plutôt que de coder en dur un nom spécifique à une version. Les scènes glTF n'ont ni caméra ni lumières — créez-les d'abord, dans une collection Render_Setup.

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/projet/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}

Règles pour ce chemin : sauvegardez .blend d'abord, écrivez dans <projet>/render/, rapportez le chemin absolu et la taille du fichier, augmentez le délai d'attente du client, et ne démarrez jamais un rendu sans interface d'un fichier avec des modifications non sauvegardées.

Pièges de Blender 5.4

SymptômeCauseCorrectif
Un driver ne fait riengraphe de dépendances non évaluéscene.frame_set(f)
Action.fcurves manquantactions à slotsact.layers[0].strips[0].channelbags[*].fcurves, ou scripts/action_compat.py
Le rig ne bouge pas, pas d'erreurl'action assignée n'a pas de slot lié à cet IDassign_action() / définir animation_data.action_slot
fcurves.new(action_group=...) TypeErrorle mot-clé 5.4 est group_namecb.fcurves.new(path, index, group_name="...")
L'appel asset.mark() échouel'opérateur lit la sélection de l'OutlinerAPI obj.asset_mark()
Les keyframes de propriété ignoréesmauvais chemin de données'["open"]'
Suffixe .001 sur l'actioncollision de nomsrenommez d'abord l'action source
Widget dans le GLBl'objet est encore dans une collection de la scènedissociez pendant l'exportation
Commande non reconnue--factory-startup / extension désactivéerelancez en ligne
Démarrage automatique silencieuxport occupélibérez le port, relancez (pas de nouvelle tentative)
Erreur d'énumération du rendumauvais nom de moteursélectionnez BLENDER_EEVEE depuis l'énumération
enum "OCTAHEDRAL" introuvablel'affichage de l'armature est une donnée, pas un objetrig.data.display_type = "OCTAHEDRAL"
bpy.context.window est Nonela construction en arrière-plan n'a pas de fenêtreprotégez avec window_manager.windows
La réimportation FBX fait flotter le personnagel'importateur marque la racine comme un os connecté et ignore sa translationvérifiez le fichier avec scripts/inspect_fbx.py, pas le round trip

Livrables

  • .blend — rig faisant autorité, sauvegardé à la trame de repos, avec un bloc de texte README_RIG.
  • .glb — skiné + animé, vérifié par réimportation.
  • README.md dans le dossier du projet avec pivot, os, propriété, angles, nombres.

Skills associés