FAQ

Respostas curtas para as perguntas mais frequentes sobre o Unity MCP, o plugin AI Game Developer para Unity. Cada resposta tem um link para a página com os detalhes.

Geral#

O que é o Unity MCP?#

Um plugin do Unity Editor que permite que agentes de IA trabalhem no seu projeto por meio do Model Context Protocol. O agente pode ler e alterar cenas, GameObjects, componentes, prefabs e assets, escrever e executar C#, rodar testes e tirar screenshots. Veja a visão geral.

O plugin é gratuito e de código aberto?#

O plugin é de código aberto sob a licença Apache-2.0, no repositório Unity-MCP. O modo Custom executa um servidor local e não precisa de conta. O modo Cloud usa sua conta ai-game.dev; os planos estão na página de preços.

Quais versões do Unity são compatíveis?#

Unity 2022.3 e superior, incluindo Unity 6.

Quais clientes de IA funcionam com ele?#

A janela do AI Game Developer tem configuradores para Claude Code, Claude Desktop, Cursor, Visual Studio Code (Copilot), Visual Studio (Copilot), Rider (Junie), GitHub Copilot CLI, Gemini, Antigravity, Cline, Open Code, Codex, Kilo Code, Zoo Code e Unity AI, além de uma entrada personalizada para qualquer outro cliente MCP. Veja Conectar clientes de IA.

Preciso ter meu próprio cliente de IA?#

Não. O aplicativo desktop AI Game Dev inclui o agente, instala o plugin e o conecta. Use seu próprio cliente se você já usa Claude Code, Cursor ou outro cliente MCP.

Configuração#

Qual é a forma mais fácil de instalá-lo?#

O aplicativo desktop. Sem ele, execute unity-mcp-cli install-plugin, ou use o OpenUPM ou o instalador .unitypackage. Veja Instalação.

Onde fica a janela do plugin?#

Window > AI Game Developer — MCP, atalho Ctrl+Alt+A (Cmd+Option+A no macOS), ou o botão AI na barra de ferramentas da Scene View.

Qual é a diferença entre o modo Cloud e o modo Custom?#

No modo Cloud, o padrão, o Editor e seu cliente de IA se conectam a https://ai-game.dev/mcp e você faz login uma única vez. No modo Custom, o plugin executa um servidor MCP local em uma porta derivada do caminho do seu projeto, e tudo fica na sua máquina. Veja Configuração.

Preciso escolher uma porta?#

Não. A porta é derivada do caminho do projeto (faixa de 20000 a 29999), então é estável por projeto e diferente entre projetos. Você pode substituí-la em Server URL.

Onde as configurações são armazenadas?#

Em UserSettings/AI-Game-Developer-Config.json dentro do projeto. O login do ai-game.dev é armazenado uma vez por máquina em ~/.ai-game-dev/credentials.json.

Posso usar vários projetos Unity ao mesmo tempo?#

Sim. Cada projeto tem sua própria porta, e as URLs fixadas (https://ai-game.dev/mcp/p/<pin>) direcionam cada agente para o Editor correto.

Uso#

Para onde foram ferramentas como gameobject-create?#

A versão 1.0.0 substituiu as ferramentas de uma por ação pelo RQL: rql-query, rql-mutate e rql-schema cobrem cenas, GameObjects, componentes, assets, o Console e o estado do Editor. Veja Ferramentas e RQL.

A IA pode desfazer suas alterações?#

Cada chamada de rql-mutate é registrada como um passo de Undo, então Ctrl+Z (Cmd+Z) a reverte. Use controle de versão para alterações maiores.

Por que o agente vê apenas algumas ferramentas?#

Para economizar contexto. Sete ferramentas ficam visíveis por padrão; as demais são instaladas mas ficam ocultas e ainda são executadas quando chamadas pelo nome. Mostre mais na janela em Tools > Open.

Posso adicionar minhas próprias ferramentas?#

Sim. Marque uma classe com [AiToolType] e um método com [AiTool]. Veja Ferramentas personalizadas.

Como adiciono suporte a Cinemachine, ProBuilder ou Tilemaps?#

Instale a extensão correspondente na seção Extensions da janela ou com unity-mcp-cli install-extension. Veja Extensões.

Funciona no modo Play?#

Sim. O agente pode entrar e sair do modo Play por meio do RQL (membros de editor, como isPlaying). A conexão se reconecta após o domain reload.

Builds, CI e privacidade#

O plugin acaba no build do meu jogo?#

A parte de runtime é compilada nos builds do player, mas um build nunca se conecta sozinho. Você opta por isso no código com UnityMcpPluginRuntime.Initialize(...) para dar ferramentas de IA dentro do seu jogo. Para excluir o plugin completamente, adicione a define de script UNITY_MCP_EXCLUDE_FROM_COMPILATION. Veja Configuração.

Como mantenho o plugin fora das execuções de teste da CI?#

Defina UNITY_MCP_DISABLE=1 no ambiente do processo do Unity, ou use a define UNITY_MCP_EXCLUDE_FROM_COMPILATION. Veja Configuração.

Posso controlá-lo por scripts sem um cliente de IA?#

Sim. unity-mcp-cli run-tool chama qualquer ferramenta a partir de um terminal, e unity-mcp-cli exec executa C# no Editor. Veja a referência da CLI.

Quais dados saem da minha máquina?#

No modo Custom com autorização none ou token, nada passa pelo ai-game.dev: o agente e o Unity conversam por meio do servidor local. Seu cliente de IA ainda envia sua conversa para o próprio provedor de modelo. No modo Cloud, as chamadas de ferramentas e os resultados passam pelo servidor ai-game.dev no trajeto entre seu agente e o Editor.

Como desativo o pop-up de atualização para minha equipe?#

Ative Disable update notifications for the entire team em Edit > Project Settings > AI Game Developer e faça commit de ProjectSettings/AI-Game-Developer-UpdateSettings.asset.

Mais ajuda#

• Solução de problemas para erros.
• A FAQ do site e as melhores práticas para Unity.