CommunityImagemgithub.com

blender-live-rigging

Rig, edite, verifique e exporte assets 3D ao vivo na instância aberta do Blender do usuário através da ponte oficial do socket MCP do Blender. Use para armaduras, skinning, rigs mecânicos/dobradiças, drivers, controles de propriedades personalizadas, verificação de malha avaliada, exportação glTF assada e renderizações somente quando o proprietário solicitar explicitamente.

O que é blender-live-rigging?

Esta habilidade permite que um agente de IA (como Claude Code, Cursor ou Codex) controle diretamente uma instância ativa do Blender 3D via uma ponte WebSocket MCP, eliminando a necessidade de processos headless ou de fechar o aplicativo do usuário. Ela é projetada para tarefas de rigging, edição, verificação e exportação de assets 3D, mantendo total compatibilidade com a interface gráfica ao vivo. A habilidade é útil para desenvolvedores e artistas técnicos que precisam automatizar fluxos de trabalho complexos de rigging — como criação de armaduras, skinning, rigs mecânicos com dobradiças, drivers e controles de propriedades personalizadas — sem interromper a sessão de trabalho do usuário. Suporta o protocolo MCP Bridge oficial do Blender via `bl_ext.blenderlab.mcp` na porta `127.0.0.1:9876` e oferece um conjunto robusto de métodos de verificação numérica baseados na malha avaliada do depsgraph, garantindo que o agente possa confirmar metricamente a conclusão das etapas. A habilidade também gerencia a exportação de ativos para glTF, incluindo baking de animações e a preparação de cenas para renderização, mas somente renderiza quando o proprietário explicitamente solicitar — nunca por iniciativa própria. Ela inclui scripts auxiliares para inspeção de assets, verificação de rigs, compatibilidade com Blender 5.x (ações slotadas) e QA de GLB puro.

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

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Blender Live Rigging

Controle a instância do Blender que o usuário já está visualizando. Sem lotes headless, sem fechar o aplicativo dele. Cada afirmação de "concluído" deve ser respaldada por números lidos do depsgraph avaliado. Renderização está desligada por padrão e só acontece quando o proprietário pede.

Documentos do repositório (leia quando precisar de profundidade, não toda vez):

  • docs/MCP_BRIDGE.md — protocolo, modos de inicialização, armadilhas, foco da viewport
  • docs/RIGGING_PLAYBOOK.md — método completo de rigging e receita de exportação/restauração
  • docs/VERIFICATION.md — limites métricos e trechos de código
  • docs/RENDERING.md — caminho de renderização sob solicitação do proprietário
  • reference/roblox-avatar.md — contrato de corpo R15, IK de caminhada in-loco, verificação FBX
  • reference/blender-5x-api.md — ações slotadas, API medida do 5.4, origem temporal glTF
  • reference/glb-qa.md — portões GLB sem renderização, linhas de base, evidências de teste negativo
  • docs/CASE_STUDY_KNIGHT.md — avatar R15 medido + loop de caminhada (raiz do repositório)

Se esta habilidade foi instalada de andypratama3/blender-mcp, a raiz do repositório está três níveis acima deste arquivo (skills/blender-live-rigging/SKILL.md).

Regras rígidas

  1. Apenas GUI ao vivo. Confirme bpy.app.background == False. Nunca mate o Blender enquanto o usuário estiver trabalhando; se precisar reiniciar por conflito de porta, salve o .blend primeiro e reabra o mesmo arquivo.
  2. Sem renderização a menos que o proprietário peça. A verificação padrão é numérica: coordenadas de vértices, larguras, áreas, proporções. Quando o proprietário solicitar explicitamente uma renderização, faça-a na sessão ao vivo (veja Renderizar sob solicitação).
  3. Foque a viewport no que você edita, antes e depois da alteração: selecione o(s) objeto(s)/ossos, ative um, execute view3d.view_axis + view3d.view_selected. Escolha o eixo correspondente ao plano do asset (FRONT para assets planos em XZ).
  4. Use a malha avaliada, nunca a original: obj.evaluated_get(depsgraph).to_mesh().
  5. Force a avaliação do driver com scene.frame_set(f) — view_layer.update() não é suficiente.
  6. Salve incrementalmente com bpy.ops.wm.save_as_mainfile(filepath=..., compress=True) a cada marco; mantenha os entregáveis dentro da pasta do projeto.
  7. Um execute = um passo atômico e idempotente que retorna as métricas que o comprovam.
  8. Meça o que toca o chão na malha, não no osso. A ponta de um osso pode estar 0,4 stud acima da sola, então um portão de ponta de osso passa enquanto a bota afunda no chão. Use o vértice mundial mais baixo da malha avaliada.

