# Instalação — Unity · AI Game Developer Wiki

Instale o Unity MCP (AI Game Developer) em um projeto Unity com o app desktop, unity-mcp-cli, OpenUPM ou o instalador .unitypackage.

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

Esta página mostra todas as formas de adicionar o plugin Unity MCP a um projeto Unity, o que cada uma faz no seu projeto e como remover o plugin depois. Todos os caminhos instalam o mesmo pacote, `com.ivanmurzak.unity.mcp`, do registro OpenUPM, então você pode escolher o que melhor se adapta ao seu fluxo de trabalho.

## Requisitos

- **Unity 2022.3 ou mais recente.** O pacote declara `2022.3` como versão mínima; as versões Unity 6 são suportadas.
- **Um caminho de projeto sem espaços.** `C:/Projects/MyGame` funciona, `C:/My Projects/My Game` não. O plugin registra um erro na inicialização quando o caminho contém um espaço.
- **Um caminho de projeto curto no Windows.** O plugin copia suas DLLs do NuGet para `Assets/Plugins/NuGet`. Se o caminho resultante ultrapassar o limite de 260 caracteres do Windows, a instalação para e pede que você mova o projeto para uma pasta mais curta.
- **Acesso à internet na primeira abertura.** O plugin baixa suas dependências .NET do NuGet e, no modo Custom, o binário do servidor MCP do GitHub.
- Somente para `unity-mcp-cli`: **Node.js** `^20.19.0` ou `>=22.12.0`.

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

