CommunityImagengithub.com

blender-live-rigging

Rig, editar, verificar y exportar activos 3D en vivo dentro de la aplicación Blender del usuario a través del puente oficial MCP de Blender. Se usa para armaduras, skinning, rigs mecánicos/articulados, drivers, controles de propiedades personalizadas, verificación de malla evaluada, exportación glTF horneada y renders solo cuando el propietario lo solicita explícitamente.

¿Qué es blender-live-rigging?

Esta habilidad permite controlar una instancia de Blender que el usuario ya tiene abierta, sin necesidad de procesos en segundo plano o cerrar la aplicación. Se comunica a través del puente oficial MCP de Blender (bl_ext.blenderlab.mcp) en 127.0.0.1:9876. El rigging se realiza en la GUI en vivo, verificando siempre con la malla evaluada (no la original) y usando métricas numéricas para garantizar la calidad. Por defecto no se renderiza a menos que el propietario lo solicite explícitamente; la verificación se basa en coordenadas de vértices, anchos, áreas y proporciones. Soporta exportación a glTF con animaciones horneadas y verificación mediante reimportación en un proceso separado de Blender. Incluye compatibilidad con Blender 5.x (acciones con slots) y trampas comunes documentadas.

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

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Blender Live Rigging

Controla la instancia de Blender que el usuario ya está viendo. Sin lotes sin cabeza, ni cerrar su aplicación. Cada afirmación de "listo" debe estar respaldada por números leídos del grafo de dependencias evaluado. El renderizado está desactivado por defecto y solo ocurre cuando el propietario lo solicita.

Documentos del repositorio (léelos cuando necesites profundidad, no en cada ocasión):

  • docs/MCP_BRIDGE.md — protocolo, modos de inicio, errores comunes, enfoque del viewport
  • docs/RIGGING_PLAYBOOK.md — método completo de rigging y receta de exportación/restauración
  • docs/VERIFICATION.md — umbrales de métricas y fragmentos de código
  • docs/RENDERING.md — ruta de renderizado bajo solicitud del propietario
  • reference/roblox-avatar.md — contrato corporal R15, IK de caminata en el lugar, verificación FBX
  • reference/blender-5x-api.md — acciones con slots, API medida 5.4, origen temporal glTF
  • reference/glb-qa.md — compuertas GLB sin render, líneas base, evidencia de prueba negativa
  • docs/CASE_STUDY_KNIGHT.md — avatar R15 medido + bucle de caminata (raíz del repositorio)

Si esta habilidad se instaló desde andypratama3/blender-mcp, la raíz del repositorio está tres niveles arriba de este archivo (skills/blender-live-rigging/SKILL.md).

Reglas estrictas

  1. Solo GUI en vivo. Confirma bpy.app.background == False. Nunca mates Blender mientras el usuario esté trabajando; si debes reiniciar por un conflicto de puerto, guarda el .blend primero y vuelve a abrir el mismo archivo.
  2. Sin render a menos que el propietario lo solicite. La verificación predeterminada es numérica: coordenadas de vértices, anchos, áreas, proporciones. Cuando el propietario solicite explícitamente un render, hazlo en la sesión en vivo (ver Renderizar bajo solicitud).
  3. Enfoca el viewport en lo que editas, antes y después del cambio: selecciona los objetos/huesos, activa uno, ejecuta view3d.view_axis + view3d.view_selected. Elige el eje que coincida con el plano del activo (FRONT para activos planos XZ).
  4. Usa la malla evaluada, nunca la original: obj.evaluated_get(depsgraph).to_mesh().
  5. Fuerza la evaluación del driver con scene.frame_set(f) — view_layer.update() no es suficiente.
  6. Guarda incrementalmente con bpy.ops.wm.save_as_mainfile(filepath=..., compress=True) en cada hito; mantén los entregables dentro de la carpeta del proyecto.
  7. Un execute = un paso atómico e idempotente que devuelve las métricas que lo prueban.
  8. Mide lo que toca el suelo en la malla, no en el hueso. La cola de un hueso puede estar 0.4 studs por encima de la suela, por lo que una compuerta de cola de hueso pasa mientras la bota se hunde en el suelo. Usa el vértice mundial más bajo de la malla evaluada.

1. Conectar

El puente es el complemento oficial bl_ext.blenderlab.mcp en 127.0.0.1:9876.

lsof -nP -iTCP:9876 -sTCP:LISTEN          # debe estar libre antes de iniciar
open -a Blender --args --online-mode "/ruta/absoluta/archivo.blend"   # macOS
sleep 8 && lsof -nP -iTCP:9876 -sTCP:LISTEN

