huayuehua15-netizen/unity-blender-mcp

Unity + Blender MCP Pipeline Autônomo

Convenção de caminhos: todos os scripts/, references/, assets/ são relativos ao diretório onde este SKILL.md está localizado. Ao mudar para outro host ou diretório de trabalho, resolva primeiro o diretório do SKILL.md como caminho absoluto antes de chamar. Sempre execute scripts com --python-exit-code 1: o Blender sai com código 0 mesmo em falhas; sem este parâmetro, falhas de auditoria podem parecer sucessos.

Visão Geral

Este skill permite que a IA opere autonomamente o Blender e o Unity através do MCP (Model Context Protocol), produzindo ativos 3D com uma abordagem Asset-First (prioridade a ativos existentes): primeiro busca e reutiliza, depois geração por IA, e só então modelagem do zero, transformando cada ativo em um produto pronto para uso no motor gráfico.

Princípio Central: Árvore de Decisão Asset-First

Ao receber a solicitação "preciso de um modelo/ativo X", siga rigorosamente esta ordem, proibido começar modelando do zero:

1. Fontes MCP Integradas (mais rápido, zero download): search_sketchfab_models / search_polyhaven_assets (HDRI, texturas PBR, modelos realistas) do Blender MCP; import_model (Sketchfab) do Unity MCP.
2. Bibliotecas de Ativos CC0 para Jogos: Kenney, Quaternius, KayKit, Poly Haven, Poly Pizza — estilo consistente, prontas para o motor, risco comercial zero.
3. Área Gratuita de Grandes Marketplaces: Sketchfab (filtrar por CC0/CC-BY e Downloadable), TurboSquid, CGTrader, Fab (Megascans), BlenderKit.
4. Sites Chineses: 3d66, Módulos, Aigoo, etc. — verificar licença e formato individualmente (muitos arquivos .max não abrem no Blender, veja 03).
5. Personagens/Animações: Esqueletos e animações priorizam Mixamo (rigging automático gratuito + milhares de animações), pacotes de personagens animados do Quaternius.
6. Geração por IA: Hyper3D Rodin / Hunyuan3D do Blender MCP, Tripo/Meshy do Unity MCP — apenas para objetos únicos e claros, nunca cenas inteiras/terrenos.
7. Modelagem Manual no Blender (último recurso): quando nada acima atende, ou para estruturas funcionais precisas/modelos de marca personalizados, use bpy/fluxos de modelagem.

Ativos de qualquer fonte devem passar pela auditoria e limpeza do Blender (passo 5) antes de entrar no Unity. Proibido arrastar FBX baixados diretamente para o Unity.

Antes de Começar: Conexão MCP e Descoberta de Ferramentas (obrigatório a cada sessão)

Os nomes das ferramentas MCP variam conforme a implementação (lado Blender: comum ahujasid/blender-mcp; lado Unity: comum CoplayDev/unity-mcp ou o oficial com.unity.ai.assistant). Não presuma nomes fixos.

1. Verifique quais ferramentas MCP estão realmente expostas na sessão atual e mapeie-as contra a "Tabela de Capacidades Padrão" em references/00-mcp-connection.md.
2. Verifique o status da conexão:
   • Blender: Chame ferramentas de inspeção de cena (ex.: get_scene_info) para confirmar que o Blender está aberto e o plugin conectado;
   • Unity: Chame ferramentas de estado do editor/console (ex.: manage_editor / read_console) para confirmar que a ponte está rodando.
3. Ferramentas ausentes ou não conectadas: Siga a tabela de verificação em 00, ou degrade para processamento em lote por linha de comando (blender --background --python, Unity batchmode). Não finja que a chamada teve sucesso.
4. Na primeira conexão, confirme o Render Pipeline do projeto (Built-in / URP / HDRP) e a versão do Unity — os shaders de materiais e a forma de empacotamento dos canais de máscara diferem.

Ciclo de Trabalho Padrão (aplicar a cada operação)

