VibeUE

Unreal Engine MCP

GitHub
713
Experimente este MCPPatrocinado

Documentação

VibeUE — Desenvolvimento de Unreal Engine com IA

🧩 Expansão MCP + Conjunto de Ferramentas de IA para Unreal Engine 5.8+

https://www.vibeue.com/

Unreal Engine MCP License: MIT Discord Donate

VibeUE é a Expansão MCP + Conjunto de Ferramentas de IA para Unreal Engine 5.8+. O Unreal 5.8 adicionou um servidor MCP integrado e conjuntos de ferramentas de IA; o VibeUE é uma Expansão MCP que se conecta diretamente a eles e adiciona um Conjunto de Ferramentas de IA profundo — uma biblioteca de capacidades do editor — Blueprints, materiais, paisagem, folhagem, animação, Niagara, UMG, áudio, StateTree, Behavior Trees e Blackboards, tags de gameplay, entrada, UVs, desempenho/perfilamento, e mais — registradas no próprio servidor ToolsetRegistry e ModelContextProtocol do motor, além de habilidades de domínio ricas servidas através do sistema nativo AgentSkill do Unreal. Qualquer agente compatível com MCP (Claude Code, Cursor, Copilot, …) controla seu editor através do endpoint MCP padrão do Unreal.

⚠️ O VibeUE requer que o MCP nativo do Unreal seja configurado primeiro — habilite o plugin Unreal MCP (que ativa automaticamente o Toolset Registry) e o plugin Editor Tools, depois inicie o servidor MCP. Siga o guia da Epic: Unreal MCP no Unreal Editor. O VibeUE então expande esse endpoint — sem servidor separado e sem chat no editor. Uma chave de API gratuita (definida em Editor Preferences → Plugins → VibeUE) desbloqueia as ferramentas de terreno do mundo real; todo o resto funciona sem ela.

✨ O que o VibeUE adiciona

O Unreal 5.8 inclui seus próprios conjuntos de ferramentas de IA (Blueprints, materiais, atores, assets, malhas, tabelas de dados, …). O VibeUE os complementa — ele foca nos domínios e na profundidade que o motor não cobre:

  • Terreno e mundo — Escultura de Landscape/heightmaps/splines, auto-materiais de Landscape + RVT, Folhagem, Map Blockout procedural para FPS, e terreno do mundo real (heightmaps + água via GPS).
  • Áudio — Criação de gráficos MetaSound e SoundCue.
  • Assets de animação — Edição de keyframes de AnimSequence, criação de AnimMontage, máquinas de estado de AnimBP, edição de ossos/sockets/retarget/perfis de blend do Skeleton.
  • Profundidade de FX — Criação de cores/curvas de emissores Niagara e módulos Custom-HLSL scratch-pad.
  • UI — Widgets UMG com bindings MVVM, criação de animações e validação de preview/PIE.
  • Criação de Blueprints de ordem superior — timelines, event dispatchers, delegates, pinos de custom events, caixas de comentários e um construtor em lote build_graph.
  • Criação de comportamento de IA — Edição de nós/decorators/services de Behavior Tree por caminho estrutural com vinculação de chaves de blackboard, round-trips de árvores JSON e validação/reparo; CRUD completo de assets de Blackboard + chaves. As gravações passam pelo EdGraph do editor com guardas de recusa cientes de PIE e editores abertos.
  • Segurança do editor — TransactionService envolve o buffer de transações do editor (desfazer / refazer / checkpoints) para que um agente possa agrupar e reverter suas próprias edições — os conjuntos de ferramentas do motor não expõem nada disso.
  • Fluxos de trabalho verificados — WorkflowService adiciona um manifesto autoritativo de motor/build, diários de tarefas duráveis com proveniência de assets afetados, cenários PIE assíncronos (compilar → entrada → asserção → captura → teardown garantido) e manutenção em massa retomável com dry-run primeiro.
  • ⚡ Desempenho e perfilamento — o destaque do VibeUE: veja a seção dedicada abaixo.
  • Acesso Python-first — execute qualquer Python unreal.* no editor e inspecione toda a API.
  • Pesquisa na web — busca / fetch / geocodificação para pesquisa em contexto e fluxos de trabalho de terreno.

Ele deliberadamente não duplica as ferramentas gerais do motor (CRUD básico de assets/atores/blueprints/materiais, capturas de tela, logs, PIE) — os agentes usam os conjuntos de ferramentas nativos do Unreal para isso.

⚡ Desempenho e Perfilamento (destaque)