--online-mode es obligatorio (el autoinicio requiere bpy.app.online_access), y nunca uses --factory-startup (deshabilita la extensión). Luego:

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

2. Inspeccionar el activo

Importa glTF, hornea matrix_world en los datos de la malla, elimina padres vacíos, suelda duplicados (remove_doubles(1e-5)), cuenta capas conectadas e imprime una silueta ASCII para encontrar el plano, el pivote y las partes móviles:

blender -b --factory-startup --python scripts/inspect_glb.py -- "/ruta/activo.glb"

3. Decidir la topología del rig

Para activos mecánicos: partes rígidas, pesos rígidos, un hueso por parte. Para formas de tijera/pinza, empareja partes en diagonal (mitad del mango izquierdo + mitad de la mandíbula derecha) para que los mangos y las mandíbulas se abran juntos; una división en la línea media hace que las mandíbulas se cierren mientras los mangos se abren.

Coloca el pivote de la bisagra donde se encuentren los mangos, pon el corte de la costura allí también, y alinea el hueso para que rotation_euler.x sea exactamente el eje mundial de la bisagra:

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

4. Preparar la malla

Bisecciona en cada límite de parte rígida con use_fill=True, desplaza las tapas ~0.0004 para eliminar el z-fighting, invierte solo las caras de las tapas (mantén las normales de split personalizadas glTF), asigna grupos de vértices por parte antes de unir, luego padre con un modificador ARMATURE.

5. Controles y animación

Una propiedad personalizada (open, 0–1) controla cada hueso a través de expresiones de driver simples, más LIMIT_ROTATION como red de seguridad. Establece rotation_mode = "XYZ" antes de controlar rotation_euler. Keyframe la propiedad — no los huesos — para la acción de bucle, y establece BEZIER + AUTO_CLAMPED.

6. Verificar (compuerta antes de afirmar éxito)

MétricaUmbral
Desviación de reposo vs malla fuente< 1e-5
Costura del bucle (último fotograma vs primero)0
Proporción de área de cara abierta/cerrada0.99–1.01
Mango y mandíbula se mueven hacia afuera> 0
Vértices ponderados100%
Caras no manifold / de área cero0
Vértice deformado más bajo vs suelo≥ −0.006, pie de postura 0 ± 0.006

scripts/verify_rig_glb.py reimporta el GLB exportado en un proceso separado de Blender (nunca molestar la sesión en vivo) e imprime conteos de nodos/piel/animación más anchos en los fotogramas 1/15/30/60.

Para locomoción, resuelve las piernas con IK de dos huesos contra un objetivo de tobillo en lugar de animar manualmente los ángulos de las articulaciones, luego mide cada fotograma:

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

Si una compuerta de hueso y una compuerta de malla están en desacuerdo, la compuerta de malla tiene la razón.

6d. QA de GLB sin render

python3 scripts/glb_qa.py export/modelo.glb --loop --max-tris 20000
python3 scripts/glb_qa.py export/herramienta.glb --manifold

Solo biblioteca estándar, sin Blender: lee el contenedor GLB directamente y verifica la longitud del encabezado, límites de accessor, sumas de pesos, vértices sin peso, índices de articulaciones, conteos de pose de ligadura, orden de keyframes, norma del cuaternión, cierre de bucle, NaN y (con --manifold) bordes de frontera. Sale con código 1 en cualquier fallo. verify_rig_glb.py sigue siendo el propietario de la medición del ancho de las partes móviles. Compuertas, líneas base y los cinco archivos deliberadamente rotos que detectaron: reference/glb-qa.md.

6b. Ejecutar un script de proyecto multifile en vivo

Los scripts que importan sus propios módulos deben cargarse por ruta dentro de la sesión en vivo:

import importlib.util, sys
spec = importlib.util.spec_from_file_location("walk_cycle", "/abs/proyecto/walk_cycle.py")
mod = importlib.util.module_from_spec(spec)
sys.modules["walk_cycle"] = mod          # de lo contrario dataclasses/imports ven un duplicado
spec.loader.exec_module(mod)
result = mod.main(save=True)             # devuelve un dict de compuertas medidas

Mantén __main__ para la ejecución sin cabeza (blender -b archivo.blend --python walk_cycle.py -- --save) y llama a main() desde el puente, para que un script sirva para ambas rutas.

6c. Acciones en Blender 5.x (con slots)

Action.fcurves, Action.groups y Action.id_root no existen en 5.4. Usa los ayudantes en lugar de volver a escribir la caminata del channelbag, y enlaza el slot explícitamente:

