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 viewportdocs/RIGGING_PLAYBOOK.md— método completo de rigging e receita de exportação/restauraçãodocs/VERIFICATION.md— limites métricos e trechos de códigodocs/RENDERING.md— caminho de renderização sob solicitação do proprietárioreference/roblox-avatar.md— contrato de corpo R15, IK de caminhada in-loco, verificação FBXreference/blender-5x-api.md— ações slotadas, API medida do 5.4, origem temporal glTFreference/glb-qa.md— portões GLB sem renderização, linhas de base, evidências de teste negativodocs/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
- 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.blendprimeiro e reabra o mesmo arquivo. - 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).
- 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 (FRONTpara assets planos em XZ). - Use a malha avaliada, nunca a original:
obj.evaluated_get(depsgraph).to_mesh(). - Force a avaliação do driver com
scene.frame_set(f)—view_layer.update()não é suficiente. - Salve incrementalmente com
bpy.ops.wm.save_as_mainfile(filepath=..., compress=True)a cada marco; mantenha os entregáveis dentro da pasta do projeto. - Um
execute= um passo atômico e idempotente que retorna as métricas que o comprovam. - 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étrica | Limite |
|---|---|
| Desvio de repouso vs malha de origem | < 1e-5 |
| Costura do loop (último quadro vs primeiro) | 0 |
| Proporção de área da face aberta/fechada | 0.99–1.01 |
| Cabo e mandíbula ambos se movem para fora | > 0 |
| Vértices com peso | 100% |
| Faces não-manifold / área zero | 0 |
| 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:
- Renomeie a ação de origem (
*_src) para que a ação assada tenha um nome limpo. - Desvincule o objeto widget de forma personalizada, senão ele se torna um nó vazio.
- Limpe a ação,
pose_bone.driver_remove(...), animerotation_euler[0]nos extremos da pose. - Exporte com
export_skins=True,export_animations=True,export_animation_mode="ACTIONS",export_yup=True. - 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
| Sintoma | Causa | Correção |
|---|---|---|
| Driver não altera nada | depsgraph não avaliado | scene.frame_set(f) |
Action.fcurves ausente | ações slotadas | act.layers[0].strips[0].channelbags[*].fcurves, ou scripts/action_compat.py |
| Rig não se move, nenhum erro | ação atribuída não tem slot vinculado a este ID | assign_action() / definir animation_data.action_slot |
fcurves.new(action_group=...) TypeError | 5.4 palavra-chave é group_name | cb.fcurves.new(path, index, group_name="...") |
asset.mark() poll falha | operador lê seleção do Outliner | API obj.asset_mark() |
| Keyframes de propriedade ignorados | caminho de dados errado | '["open"]' |
Sufixo de ação .001 | colisão de nome | renomeie a ação de origem primeiro |
| Widget no GLB | objeto ainda em uma coleção da cena | desvincule durante a exportação |
Comando não reconhecido | --factory-startup / extensão desligada | reinicie online |
| Inicialização automática silenciosa | porta ocupada | libere porta, reinicie (sem repetição) |
| Erro de enum de renderização | nome do motor errado | selecione BLENDER_EEVEE do enum |
enum "OCTAHEDRAL" não encontrado | exibição da armadura é dados, não objeto | rig.data.display_type = "OCTAHEDRAL" |
bpy.context.window é None | compilação em background não tem janela | proteja com window_manager.windows |
| Reimportação FBX flutua o personagem | importador marca a raiz como osso conectado e descarta sua translação | verifique 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 textoREADME_RIG..glb— com skin + animado, verificado por reimportação.README.mdna pasta do projeto com pivô, ossos, propriedade, ângulos, números.