Os conjuntos de ferramentas de IA nativos do Unreal têm zero ferramentas de desempenho — eles podem iniciar PIE/Simulate, mas não podem medir nada. O PerformanceService do VibeUE preenche essa lacuna para que um agente possa realmente diagnosticar e corrigir a taxa de quadros:

  • frame_timing() — Divisão de threads Game/Render/GPU/RHI + um veredito de gargalo CPU-vs-GPU e uma dica concreta de próximo passo. Execute isso primeiro — otimizar a GPU não faz nada em um quadro limitado pela CPU.
  • Captura Unreal Insights — start_trace / stop_trace / get_trace_status, com marcadores bookmark e region_start / region_end.
  • analyse() — lê o trace e o log de volta e retorna um resumo de desempenho (estatísticas de quadros, piores quadros, hitches, linhas de log notáveis).
  • start_standalone anexado ao trace — perfile um build standalone representativo, não apenas o viewport do editor.
import unreal
print(unreal.PerformanceService.frame_timing())   # CPU vs GPU bound — diagnose FIRST
unreal.PerformanceService.start_trace("cap", "")   # Insights trace
# … reproduce the workload (ideally under PIE / standalone) …
unreal.PerformanceService.stop_trace()
print(unreal.PerformanceService.analyse("both", ""))

Combine com as habilidades profiling e frame-rate para o drill-down completo de CPU/GPU.

🏗️ Arquitetura

O VibeUE se conecta a três sistemas nativos do UE 5.8+:

  1. Toolsets (ToolsetRegistry) — Os serviços do VibeUE se registram como UToolsetDefinitions, então seus métodos se tornam ferramentas AICallable no endpoint MCP. Eles também são BlueprintCallable, então os mesmos métodos são chamáveis a partir do Python como unreal.<Name>Service.<method>().
  2. Servidor MCP (ModelContextProtocol) — um pequeno conjunto de ferramentas utilitárias do VibeUE é registrado diretamente no endpoint: execute_python_code, discover_python_module/_class/_function, list_python_subsystems, deep_research, terrain_data.
  3. Habilidades (AgentSkillToolset) — ~36 pacotes de habilidades em markdown se registram como UAgentSkills nativos, descobríveis via ListSkills e carregados lentamente via GetSkills, junto com as habilidades do próprio motor.

Uso eficiente (para agentes): execute_python_code é o cavalo de batalha — ele agrupa uma tarefa inteira de várias etapas em uma única round-trip e alcança todos os serviços do VibeUE além da API completa unreal.*. Use call_tool apenas para habilidades e os poucos toolsets do motor sem caminho Python (capturas de tela, etc.). Veja Content/samples/AGENTS.md.sample para o guia completo do agente.

🚀 Instalação e configuração

Requisitos: Unreal Engine 5.8+ · Git

Passo 1 — Configure o MCP nativo do Unreal (faça isso PRIMEIRO)

O VibeUE é uma expansão do suporte MCP integrado do Unreal, então habilite isso primeiro. Detalhes completos no guia da Epic: Unreal MCP no Unreal Editor.

  1. Edit → Plugins → habilite Unreal MCP (isso ativa automaticamente o Toolset Registry) e Editor Tools (os conjuntos de ferramentas de IA do próprio motor, para que os agentes tenham ambos). Eles são Experimentais. Reinicie quando solicitado.
  2. Edit → Editor Preferences → General → Model Context Protocol → habilite Auto Start Server (ou execute o comando de console ModelContextProtocol.StartServer). Endpoint padrão http://127.0.0.1:8000/mcp (porta/caminho configuráveis). Habilitar Tool Search mantém o contexto de um agente pequeno — ele vê list_toolsets / describe_toolset / call_tool e carrega ferramentas sob demanda.

Passo 2 — Instale o VibeUE

cd /path/to/YourProject/Plugins
git clone https://github.com/kevinpbuckley/VibeUE.git

Compile com o script do projeto:

Plugins/VibeUE/BuildAndLaunchGame.ps1                  # builds + launches the editor
Plugins/VibeUE/BuildAndLaunchGame.ps1 -StrictRebuild   # full recompile (warnings-as-errors)
Plugins/VibeUE/BuildAndLaunchGame.ps1 -Map /Game/Maps/MyMap   # open a specific map (issue #554)

No Linux ou macOS, use o script de shell com detecção de plataforma:

Plugins/VibeUE/BuildAndLaunchGame.sh --engine /path/to/UE5
Plugins/VibeUE/BuildAndLaunchGame.sh --engine /path/to/UE5 --strict-rebuild
Plugins/VibeUE/BuildAndLaunchGame.sh --engine /path/to/UE5 --map /Game/Maps/MyMap