# sesión en vivo (cwd = esta carpeta de habilidad); devuelve la auditoría como `result`
python3 scripts/blender_mcp.py "import sys; sys.path.insert(0, 'scripts')
import action_compat
result = action_compat.audit()"

# sin cabeza; sale con 1 cuando un slot está desenlazado
blender -b archivo.blend --python scripts/action_compat.py
from action_compat import iter_fcurves, ensure_fcurve, assign_action
slot = assign_action(obj, action)                 # solo asignar deja action_slot en None
ensure_fcurve(action, slot, 'pose.bones["Head"].rotation_euler', 1, group_name="HeadTwist")

Modo de fallo medido: asignar una acción que ya tiene un slot a un ID diferente deja animation_data.action_slot is None y el rig se queda en reposo sin error (cabeza en 4.0 en lugar del 3.92 animado). Compuerta: action_compat.py reporta slot_assigned: true y slot_fcurves > 0 para cada objeto animado. También channelbag.fcurves.new(..., group_name=...), nunca action_group=.

Detalles y el resto de la API medida: reference/blender-5x-api.md.

7. Exportar glTF

glTF no tiene drivers, propiedades personalizadas ni restricciones. Hornéalos:

  1. Renombra la acción fuente (*_src) para que la acción horneada obtenga un nombre limpio.
  2. Desenlaza el objeto widget de forma personalizada, de lo contrario se convierte en un nodo vacío.
  3. Limpia la acción, pose_bone.driver_remove(...), keyframe rotation_euler[0] en los extremos de la pose.
  4. Exporta con export_skins=True, export_animations=True, export_animation_mode="ACTIONS", export_yup=True.
  5. Restaura: reasigna la acción, elimina el horneado, vuelve a enlazar el widget, vuelve a añadir los drivers, frame_set(1), guarda.

Las advertencias sobre "Horneando animación debido a restricciones no soportadas" son esperadas.

Renderizar bajo solicitud (solo propietario)

Disparador: el propietario dice explícitamente render, o solicita una imagen/vista previa. No renderices por iniciativa propia, y no renderices como verificación.

Blender 5.4 expone EEVEE como BLENDER_EEVEE (no BLENDER_EEVEE_NEXT), así que elige del enum en lugar de codificar un nombre específico de versión. Las escenas glTF no tienen cámara ni luces — créalas primero, en una colección 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/proyecto/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}

Reglas para esta ruta: guarda el .blend primero, escribe dentro de <proyecto>/render/, reporta la ruta absoluta y el tamaño del archivo, aumenta el tiempo de espera del cliente, y nunca inicies un render sin cabeza de un archivo con cambios sin guardar.

Trampas de Blender 5.4

SíntomaCausaSolución
El driver no cambia nadadepsgraph no evaluadoscene.frame_set(f)
Action.fcurves faltanteacciones con slotsact.layers[0].strips[0].channelbags[*].fcurves, o scripts/action_compat.py
El rig no se mueve, sin erroracción asignada sin slot vinculado a este IDassign_action() / establecer animation_data.action_slot
fcurves.new(action_group=...) TypeErrorla palabra clave en 5.4 es group_namecb.fcurves.new(path, index, group_name="...")
asset.mark() falla en pollel operador lee la selección del OutlinerAPI obj.asset_mark()
Keyframes de propiedad ignoradosruta de datos incorrecta'["open"]'
Sufijo de acción .001colisión de nombresrenombra la acción fuente primero
Widget en GLBobjeto todavía en una colección de escenadesenlázalo durante la exportación
Unrecognized command--factory-startup / extensión desactivadareinicia en línea
Autoinicio silenciosopuerto ocupadolibera el puerto, reinicia (sin reintento)
Error de enum de rendernombre de motor incorrectoselecciona BLENDER_EEVEE del enum
enum "OCTAHEDRAL" not foundla visualización de la armadura son datos, no objetorig.data.display_type = "OCTAHEDRAL"
bpy.context.window es Nonecompilación sin cabeza no tiene ventanaprotege con window_manager.windows
La reimportación FBX flota el personajeel importador marca la raíz como un hueso conectado y descarta su traslaciónverifica el archivo con scripts/inspect_fbx.py, no con el ida y vuelta

Entregables

  • .blend — rig autoritativo, guardado en el fotograma de reposo, con un bloque de texto README_RIG.
  • .glb — con piel + animación, verificado mediante reimportación.
  • README.md en la carpeta del proyecto con pivote, huesos, propiedad, ángulos, números.

Skills relacionados