O [app AI Game Dev](https://ai-game.dev/docs/app) instala e conecta o plugin para você, sem terminal e sem Node.js na sua máquina.

1. [Baixe o app](https://ai-game.dev/pt-br/download) e entre com sua conta ai-game.dev.
2. Abra a pasta do seu projeto Unity no app. O app detecta que é um projeto Unity.
3. Clique em **Install Package**. O app adiciona o plugin ao `Packages/manifest.json` na versão mais recente lançada no OpenUPM e nunca faz downgrade de uma versão mais nova que você já tenha. Um projeto criado pelo app recebe o plugin automaticamente.
4. Abra o Editor pelo app. O app transmite sua sessão, então o plugin se conecta pelo ai-game.dev sem um login separado.

O app também instala extensões e executa o próprio agente de IA, então você não precisa de um cliente MCP separado. Os detalhes estão na wiki do app: [instalação](https://ai-game.dev/pt-br/docs/wiki/app/installation) e [projetos e engines](https://ai-game.dev/pt-br/docs/wiki/app/projects-and-engines).

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

O `unity-mcp-cli` edita o `Packages/manifest.json` diretamente, então o Unity não precisa estar aberto:

```bash
npm install -g unity-mcp-cli
unity-mcp-cli install-plugin ./MyUnityProject
```

Você também pode executá-lo sem uma instalação global:

```bash
npx unity-mcp-cli install-plugin ./MyUnityProject
```

O `install-plugin` adiciona o registro com escopo OpenUPM com os escopos `com.ivanmurzak` e `extensions.unity`, adiciona `com.ivanmurzak.unity.mcp` às `dependencies` na versão mais recente do OpenUPM e nunca faz downgrade de uma versão superior já instalada. Passe `--plugin-version <version>` para fixar uma versão. O caminho é opcional quando você executa o comando a partir da pasta do projeto.

A CLI também pode instalar o Unity e criar um projeto primeiro:

```bash
unity-mcp-cli install-unity
unity-mcp-cli create-project ./MyUnityProject
```

Se o Unity Hub não estiver presente, a CLI o instala. Depois, abra o projeto no Unity para que o Package Manager resolva o pacote. Todos os comandos estão na [referência da CLI](https://ai-game.dev/pt-br/docs/wiki/unity/cli).

## Opção 3: OpenUPM

Com a [CLI do OpenUPM](https://openupm.com/) instalada, execute isto na pasta do projeto:

```bash
openupm add com.ivanmurzak.unity.mcp
```

Sem a CLI do OpenUPM, adicione o registro e a dependência ao `Packages/manifest.json` você mesmo. Use a versão mostrada na [página do pacote no OpenUPM](https://openupm.com/packages/com.ivanmurzak.unity.mcp/):

```json
{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.ivanmurzak", "extensions.unity"]
    }
  ],
  "dependencies": {
    "com.ivanmurzak.unity.mcp": "1.6.2"
  }
}
```

Mescle estas entradas no seu arquivo existente; não substitua as outras dependências.

## Opção 4: o instalador .unitypackage

1. Baixe [AI-Game-Dev-Installer.unitypackage](https://github.com/IvanMurzak/Unity-MCP/releases/latest/download/AI-Game-Dev-Installer.unitypackage).
2. Abra seu projeto no Unity.
3. Dê um duplo clique no arquivo, ou use **Assets > Import Package > Custom Package** e selecione-o.
4. Clique em **Import**.

O instalador é um pequeno script de editor. Ele adiciona o registro com escopo OpenUPM e a dependência do plugin ao `Packages/manifest.json` e depois se exclui de `Assets`. Em seguida, o Package Manager baixa o pacote real.

## O que acontece na primeira abertura

Depois que o pacote chega, o plugin se prepara:

- Ele baixa as bibliotecas .NET necessárias (a biblioteca de plugin MCP, ReflectorNet, RQL, SignalR, System.Text.Json e outras) do NuGet para `Assets/Plugins/NuGet`, com um cache em `Library/NuGetCache`, e o Unity recompila uma vez. Se essas DLLs ficarem dessincronizadas, use **Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs**.
- Ele baixa o binário `gamedev-mcp-server` para a sua plataforma do GitHub para `Library/mcp-server/<platform>/` (por exemplo `win-x64`, `osx-arm64` ou `linux-x64`). O servidor só é iniciado no modo Custom com o transporte HTTP; o modo Cloud, o padrão, não inicia nenhum servidor local.
- A janela **AI Game Developer** fica disponível em **Window > AI Game Developer — MCP** (atalho Ctrl+Alt+A, ou Cmd+Option+A no macOS). A barra de ferramentas da Scene View também ganha um botão de sobreposição **AI** que a abre.

`Library/` é excluída do controle de versão por padrão, então o binário do servidor nunca é enviado ao repositório. Em ambientes de CI, o plugin ignora o download e a inicialização do servidor.

## Atualizando o plugin

Quando há uma versão mais recente no OpenUPM, o plugin mostra um popup de atualização na inicialização do Editor. Você pode verificar manualmente com **Tools > AI Game Developer > Updates > Check for Updates**. Para atualizar, altere a versão no Package Manager, execute novamente `unity-mcp-cli install-plugin` (ele instala a mais recente) ou deixe o app desktop atualizá-lo.

Para equipes em que uma pessoa é responsável pela versão do plugin, abra **Edit > Project Settings > AI Game Developer** e ative **Disable update notifications for the entire team**. A configuração é salva em `ProjectSettings/AI-Game-Developer-UpdateSettings.asset`; faça commit desse arquivo. A mesma opção está em **Tools > AI Game Developer > Updates > Disable Update Notifications (Team)**.

## Desinstalação

1. Abra **Window > Package Manager**, selecione **AI Game Developer — MCP** e clique em **Remove**, ou execute `unity-mcp-cli remove-plugin ./MyUnityProject`. A CLI mantém o registro com escopo, porque outros pacotes podem usá-lo.
2. Feche o Unity e exclua a pasta `Assets/Plugins/NuGet` e seu arquivo `Assets/Plugins/NuGet.meta`.

## Próximos passos

- [Primeiros passos](https://ai-game.dev/pt-br/docs/wiki/unity/getting-started): conecte um cliente de IA e execute seu primeiro prompt.
- [Extensões](https://ai-game.dev/pt-br/docs/wiki/unity/extensions): adicione pacotes de ferramentas para Cinemachine, ProBuilder, Tilemap e muito mais.
- Se algo falhar durante a instalação, consulte [Solução de problemas](https://ai-game.dev/pt-br/docs/wiki/unity/troubleshooting).

---

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

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