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 vuedocs/RIGGING_PLAYBOOK.md— méthode complète de rigging et recette d'exportation/restaurationdocs/VERIFICATION.md— seuils métriques et extraitsdocs/RENDERING.md— chemin de rendu sur demande du propriétairereference/roblox-avatar.md— corps R15, IK de marche sur place, vérification FBXreference/blender-5x-api.md— actions à slots, API mesurée 5.4, origine temporelle glTFreference/glb-qa.md— portes de validation GLB sans rendu, bases de référence, preuves de tests négatifsdocs/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
- 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.blendet rouvrez le même fichier. - 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).
- 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 (FRONTpour les assets plats en XZ). - Utilisez le maillage évalué, jamais l'original :
obj.evaluated_get(depsgraph).to_mesh(). - Forcez l'évaluation des drivers avec
scene.frame_set(f)—view_layer.update()ne suffit pas. - 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. - Un
execute= une étape atomique et idempotente qui renvoie les métriques qui la prouvent. - 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étrique | Seuil |
|---|---|
| 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és | 100% |
| Faces non-manifold / d'aire nulle | 0 |
| 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 :
- Renommez l'action source (
*_src) pour que l'action bakeée reçoive un nom propre. - Dissociez l'objet widget de forme personnalisée, sinon il devient un nœud vide.
- Effacez l'action,
pose_bone.driver_remove(...), keyframezrotation_euler[0]aux extrêmes de la pose. - Exportez avec
export_skins=True,export_animations=True,export_animation_mode="ACTIONS",export_yup=True. - 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ôme | Cause | Correctif |
|---|---|---|
| Un driver ne fait rien | graphe de dépendances non évalué | scene.frame_set(f) |
Action.fcurves manquant | actions à slots | act.layers[0].strips[0].channelbags[*].fcurves, ou scripts/action_compat.py |
| Le rig ne bouge pas, pas d'erreur | l'action assignée n'a pas de slot lié à cet ID | assign_action() / définir animation_data.action_slot |
fcurves.new(action_group=...) TypeError | le mot-clé 5.4 est group_name | cb.fcurves.new(path, index, group_name="...") |
L'appel asset.mark() échoue | l'opérateur lit la sélection de l'Outliner | API obj.asset_mark() |
| Les keyframes de propriété ignorées | mauvais chemin de données | '["open"]' |
Suffixe .001 sur l'action | collision de noms | renommez d'abord l'action source |
| Widget dans le GLB | l'objet est encore dans une collection de la scène | dissociez pendant l'exportation |
Commande non reconnue | --factory-startup / extension désactivée | relancez en ligne |
| Démarrage automatique silencieux | port occupé | libérez le port, relancez (pas de nouvelle tentative) |
| Erreur d'énumération du rendu | mauvais nom de moteur | sélectionnez BLENDER_EEVEE depuis l'énumération |
enum "OCTAHEDRAL" introuvable | l'affichage de l'armature est une donnée, pas un objet | rig.data.display_type = "OCTAHEDRAL" |
bpy.context.window est None | la construction en arrière-plan n'a pas de fenêtre | protégez avec window_manager.windows |
| La réimportation FBX fait flotter le personnage | l'importateur marque la racine comme un os connecté et ignore sa translation | vé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 texteREADME_RIG..glb— skiné + animé, vérifié par réimportation.README.mddans le dossier du projet avec pivot, os, propriété, angles, nombres.