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 viewportdocs/RIGGING_PLAYBOOK.md— método completo de rigging y receta de exportación/restauracióndocs/VERIFICATION.md— umbrales de métricas y fragmentos de códigodocs/RENDERING.md— ruta de renderizado bajo solicitud del propietarioreference/roblox-avatar.md— contrato corporal R15, IK de caminata en el lugar, verificación FBXreference/blender-5x-api.md— acciones con slots, API medida 5.4, origen temporal glTFreference/glb-qa.md— compuertas GLB sin render, líneas base, evidencia de prueba negativadocs/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
- 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.blendprimero y vuelve a abrir el mismo archivo. - 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).
- 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 (FRONTpara activos planos XZ). - Usa la malla evaluada, nunca la original:
obj.evaluated_get(depsgraph).to_mesh(). - Fuerza la evaluación del driver con
scene.frame_set(f)—view_layer.update()no es suficiente. - 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. - Un
execute= un paso atómico e idempotente que devuelve las métricas que lo prueban. - 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étrica | Umbral |
|---|---|
| Desviación de reposo vs malla fuente | < 1e-5 |
| Costura del bucle (último fotograma vs primero) | 0 |
| Proporción de área de cara abierta/cerrada | 0.99–1.01 |
| Mango y mandíbula se mueven hacia afuera | > 0 |
| Vértices ponderados | 100% |
| Caras no manifold / de área cero | 0 |
| 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:
- Renombra la acción fuente (
*_src) para que la acción horneada obtenga un nombre limpio. - Desenlaza el objeto widget de forma personalizada, de lo contrario se convierte en un nodo vacío.
- Limpia la acción,
pose_bone.driver_remove(...), keyframerotation_euler[0]en los extremos de la pose. - Exporta con
export_skins=True,export_animations=True,export_animation_mode="ACTIONS",export_yup=True. - 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íntoma | Causa | Solución |
|---|---|---|
| El driver no cambia nada | depsgraph no evaluado | scene.frame_set(f) |
Action.fcurves faltante | acciones con slots | act.layers[0].strips[0].channelbags[*].fcurves, o scripts/action_compat.py |
| El rig no se mueve, sin error | acción asignada sin slot vinculado a este ID | assign_action() / establecer animation_data.action_slot |
fcurves.new(action_group=...) TypeError | la palabra clave en 5.4 es group_name | cb.fcurves.new(path, index, group_name="...") |
asset.mark() falla en poll | el operador lee la selección del Outliner | API obj.asset_mark() |
| Keyframes de propiedad ignorados | ruta de datos incorrecta | '["open"]' |
Sufijo de acción .001 | colisión de nombres | renombra la acción fuente primero |
| Widget en GLB | objeto todavía en una colección de escena | desenlázalo durante la exportación |
Unrecognized command | --factory-startup / extensión desactivada | reinicia en línea |
| Autoinicio silencioso | puerto ocupado | libera el puerto, reinicia (sin reintento) |
| Error de enum de render | nombre de motor incorrecto | selecciona BLENDER_EEVEE del enum |
enum "OCTAHEDRAL" not found | la visualización de la armadura son datos, no objeto | rig.data.display_type = "OCTAHEDRAL" |
bpy.context.window es None | compilación sin cabeza no tiene ventana | protege con window_manager.windows |
| La reimportación FBX flota el personaje | el importador marca la raíz como un hueso conectado y descarta su traslación | verifica 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 textoREADME_RIG..glb— con piel + animación, verificado mediante reimportación.README.mden la carpeta del proyecto con pivote, huesos, propiedad, ángulos, números.