1. Conectar

A ponte é o add-on oficial bl_ext.blenderlab.mcp em 127.0.0.1:9876.

lsof -nP -iTCP:9876 -sTCP:LISTEN          # deve estar livre antes da inicialização
open -a Blender --args --online-mode "/caminho/absoluto/arquivo.blend"   # macOS
sleep 8 && lsof -nP -iTCP:9876 -sTCP:LISTEN

--online-mode é obrigatório (inicialização automática requer bpy.app.online_access), e nunca use --factory-startup (ele desabilita a extensão). Em seguida:

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

2. Inspecionar o asset

Importe glTF, asse matrix_world nos dados da malha, remova pais vazios, solde duplicatas (remove_doubles(1e-5)), conte cascas conectadas e imprima uma silhueta ASCII para encontrar o plano, pivô e partes móveis:

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

3. Decidir a topologia do rig

Para assets mecânicos: partes rígidas, pesos rígidos, um osso por parte. Para formas de tesoura/alicate, emparelhe partes diagonalmente (cabo esquerdo + metade da mandíbula direita) para que cabos e mandíbulas abram juntos; uma divisão na linha média faz as mandíbulas fecharem enquanto os cabos abrem.

Coloque o pivô da dobradiça onde os cabos se encontram, coloque o corte da costura lá também, e alinhe o osso para que rotation_euler.x seja exatamente o eixo mundial da dobradiça:

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

4. Preparar a malha

Bisseccione em cada limite de parte rígida com use_fill=True, desloque as tampas ~0.0004 para matar z-fighting, inverta apenas as faces da tampa (mantenha as normais de split personalizadas glTF), atribua grupos de vértices por parte antes de unir, então parenteie com um modificador ARMATURE.

5. Controles e animação

Uma propriedade personalizada (open, 0–1) aciona cada osso através de expressões de driver simples, mais LIMIT_ROTATION como rede de segurança. Defina rotation_mode = "XYZ" antes de acionar rotation_euler. Anime a propriedade — não os ossos — para a ação de loop, e defina BEZIER + AUTO_CLAMPED.

6. Verificar (portão antes de afirmar sucesso)

MétricaLimite
Desvio de repouso vs malha de origem< 1e-5
Costura do loop (último quadro vs primeiro)0
Proporção de área da face aberta/fechada0.99–1.01
Cabo e mandíbula ambos se movem para fora> 0
Vértices com peso100%
Faces não-manifold / área zero0
Vértice deformado mais baixo vs chão≥ −0.006, pé de apoio 0 ± 0.006

scripts/verify_rig_glb.py reimporta o GLB exportado em um processo separado do Blender (nunca perturbe a sessão ao vivo) e imprime contagens de nós/skin/animação mais larguras nos quadros 1/15/30/60.

Para locomoção, resolva as pernas com IK de dois ossos contra um alvo de tornozelo em vez de animar manualmente ângulos de juntas, então meça cada quadro:

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

Se um portão de osso e um portão de malha discordarem, o portão de malha está certo.

6d. QA de GLB sem renderização

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

Apenas biblioteca padrão, sem Blender: ele lê o contêiner GLB diretamente e valida comprimento do cabeçalho, limites do accessor, soma de pesos, vértices sem peso, índices de juntas, contagens de pose de ligação, ordem dos quadros-chave, norma do quaternion, fechamento de loop, NaN e (com --manifold) bordas de limite. Saída com código 1 em qualquer falha. verify_rig_glb.py ainda é responsável pela medição de largura das partes móveis. Portões, linhas de base e os cinco arquivos deliberadamente quebrados que eles pegaram: reference/glb-qa.md.

6b. Executar um script de projeto multifile ao vivo

Scripts que importam seus próprios módulos devem ser carregados por caminho dentro da sessão ao vivo:

import importlib.util, sys
spec = importlib.util.spec_from_file_location("walk_cycle", "/abs/projeto/walk_cycle.py")
mod = importlib.util.module_from_spec(spec)
sys.modules["walk_cycle"] = mod          # senão dataclasses/imports veem uma duplicata
spec.loader.exec_module(mod)
result = mod.main(save=True)             # retorna um dicionário de portões medidos

Mantenha __main__ para a execução headless (blender -b arquivo.blend --python walk_cycle.py -- --save) e chame main() da ponte, para que um script sirva a ambos os caminhos.

6c. Ações no Blender 5.x (slotadas)

