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

Configure o Unity MCP na janela do AI Game Developer: modos Cloud e Custom, servidor local, porta, transporte, autorização, ferramentas e CI.

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

A maioria dos projetos não precisa de configuração: instale o plugin, faça login e clique em **Configure** para o seu agente. Esta página explica o que cada configuração da janela do AI Game Developer faz, onde as configurações são armazenadas, como substituí-las para automação e como o plugin se comporta em CI e em builds de player.

## A janela do AI Game Developer

Abra-a com **Window > AI Game Developer — MCP** (Ctrl+Alt+A, ou Cmd+Option+A no macOS) ou com o botão **AI** na barra de ferramentas da Scene View. De cima para baixo, ela contém:

- **Log Level**, **Timeout (ms)** e **Tool timeout (ms)**, além da **Version** do plugin.
- **Connection**: o seletor **Custom** / **Cloud** e as configurações do modo escolhido.
- Uma linha do tempo de conexão: **Unity** (com um botão **Connect** / **Disconnect**), **MCP server** e **AI agent**.
- O dropdown **AI agent** com o configurador de cada cliente: **Model Context Protocol (MCP)** com **Configure** / **Remove**, e **Skills** com **Auto-generate** e **Generate**.
- Contadores de **Tools**, **Prompts** e **Resources**, cada um com um botão **Open**.
- **Extensions**: instale pacotes de ferramentas opcionais (veja [Extensões](https://ai-game.dev/pt-br/docs/wiki/unity/extensions)).
- Links de ajuda: **Help / Talk** (Discord), **Bug Report** (issues do GitHub) e um botão **Check** para diagnósticos de serialização.

## Modos de conexão

### Cloud (padrão)

O plugin se conecta ao servidor hospedado em `https://ai-game.dev/mcp`. Nenhum servidor local é iniciado e a URL não é editável. O modo Cloud exige login: clique em **Authorize** ao lado de **Cloud Token** e aprove o código do dispositivo no navegador, ou faça login uma vez com `unity-mcp-cli login` ou com o app AI Game Dev. **Revoke** desconecta todas as ferramentas AI Game Dev da máquina.

### Custom (local ou seu próprio servidor)

O plugin se conecta à URL em **Server URL**. Por padrão, ela é um servidor local em `http://localhost:<port>`, e o plugin baixa, inicia e para o servidor (`gamedev-mcp-server`) para você. Você também pode informar a URL de um servidor MCP remoto que você hospeda. **Server URL** só é editável enquanto o Unity está desconectado do servidor.

O modo Custom adiciona estas configurações:

- **MCP server**: um botão **Start** / **Stop** e o status (Running, Starting, Stopping, Downloading ou External quando outro processo já atende a porta). **Download / Retry server** aparece se o download do binário falhar.
- **Transport**: `http` (recomendado) ou `stdio`. Com `http`, o agente se conecta ao servidor em execução, vários agentes podem compartilhá-lo e o servidor pode rodar em outra máquina. Com `stdio`, o agente inicia o servidor como seu próprio processo filho, apenas um agente pode se conectar e o botão Start / Stop fica desabilitado.
- **Authorization Token**: `none`, `oauth` ou `token`.
  - `none`: o servidor aceita qualquer conexão. Seguro apenas quando a porta não é acessível a partir de outras máquinas.
  - `oauth`: os agentes fazem login com a própria conta ai-game.dev; o servidor verifica os tokens online.
  - `token`: um segredo compartilhado, totalmente offline. Clique em **New** para gerar um token e depois em **Configure** (ou copie o token manualmente para a configuração do agente).

## A porta

A porta local não é um valor fixo como 8080. Ela é derivada da pasta do seu projeto: o hash SHA-256 do caminho normalizado do projeto, mapeado para o intervalo **20000 a 29999**. O mesmo projeto sempre usa a mesma porta, e projetos diferentes usam portas diferentes, então várias instâncias do Unity podem rodar lado a lado. A CLI usa a mesma fórmula, portanto seus comandos encontram o servidor certo sem flags.

Para usar outra porta, desconecte e depois digite-a em **Server URL** (por exemplo, `http://localhost:25000`). Os configuradores gravam a porta que você digitou nas configurações dos agentes.

## O arquivo de configuração

As configurações são armazenadas por usuário em `UserSettings/AI-Game-Developer-Config.json`, criado no primeiro lançamento. Chaves importantes:

| Chave | Significado | Padrão |
| --- | --- | --- |
| `connectionMode` | `Cloud` ou `Custom` | `Cloud` |
| `host` | URL do servidor no modo Custom | `http://localhost:<port>` |
| `token` | Token compartilhado para o modo de autorização `token` | gerado |
| `transportMethod` | `streamableHttp` ou `stdio` | `streamableHttp` |
| `authOption` | `none`, `oauth` ou `token` | `none` |
| `keepConnected` | Conectar ao servidor automaticamente | `true`, `false` em CI |
| `keepServerRunning` | Iniciar e manter o servidor local em execução | `true`, `false` em CI |
| `logLevel` | `Trace`, `Debug`, `Information`, `Warning`, `Error`, `Critical` | `Warning` |
| `timeoutMs` | Timeout do plugin para o servidor | `10000` |
| `toolTimeoutMs` | Quanto tempo uma chamada de ferramenta pode durar | `300000` |
| `tools`, `prompts`, `resources` | Visibilidade por item | padrões |

As credenciais do Cloud não são armazenadas aqui; elas ficam em `~/.ai-game-dev/credentials.json`. Para começar do zero, use **Tools > AI Game Developer > Reset Config**, que restaura os padrões e recarrega os scripts.

## Ferramentas, prompts e recursos

O contador **Tools** mostra quantas das ferramentas instaladas o agente vê, além de uma estimativa dos tokens que elas ocupam no contexto da IA. Clique em **Open** para mostrar ou ocultar ferramentas individuais; as janelas **MCP Prompts** e **MCP Resources** funcionam da mesma forma.

Uma ferramenta oculta não é excluída: ela desaparece da lista de ferramentas do agente, mas ainda é executada quando chamada pelo nome. Menos ferramentas visíveis deixam mais contexto para o raciocínio. Você também pode alterar a visibilidade com a ferramenta `tool-set-visibility` ou a partir de um terminal:

```bash
unity-mcp-cli configure ./MyUnityProject --enable-tools screenshot-scene-view,script-read
unity-mcp-cli configure ./MyUnityProject --list
```

## Substituições por ambiente e linha de comando

Para CI e inicializações por script, o plugin lê estas variáveis (ou os argumentos de linha de comando correspondentes do Unity) na inicialização. As substituições se aplicam apenas em memória e nunca são gravadas no arquivo de configuração.

| Variável | Argumento de linha de comando | Valores |
| --- | --- | --- |
| `UNITY_MCP_CLOUD_URL` | `-url` | URL do servidor (`UNITY_MCP_HOST` é um alias legado) |
| `UNITY_MCP_CONNECTION_MODE` | `-UNITY_MCP_CONNECTION_MODE` | `Cloud` ou `Custom`; uma URL de loopback implica `Custom` |
| `UNITY_MCP_KEEP_CONNECTED` | `-UNITY_MCP_KEEP_CONNECTED` | `true` ou `false` |
| `UNITY_MCP_AUTH_OPTION` | `-auth` | `none`, `oauth` ou `token` |
| `UNITY_MCP_TOKEN` | `-token` | Token do servidor local |
| `UNITY_MCP_TRANSPORT` | `-UNITY_MCP_TRANSPORT` | `stdio` ou `streamableHttp` |
| `UNITY_MCP_START_SERVER` | `-UNITY_MCP_START_SERVER` | `true` ou `false` |
| `UNITY_MCP_TOOLS` | `-UNITY_MCP_TOOLS` | Ids de ferramentas separados por vírgula a exibir; todas as outras ficam ocultas |

Os argumentos de linha de comando têm precedência sobre as variáveis de ambiente. Exemplo para um Editor em modo batch conectado a um servidor local:

```bash
Unity -batchmode -projectPath ./MyUnityProject \
  -UNITY_MCP_CLOUD_URL=http://localhost:8080 \
  -UNITY_MCP_KEEP_CONNECTED=true \
  -UNITY_MCP_AUTH_OPTION=token \
  -UNITY_MCP_TOKEN=my-secret-token
```

`unity-mcp-cli open` define essas variáveis para você; veja a [referência da CLI](https://ai-game.dev/pt-br/docs/wiki/unity/cli#open).

## Desabilitando o Unity MCP em CI

O plugin detecta ambientes de CI e então pula o download do servidor e a conexão automática. Para desativá-lo completamente em jobs comuns de teste em CI, use uma das duas opções:

- **`UNITY_MCP_DISABLE=1`** (ou `true`) no ambiente do processo que lança o Unity. O plugin pula a inicialização, o registro de ferramentas, o download do servidor, a resolução do NuGet e seus hooks do editor. Seu código ainda compila, então o projeto ainda precisa compilar.
- **`UNITY_MCP_EXCLUDE_FROM_COMPILATION`** como um Scripting Define Symbol em **Project Settings > Player > Other Settings**. Isso exclui todos os assemblies do plugin (e as extensões de primeira parte atualizadas) da compilação. Seu próprio código que referencia tipos do plugin precisa de `#if !UNITY_MCP_EXCLUDE_FROM_COMPILATION`.

Nenhuma das duas é habilitada automaticamente para `-batchmode` ou `-runTests`, porque sessões MCP headless precisam do plugin.

## Builds de player e runtime

O assembly de runtime do plugin compila para todas as plataformas, então ele faz parte dos seus builds de player a menos que você o exclua com o define acima. Um build nunca se conecta sozinho: em um jogo, você opta por isso no código com `UnityMcpPluginRuntime.Initialize(...)`, que é como você expõe ferramentas do jogo para uma IA (por exemplo, um oponente de xadrez com IA). Veja [Ferramentas personalizadas](https://ai-game.dev/pt-br/docs/wiki/unity/custom-tools#runtime).

## Auto-hospedando o servidor MCP

O servidor é o [GameDev-MCP-Server](https://github.com/IvanMurzak/GameDev-MCP-Server) compartilhado, também publicado como a imagem Docker `aigamedeveloper/mcp-server`:

```bash
docker run -p 8080:8080 aigamedeveloper/mcp-server
```

Em seguida, defina o plugin como **Custom** com **Server URL** `http://localhost:8080` (ou seu host) e aponte seu agente para o mesmo endereço. O servidor aceita configurações como `--port`, `--client-transport`, `--authorization` e `--idle-timeout-seconds`, ou as variáveis de ambiente `MCP_PLUGIN_*` correspondentes; a [documentação do servidor](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/mcp-server.md) lista todas elas.

## Páginas relacionadas

- [Conectando clientes de IA](https://ai-game.dev/pt-br/docs/wiki/unity/connecting-ai-clients) para configurações de agentes e login.
- [Solução de problemas](https://ai-game.dev/pt-br/docs/wiki/unity/troubleshooting) para problemas de conexão.

---

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

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