Verificar estado atual (scene_info / console) → Capturar screenshot/leituras como evidência → Executar uma única mudança em pequenos passos
→ Verificar com screenshot ou leitura → Salvar/registrar → Avançar para o próximo passo

• Leia antes de escrever: Antes de alterar qualquer coisa, obtenha informações da cena/objeto; no Blender, faça backup com bpy.ops.wm.save_as_mainfile antes de modificar.
• Passos pequenos: execute_blender_code do Blender MCP tem timeout (~180s); divida tarefas complexas em múltiplos blocos de código; cada bloco deve ser autocontido (import bpy, selecionar objetos por nome novamente, sem depender de variáveis de memória do bloco anterior).
• Resultados devem ser visíveis: Após cada importação/posicionamento/exportação no Blender, valide com get_viewport_screenshot; no Unity, verifique erros com read_console e confirme resultados com consultas de hierarquia/cena.
• Não insista em falhas: Se a mesma operação falhar duas vezes, mude de método ou canal, registre o fenômeno, e não repita a mesma chamada.

Três Fluxos de Trabalho

Fluxo A: Obter um Ativo Existente (mais comum)

Leia references/04-asset-reuse-workflow.md, siga 9 passos: Requisição → Buscar Ativo → Avaliar Candidatos (incluindo licença) → Download Temporário → Auditoria no Blender → Limpeza e Padronização → Exportar FBX → Renderização QA → Importação e Validação no Unity.

• Auditoria: scripts/blender_asset_audit.py (gera relatório JSON de contagem de polígonos, materiais, UVs, transformações, esqueleto, animação; compare com orçamento para decidir manter/descartar).
• Limpeza + Exportação: scripts/blender_prep_unity.py (aplica transformações, centraliza a origem, recalcula normais, uniformiza nomes, exporta FBX com parâmetros corretos para Unity).
• Renderização QA: scripts/blender_asset_qa_render.py (após exportação, gera automaticamente uma imagem de qualidade com iluminação padrão/enquadramento para inspeção visual de texturas, metal roughness, normais e forma; use --turntable N para múltiplos ângulos; dados auditados + verificação ocular aprovam).
• Licenciamento: Para ativos não-CC0, registre cada item em assets/asset-ledger.csv (tipo de licença, URL de origem, requisitos de atribuição).

Fluxo B: Criar um Ativo do Zero

Leia references/05-model-from-scratch.md: imagem de referência/dimensões → modelagem low-poly → detalhamento high-poly → UVs → normal/PBR baking → verificação de orçamento de polígonos e densidade texel → siga os passos de exportação/importação do Fluxo A. Primeiro avalie se a geração por IA pode substituir; itens gerados por IA também precisam de auditoria e retopologia.

Fluxo C: Configuração no Motor Unity (Blender → Unity)

Leia references/06-blender-to-unity.md: configurações de importação de modelo/material/animacão → LOD → colisor → mapeamento de canais de textura de material (diferente para URP/HDRP) → criar Prefab → posicionamento em cena/bake de luzes → build.

• Para importação em lote, coloque assets/unity/Editor/AssetPostprocessor.cs no diretório Assets/Editor/ do projeto Unity (com controle de diretório para processar apenas pastas de importação especificadas, sem poluir todo o projeto).

Scripts e Ativos

Arquivo	Finalidade	Modo de Execução
scripts/blender_asset_audit.py	Auditar a cena atual ou arquivo de modelo especificado, gerar relatório JSON de saúde	MCP: colar código e executar; ou blender --background --python scripts/blender_asset_audit.py -- caminho_do_modelo
scripts/blender_prep_unity.py	Limpar o ativo selecionado e exportar FBX padrão Unity (com opção de bake de animação)	MCP: colar código e chamar prep_and_export(); ou linha de comando -- caminho_de_saída
scripts/blender_asset_qa_render.py	Renderização QA do ativo: enquadramento automático, iluminação HDRI/três pontos, AgX, fundo neutro para imagem de qualidade; suporta --turntable N para múltiplos ângulos	blender --background --python ... -- caminho_do_modelo saída.png [--hdri caminho] [--turntable 3]; MCP: colar e renderizar a cena atual
assets/unity/Editor/AssetPostprocessor.cs	Pós-processamento de importação no Unity: texturas configuradas por sufixo (sRGB, normal, máscara), escala/normais/configurações de malha uniformizadas	Copiar para Assets/Editor/ do projeto Unity
assets/asset-ledger.csv	Modelo de registro de licenças de ativos	Registrar uma linha para cada ativo não-CC0

