Instalação

Esta página mostra como instalar o Unreal MCP, o plugin do AI Game Developer para o Unreal Engine, em um projeto. Escolha um caminho de instalação, siga os seus passos e depois continue com Primeiros passos.

Requisitos#

O plugin não fixa uma versão exata da engine no seu descritor, então o mesmo plugin carrega em versões mais recentes da engine.

Observação: Um projeto só com Blueprints precisa de um módulo C++ antes de conseguir compilar plugins. No Unreal Editor, adicione qualquer classe C++ (Tools, New C++ Class) para transformá-lo em um projeto C++, ou crie um projeto C++ novo com unreal-mcp-cli create-project.

Opção 1: o app desktop AI Game Dev#

O app desktop é o caminho mais simples. Ele já traz a lógica de instalação, então você não precisa de Node.js, npm nem de um terminal.

1. Instale o AI Game Dev pela página de download. O guia de instalação do app explica o processo.
2. Entre com a sua conta ai-game.dev.
3. Escolha Open folder… e selecione a pasta do seu projeto Unreal (a pasta que contém o arquivo .uproject). O app a detecta como um projeto Unreal. Ou use Create new project para criar um novo; o plugin é então instalado automaticamente.
4. Clique em Install Package na barra lateral. O app instala a versão mais recente lançada do Unreal MCP e verifica o download antes. Se o plugin instalado já for mais novo, o app o mantém.
5. Clique em Open Editor para abrir o Unreal Editor com a sua sessão autenticada, para que o plugin se conecte pelo ai-game.dev sem precisar de um token manual.

Na CLI do app, as mesmas ações são os comandos /install-plugin e /open. O app também pode instalar as extensões opcionais. Os detalhes estão em Projetos e engines.

Opção 2: unreal-mcp-cli#

O unreal-mcp-cli é publicado no npm e funciona no Windows, macOS e Linux. Ele não exige clonar o repositório nem uma etapa de build própria.

Instale a CLI globalmente:

npm install -g unreal-mcp-cli

Ou execute qualquer comando uma vez sem instalá-la:

npx unreal-mcp-cli@latest status

Depois, instale o plugin, faça login e abra o editor:

# 1. Install the UnrealMCP plugin into <project>/Plugins/UnrealMCP
unreal-mcp-cli install-plugin ./YourProject

# 2. Sign in to ai-game.dev once per machine (device-code flow in your browser)
unreal-mcp-cli login

# 3. Open the Unreal Editor for the project
unreal-mcp-cli open ./YourProject

O que esses comandos fazem:

• install-plugin baixa o código-fonte do plugin que corresponde à versão da CLI (unreal-mcp-plugin-source-<version>.zip do release no GitHub) e verifica a assinatura antes de extraí-lo. Um download adulterado ou sem assinatura é recusado. A bridge para a sua plataforma vem dentro desse pacote.
• login armazena a sua credencial no armazenamento da máquina inteira (~/.ai-game-dev/credentials.json), compartilhado com o app e com as CLIs das outras engines.
• open encontra a engine correta a partir do EngineAssociation do projeto, compila os módulos nativos do editor primeiro quando eles precisam ser compilados, e dispensa os avisos de inicialização conhecidos do Unreal (como "Missing Modules") caso ainda apareçam.

Dica: Feche o Unreal Editor antes de instalar ou atualizar o plugin. O Unreal não consegue substituir um plugin que um editor em execução carregou.

Opção 3: instalação manual a partir do código-fonte#

A instalação manual é destinada a contribuidores e ao desenvolvimento do plugin.

1. Copie a pasta UnrealMCP/ do repositório Unreal-MCP para <YourProject>/Plugins/UnrealMCP/.
2. Um checkout do código-fonte não tem bridge incluída. Compile uma com unreal-mcp-cli bootstrap-local ./YourProject (requer o .NET 9 SDK), ou aponte UNREAL_MCP_BRIDGE_PATH para uma bridge que você compilou.
3. Abra o projeto. O Unreal compila os módulos do plugin na primeira inicialização.

Para desenvolvimento ao vivo, unreal-mcp-cli install-plugin --junction vincula a pasta do plugin em vez de copiá-la (Windows).

Fab / Epic Marketplace#

Uma listagem no Fab está planejada, mas ainda não está no ar. Até ela ser publicada, não há nada para instalar pelo Fab; use o app ou a CLI.

Verificar a instalação#

Quando o editor inicia, o Output Log exibe:

[Unreal-MCP] plugin loaded

Você também pode executar unreal-mcp-cli status --path ./YourProject para ver o estado do pacote, do projeto, do plugin e da conexão.

O plugin então aparece no menu Tools do editor como AI Game Developer. Continue com Primeiros passos.

Atualizar o plugin#

• App: a barra lateral mostra Update Package quando existe uma versão mais recente do plugin.
• CLI: execute unreal-mcp-cli update ./YourProject. Em uma mudança de versão, ele exclui a pasta Intermediate/ do plugin instalado e os Binaries/ de C++ compilados para que o Unreal faça uma recompilação limpa, e mantém a bridge incluída. Adicione --force para reinstalar a mesma versão, ou --no-clean para manter o cache de build.
• Cópia manual: feche o editor, exclua Plugins/UnrealMCP/Intermediate/ e os Binaries/ de C++ (mantenha Binaries/ThirdParty/) e depois reabra o projeto.

Um cache de build obsoleto é o motivo mais comum de uma atualização parecer não ter efeito. Consulte Solução de problemas.

Remover o plugin#

unreal-mcp-cli remove-plugin ./YourProject

Ou exclua <YourProject>/Plugins/UnrealMCP/ com o editor fechado.

Manter o plugin fora de jogos empacotados#

Se você usa o Unreal MCP apenas para ajuda de IA no editor, exclua-o das builds empacotadas na entrada de plugin do .uproject do seu projeto:

{
  "Name": "UnrealMCP",
  "Enabled": true,
  "TargetDenyList": ["Game", "Client", "Server"]
}

O plugin então permanece ativo no editor, mas nada dele, incluindo a bridge, é compilado ou incluído (staged) em um jogo empacotado. Não adicione nenhum módulo UnrealMcp* às dependências do Build.cs do módulo do seu jogo: uma dependência direta sobrepõe a lista de bloqueio. Para usar ferramentas de IA dentro de um jogo em execução, consulte ferramentas no jogo.