# Configuração do plugin do Unity — AI Game Developer

Configure o plugin AI Game Developer para Unity passo a passo: instale, faça login, conecte seu cliente de IA e adicione extensões — com soluções para os problemas mais comuns.

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

Unity · configuração manual

Tudo para sair de um projeto Unity vazio e chegar a um agente de IA trabalhando no Editor: instale o plugin, faça login, conecte seu cliente de IA e adicione as extensões de que precisa. A [página de instalação do Unity](https://ai-game.dev/pt-br/engines/unity) tem a versão resumida.

01

## Antes de começar

Unity 2022.3 ou mais recente, uma conta ai-game.dev e um cliente de IA.

- **Unity 2022.3 ou mais recente** — o Unity 6 é compatível.
- **Uma conta ai-game.dev** para a conexão Cloud padrão — [crie uma](https://ai-game.dev/create-account) se ainda não tiver.
- **Um cliente de IA** — o app AI Game Dev, Claude Code, Cursor, Copilot, Gemini, Codex ou qualquer um dos [14 clientes MCP compatíveis](https://ai-game.dev/pt-br/mcp-endpoint-info).
- **Acesso à internet na primeira abertura** — o plugin baixa seus pacotes .NET do NuGet.

02

## Instale o plugin

Com o app, a CLI, o OpenUPM ou o pacote instalador — escolha um.

Quatro formas de adicionar o plugin, da mais fácil:

**App desktop**

Abra seu projeto Unity no [app AI Game Dev](https://ai-game.dev/pt-br/download) e clique em **Install Package**. O app instala o plugin mais recente do OpenUPM, faz o login dele e configura seu agente.

**unity-mcp-cli**

Instale a CLI pelo npm e adicione o plugin ao seu projeto (ele edita o `Packages/manifest.json` para você):

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

**OpenUPM**

Com a CLI do OpenUPM, execute isto na pasta do projeto:

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

Sem a CLI do OpenUPM? Adicione o registro com escopo ao `Packages/manifest.json` e depois adicione o pacote em **Window → Package Manager**:

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

**.unitypackage**

Baixe o instalador e importe-o com **Assets → Import Package → Custom Package…**. Ele adiciona o registro OpenUPM e o pacote ao seu projeto, então as atualizações seguintes vêm pelo Package Manager.

[⬇ Baixar AI-Game-Dev-Installer.unitypackage](https://github.com/IvanMurzak/Unity-MCP/releases/latest/download/AI-Game-Dev-Installer.unitypackage)

03

## Abra a janela e faça login

Abra a janela do AI Game Developer e faça login uma vez com sua conta.

1. No Unity, escolha **Window → AI Game Developer — MCP** (`Ctrl+Alt+A`, ou `Cmd+Option+A` no macOS).
2. Mantenha a opção **Connection** em **Cloud** e clique em **Authorize**.
3. Seu navegador abre a página de login do ai-game.dev com um código curto. Confira se o código confere e aprove.
4. O status do Unity muda para **Connected**.

O login fica armazenado para o computador inteiro: se você já entrou com o app ou com `unity-mcp-cli login`, o Editor usa essa sessão e você pode pular esta etapa.

04

## Conecte seu cliente de IA

Um comando, ou um clique na janela, grava a configuração do seu cliente.

Na janela, clique em **Configure** ao lado do seu agente de IA — ou execute `setup-mcp` no terminal. Os dois gravam a URL fixada do projeto e uma chave do projeto na configuração do cliente, então ele se conecta na hora:

```bash
# Claude Code — use your agent's id (cursor, codex, gemini, vscode-copilot, …)
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
```

Reinicie o cliente de IA depois de alterar a configuração. Para outros clientes e configuração manual, veja [Como conectar clientes de IA](https://ai-game.dev/pt-br/docs/wiki/unity/connecting-ai-clients) e a [página do endpoint MCP](https://ai-game.dev/pt-br/mcp-endpoint-info).

05

## Adicione extensões (opcional)

Animação, Cinemachine, Terreno, Timeline e mais — instale só o que precisar.

Cada extensão é um pacote Unity próprio. Assim que é instalada, ela ensina ao agente uma área do Unity por meio do RQL. Algumas populares:

- [AI Animation](https://ai-game.dev/docs/extensions/unity/animation) 3 recursos
  ```bash
  openupm add com.ivanmurzak.unity.mcp.animation
  ```
- [AI Cinemachine](https://ai-game.dev/docs/extensions/unity/cinemachine) 4 recursos
  ```bash
  openupm add com.ivanmurzak.unity.mcp.cinemachine
  ```
- [AI Terrain](https://ai-game.dev/docs/extensions/unity/terrain) 4 recursos
  ```bash
  openupm add com.ivanmurzak.unity.mcp.terrain
  ```
- [AI Timeline](https://ai-game.dev/docs/extensions/unity/timeline) 5 recursos
  ```bash
  openupm add com.ivanmurzak.unity.mcp.timeline
  ```

[Todas as 10 extensões do Unity →](https://ai-game.dev/docs/extensions/unity)

?

## Solução de problemas

Soluções para os problemas mais comuns. Saiba mais no [guia de solução de problemas do Unity](https://ai-game.dev/pt-br/docs/wiki/unity/troubleshooting).

**Meu cliente de IA conecta, mas não mostra nenhuma ferramenta**

Verifique se o status do Unity mostra **Connected** e reconecte o cliente (no Claude Code, `/mcp`) ou reinicie-o. Se ainda não aparecer nada, clique em **Configure** para o seu agente novamente e reinicie o cliente.

**A janela do AI Game Developer não aparece**

O plugin só carrega depois que o projeto compila. Verifique no Console se há erros de compilação em qualquer parte do projeto e reabra o Editor. Tipos ausentes de McpPlugin ou ReflectorNet geralmente indicam que a primeira importação ainda não terminou: aguarde ou use **Tools → AI Game Developer → Dependencies → Force Resolve NuGet DLLs**.

**Modo Custom: o servidor MCP local não inicia**

No modo Custom, o plugin baixa o `gamedev-mcp-server` para `Library/mcp-server/<platform>/`. Se um firewall ou proxy bloqueou o download, a janela mostra um erro de servidor com um botão **Download / Retry**. No modo Cloud, nenhum servidor local é necessário.

**Conflito de porta no modo Custom**

Cada projeto recebe uma porta local fixa entre 20000 e 29999, derivada do seu caminho. Se outro processo já estiver usando essa porta, o servidor aparece como **External**: encerre esse processo ou digite outra porta em **Server URL** e clique em **Configure** novamente.

**O Package Manager informa que o pacote precisa de uma versão mais nova do Unity**

O plugin requer Unity 2022.3 ou mais recente. Atualize o projeto ou instale um Editor mais novo com `unity-mcp-cli install-unity`.

### Próximos passos

[**Wiki do Unity →** Configuração, ferramentas e RQL, ferramentas personalizadas, referência da CLI e mais.](https://ai-game.dev/pt-br/docs/wiki/unity) [**Ferramentas do Unity →** Tudo o que o agente pode fazer no Unity, com exemplos.](https://ai-game.dev/docs/tools/unity) [**Boas práticas →** Como pedir ao agente aquilo que ele faz bem.](https://ai-game.dev/docs/best-practices/unity)

---

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

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