Índice de Documentos de Referência (carregar conforme necessário)

• references/00-mcp-connection.md: Conexão MCP/descoberta de ferramentas/regras de segurança/degrad ação para linha de comando sem MCP
• references/01-blender-mcp-playbook.md: Tabela de ferramentas Blender MCP + biblioteca de snippets bpy comuns (importação/limpeza/materiais/LOD/exportação/captura de tela)
• references/02-unity-mcp-playbook.md: Tabela de ferramentas Unity MCP + operações de cena/objeto/ativo/material/script/build
• references/03-asset-libraries.md: Enciclopédia de bibliotecas de ativos (licença/formato/seleção/palavras-chave de busca/armadilhas de sites chineses como 3d66)
• references/04-asset-reuse-workflow.md: Fluxo de reutilização de ativos em 9 passos e lista de verificação de aceitação
• references/05-model-from-scratch.md: Quando modelar manualmente, pipeline de geração de ativos de jogo no Blender, tratamento de itens gerados por IA
• references/06-blender-to-unity.md: Pipeline padrão Blender→Unity (eixos/escala/parâmetros FBX/canais de material/LOD/colisor/Humanoid)
• references/07-troubleshooting.md: Tabela sintoma→causa→correção (material rosa/escala/normais/modelo tombado/sem colisor/T-pose/deslizamento de pés, etc.)

Regras de Segurança

• Antes de modificar cenas existentes do Blender/Unity do usuário, salve uma cópia de backup; importação e limpeza devem ocorrer em cenas Blender separadas e no diretório temporário Assets/Imports/ do Unity; só mova para o diretório oficial após aprovação.
• Não exclua nem sobrescreva arquivos originais do usuário; mantenha downloads originais na área temporária e salve os produtos limpos separadamente.
• execute_blender_code e execute_code do Unity podem executar código arbitrário; proibido realizar operações não relacionadas à tarefa atual; operações perigosas (exclusão, renomeação em lote, exportação sobrescrevendo) devem listar os objetos afetados antes de executar.
• Ativos com licença incerta (especialmente NC, apenas para aprendizado, itens gratuitos de 3d66, itens de assinatura paga) nunca entram em projetos comerciais; prefira fontes CC0 ou modelagem manual.
• Nomeação de todos os materiais/texturas/modelos deve seguir o padrão (SM_/SK_/T_BC/N/RMA/M/M_/MI_); nomes de arquivo em chinês e caminhos de textura em chinês devem ser convertidos para inglês antes da exportação.

Definição de Pronto (DoD por Ativo)

Cada ativo entregue ao Unity deve satisfazer:

• Licença registrada (CC0 também deve ter fonte anotada), sem bloqueio para uso comercial
• Relatório de auditoria: contagem de polígonos dentro do orçamento, possui UVs, sem problemas de N-gon, transformações aplicadas
• Escala correta na cena (personagens ~1,7 m, proporção realista com objetos ao redor), orientação correta
• Materiais não rosas, texturas não perdidas (texturas incluídas no pacote/dentro do projeto), canais URP/HDRP corretos
• Colisor adequado; personagens/itens com animação possuem Avatar configurado e animação funcionando
• Prefab gerado, LOD configurado conforme requisito, console sem erros
• Imagem de qualidade em ângulo-chave gerada por blender_asset_qa_render.py e aprovada por inspeção visual (texturas/normais/metal roughness/forma); então entregue ao usuário para confirmação