Configuração

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).
• 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:

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:

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.

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:

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.

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.

Auto-hospedando o servidor MCP#

O servidor é o GameDev-MCP-Server compartilhado, também publicado como a imagem Docker aigamedeveloper/mcp-server:

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 lista todas elas.

Páginas relacionadas#

• Conectando clientes de IA para configurações de agentes e login.
• Solução de problemas para problemas de conexão.