Depois Edit → Plugins → habilite VibeUE e reinicie. Seus serviços, ferramentas e habilidades agora se registram no mesmo endpoint, junto com os do motor.

Passo 3 — Conecte seu agente

Dois comandos de console do editor (abra o console com `):

1. Escreva a configuração do servidor MCP (.mcp.json na raiz do projeto):

ModelContextProtocol.GenerateClientConfig ClaudeCode

(suporta ClaudeCode, Cursor, VSCode, Gemini, Codex ou All.)

2. Escreva o guia do agente do VibeUE para que o assistente use os padrões eficientes:

VibeUE.GenerateAgentConfig ClaudeCode

Isso escreve o guia no arquivo correto para seu agente — CLAUDE.md (Claude Code), GEMINI.md (Gemini), AGENTS.md (Codex / Hermes / Cursor) ou .github/copilot-instructions.md (Copilot) — ou passe All para escrever CLAUDE.md + GEMINI.md + AGENTS.md de uma vez. Ele resolve a localização do plugin automaticamente, então funciona se o VibeUE foi instalado via FAB ou Git. O guia vai em um bloco gerenciado, então execute novamente a qualquer momento para atualizar sem perturbar suas próprias anotações. Passe import para vincular o guia com um @import de uma linha em vez de copiá-lo (apenas Claude Code / Gemini — outros agentes não resolvem imports, então eles sempre recebem uma cópia).

O servidor MCP é somente loopback, sem autenticação — uso apenas na mesma máquina (conforme a documentação da Epic).

O guia ensina: descubra antes de chamar (discover_python_class), agrupe com execute_python_code, carregue habilidades via ListSkills/GetSkills e quando usar deep_research / terrain_data.

🎯 Habilidades

Habilidades são conhecimento de domínio carregado lentamente (fluxos de trabalho, pegadinhas, formatos de propriedades) servido pelo AgentSkillToolset nativo do Unreal:

# discover (summaries only — cheap)
call_tool(tool_name="ListSkills", toolset_name="ToolsetRegistry.AgentSkillToolset")

# load the packs you need (full markdown, lazy)
call_tool(tool_name="GetSkills", toolset_name="ToolsetRegistry.AgentSkillToolset",
          arguments={"skillPaths": ["/VibeUE/Python/init_unreal_PY.VibeUE_blueprints"]})

ListSkills é a fonte de verdade ao vivo para o que está disponível (ele lê o SKILL.md de cada pacote). As habilidades dizem o que fazer e por quê; use discover_python_class('unreal.<Name>Service', method_filter='…') para assinaturas exatas antes de escrever código.

🔧 Dependências do plugin

Pré-requisitos nativos do motor (habilite no Passo 1 — a pilha MCP da Epic):

PluginPropósito
Unreal MCP (ModelContextProtocol)O endpoint do servidor MCP nativo
Toolset Registry (ToolsetRegistry)Registro nativo de toolset de IA + AgentSkill (auto-habilitado pelo Unreal MCP)
Editor Tools (EditorToolset)Os conjuntos de ferramentas de IA do próprio motor — o VibeUE complementa estes

Habilitados automaticamente pelo VibeUE: PythonScriptPlugin (a API unreal.*), EditorScriptingUtilities e os plugins de domínio que seus serviços precisam — Niagara, MetaSound, EnhancedInput, ModelViewViewModel, StateTree, MeshModelingToolset, GameplayTagsEditor. (O VibeUE também depende de ToolsetRegistry + ModelContextProtocol, então habilitar o VibeUE os puxa — mas você ainda habilita Editor Tools e inicia o servidor conforme o Passo 1.)

🛠️ Script de build e inicialização

BuildAndLaunchGame.ps1 (raiz do projeto ou Plugins/VibeUE/) para o editor em execução, compila e reinicia:

  • -StrictRebuild — recompilação completa do plugin com warnings-as-errors
  • -Clean — limpa intermediate/binaries primeiro
  • -SkipBuild — apenas reinicia

📚 A API ao vivo

O VibeUE intencionalmente mantém nenhum catálogo estático de métodos neste README — a superfície evolui com o motor. As referências autoritativas e sempre atuais são:

  • ListSkills → quais domínios existem e quando usá-los.
  • discover_python_class('unreal.<Name>Service') → assinaturas exatas de métodos.
  • describe_toolset('VibeUE.<Name>Service') → as ferramentas do toolset + schemas JSON (pesado em tokens; prefira habilidades + descoberta).

Licença

MIT — veja LICENSE. Página inicial do projeto: https://www.vibeue.com/