Action.fcurves, Action.groups e Action.id_root não existem no 5.4. Use os auxiliares em vez de redigitar a caminhada do channelbag, e vincule o slot explicitamente:

# sessão ao vivo (cwd = esta pasta de habilidade); retorna a auditoria como `result`
python3 scripts/blender_mcp.py "import sys; sys.path.insert(0, 'scripts')
import action_compat
result = action_compat.audit()"

# headless; saída com código 1 quando um slot não está vinculado
blender -b arquivo.blend --python scripts/action_compat.py
from action_compat import iter_fcurves, ensure_fcurve, assign_action
slot = assign_action(obj, action)                 # apenas atribuir deixa action_slot None
ensure_fcurve(action, slot, 'pose.bones["Head"].rotation_euler', 1, group_name="HeadTwist")

Modo de falha medido: atribuir uma ação que já tem um slot a um ID diferente deixa animation_data.action_slot is None e o rig fica parado sem erro (cabeça em 4.0 em vez da animada 3.92). Portão: action_compat.py reporta slot_assigned: true e slot_fcurves > 0 para cada objeto animado. Também channelbag.fcurves.new(..., group_name=...), nunca action_group=.

Detalhes e o resto da API medida: reference/blender-5x-api.md.

7. Exportar glTF

glTF não tem drivers, propriedades personalizadas ou constraints. Asse-os:

  1. Renomeie a ação de origem (*_src) para que a ação assada tenha um nome limpo.
  2. Desvincule o objeto widget de forma personalizada, senão ele se torna um nó vazio.
  3. Limpe a ação, pose_bone.driver_remove(...), anime rotation_euler[0] nos extremos da pose.
  4. Exporte com export_skins=True, export_animations=True, export_animation_mode="ACTIONS", export_yup=True.
  5. Restaure: reatribua a ação, delete o bake, religue o widget, readicione os drivers, frame_set(1), salve.

Avisos sobre "Assando animação devido a constraints não suportadas" são esperados.

Renderizar sob solicitação (apenas proprietário)

Gatilho: o proprietário diz explicitamente renderizar, ou pede uma imagem/vídeo de pré-visualização. Não renderize por iniciativa própria, e não renderize como verificação.

Blender 5.4 expõe EEVEE como BLENDER_EEVEE (não BLENDER_EEVEE_NEXT), então escolha do enum em vez de codificar um nome específico de versão. Cenas glTF não têm câmera e nem luzes — crie-as primeiro, em uma coleção 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/projeto/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}

Regras para este caminho: salve .blend primeiro, escreva dentro de <projeto>/render/, reporte o caminho absoluto e tamanho do arquivo, aumente o timeout do cliente e nunca inicie uma renderização headless de um arquivo com alterações não salvas.

Armadilhas do Blender 5.4

SintomaCausaCorreção
Driver não altera nadadepsgraph não avaliadoscene.frame_set(f)
Action.fcurves ausenteações slotadasact.layers[0].strips[0].channelbags[*].fcurves, ou scripts/action_compat.py
Rig não se move, nenhum erroação atribuída não tem slot vinculado a este IDassign_action() / definir animation_data.action_slot
fcurves.new(action_group=...) TypeError5.4 palavra-chave é group_namecb.fcurves.new(path, index, group_name="...")
asset.mark() poll falhaoperador lê seleção do OutlinerAPI obj.asset_mark()
Keyframes de propriedade ignoradoscaminho de dados errado'["open"]'
Sufixo de ação .001colisão de nomerenomeie a ação de origem primeiro
Widget no GLBobjeto ainda em uma coleção da cenadesvincule durante a exportação
Comando não reconhecido--factory-startup / extensão desligadareinicie online
Inicialização automática silenciosaporta ocupadalibere porta, reinicie (sem repetição)
Erro de enum de renderizaçãonome do motor erradoselecione BLENDER_EEVEE do enum
enum "OCTAHEDRAL" não encontradoexibição da armadura é dados, não objetorig.data.display_type = "OCTAHEDRAL"
bpy.context.window é Nonecompilação em background não tem janelaproteja com window_manager.windows
Reimportação FBX flutua o personagemimportador marca a raiz como osso conectado e descarta sua translaçãoverifique o arquivo com scripts/inspect_fbx.py, não o round trip

Entregáveis

  • .blend — rig oficial, salvo no quadro de repouso, com um bloco de texto README_RIG.
  • .glb — com skin + animado, verificado por reimportação.
  • README.md na pasta do projeto com pivô, ossos, propriedade, ângulos, números.

Habilidades Relacionadas