# Instalação — Unreal Engine · AI Game Developer Wiki

Instale o plugin Unreal MCP para Unreal Engine 5.5+ com o app AI Game Dev ou o unreal-mcp-cli. Requisitos, atualizações, remoção e status no Fab.

Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/unreal/installation).

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](https://ai-game.dev/pt-br/docs/wiki/unreal/getting-started).

## Requisitos

| Requisito | Detalhes |
| --- | --- |
| Unreal Engine | 5.5 ou mais recente. As builds de release são validadas com as versões 5.5, 5.6, 5.7 e 5.8. |
| Tipo de projeto | Um **projeto Unreal em C++**. O plugin contém módulos de editor que são compilados para o seu projeto, então o projeto precisa conseguir compilar C++. |
| Toolchain C++ | A toolchain de compilador que a sua versão do Unreal Engine exige na sua plataforma (por exemplo, Visual Studio no Windows, Xcode no macOS). |
| Sistema operacional | Windows (x64), macOS (Apple silicon e Intel) e Linux (x64). O release inclui uma build da bridge para cada um deles. |
| Node.js | Apenas para o `unreal-mcp-cli`: `^20.19.0` ou `>=22.12.0`. O app desktop não precisa dele. |
| .NET 9 SDK | Apenas se você compilar a bridge a partir do código-fonte. As instalações empacotadas já a incluem. |

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](https://ai-game.dev/pt-br/download). O [guia de instalação do app](https://ai-game.dev/pt-br/docs/wiki/app/installation) 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](https://ai-game.dev/pt-br/docs/wiki/unreal/extensions) opcionais. Os detalhes estão em [Projetos e engines](https://ai-game.dev/pt-br/docs/wiki/app/projects-and-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:

```bash
npm install -g unreal-mcp-cli
```

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

```bash
npx unreal-mcp-cli@latest status
```

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

```bash
# 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](https://github.com/IvanMurzak/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:

```text
[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](https://ai-game.dev/pt-br/docs/wiki/unreal/getting-started).

## 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](https://ai-game.dev/pt-br/docs/wiki/unreal/troubleshooting#stale-build).

## Remover o plugin

```bash
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**:

```json
{
  "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](https://ai-game.dev/pt-br/docs/wiki/unreal/custom-tools#runtime).

---

Source (HTML): https://ai-game.dev/pt-br/docs/wiki/unreal/installation

Machine-translated (pt-BR) from the English page: https://ai-game.dev/docs/wiki/unreal/installation