Esta página foi traduzida automaticamente do inglês. Leia o original em inglês.

Primeiros passos

Conecte seu primeiro agente de IA ao Unity Editor com o Unity MCP, verifique a conexão e teste seus primeiros prompts no Claude Code, Cursor ou Copilot.

Atualizado em 4 de novembro de 2026 Ver como Markdown

Esta página leva você de um plugin instalado a um agente de IA que altera sua cena do Unity. Ela usa a conexão Cloud padrão através do ai-game.dev e o Claude Code como agente de exemplo; os passos são os mesmos para qualquer outro cliente. Se o plugin ainda não estiver instalado, comece pela Instalação.

Passo 1: abra a janela do AI Game Developer

Abra seu projeto no Unity e escolha Window > AI Game Developer — MCP (Ctrl+Alt+A, ou Cmd+Option+A no macOS). A aba da janela tem o título Game Developer. Você também pode clicar no botão AI na barra de ferramentas da Scene View.

A janela mostra a conexão como uma linha do tempo de cima para baixo: Unity, depois MCP server, depois AI agent. Cada ponto tem um círculo de status. Seu objetivo é deixar os três verdes.

Passo 2: faça login (modo Cloud)

O seletor Connection no topo tem duas opções, Custom e Cloud. Uma instalação nova usa Cloud.

  1. Clique em Authorize ao lado do campo Cloud Token.
  2. Seu navegador abre a página de login por dispositivo do ai-game.dev. A janela mostra um código curto ("Code: … — Authorize in browser"). Verifique se o navegador mostra o mesmo código e aprove.
  3. O campo muda para "Signed in via account", e o status do Unity passa a Connected.

O login é armazenado para toda a máquina em ~/.ai-game-dev/credentials.json. Se você já fez login com unity-mcp-cli login ou com o app AI Game Dev, o Editor aproveita essa credencial e você pode pular este passo. Mais detalhes em Autenticação.

Passo 3: configure seu agente de IA

  1. Na seção AI agent, escolha seu cliente na lista suspensa, por exemplo Claude Code.
  2. Em Model Context Protocol (MCP), clique em Configure. O plugin grava o arquivo de configuração MCP do cliente (para o Claude Code, .mcp.json na raiz do projeto) com uma URL fixada neste projeto.
  3. Em Skills, ative Auto-generate ou clique em Generate. Isso grava os arquivos de skills que o agente lê para aprender a usar o Unity MCP e o RQL (para o Claude Code, em .claude/skills). Agentes que dão suporte a skills funcionam visivelmente melhor com elas.
  4. Inicie seu cliente de IA a partir da pasta do projeto, ou reinicie-o se ele já estiver em execução, para que carregue a nova configuração.

O mesmo pode ser feito pelo terminal:

unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli setup-skills claude-code ./MyUnityProject

setup-skills precisa que o Editor esteja aberto e conectado. Outros clientes e a configuração manual são abordados em Conectando clientes de IA.

Passo 4: verifique a conexão

  • Na janela, o status do Unity mostra Connected e o ponto do agente de IA mostra seu cliente como configurado.
  • No seu cliente de IA, liste os MCP servers ou as ferramentas. No Claude Code, execute /mcp; você deve ver ai-game-developer com ferramentas como rql-query, rql-mutate, rql-schema, script-execute, screenshot-isolated, tests-run e unity-tool-list.
  • Se seu cliente foi conectado antes de o Unity estar pronto, reconecte-o para que ele liste as ferramentas novamente.

Pelo terminal, unity-mcp-cli status ./MyUnityProject mostra se o Unity está em execução e se o servidor configurado está acessível.

Passo 5: seus primeiros prompts

Comece com um pedido que lê a cena e depois um que a altera:

Explain my scene hierarchy.
Create 3 spheres stacked on top of each other, then save the scene.
Create a metallic golden material and assign it to a new sphere.

Observe a Hierarchy: os objetos aparecem conforme o agente trabalha. Nos bastidores, o agente envia RQL, por exemplo uma mutação como esta:

editor | call CreateGameObject({name: "Ground", primitive: "Plane"})

Toda alteração via RQL é registrada como um único passo de Undo, então Ctrl+Z (Cmd+Z) a desfaz como uma edição manual.

Um exemplo mais longo que exercita várias ferramentas:

Create a new scene called Playground. Add a plane scaled to 10, 1, 10 and a capsule
named Player at 0, 1, 0 with a Rigidbody. Write a PlayerController script that moves
the Player with WASD, attach it, and take a screenshot of the Player.

Mais ideias para experimentar:

  • "Leia o Console e me diga se há algum erro."
  • "Execute todos os testes EditMode e resuma as falhas."
  • "Liste todos os Rigidbody das cenas abertas com sua massa."
  • "Inicie o profiler, grave alguns segundos do modo Play e informe o tempo de frame."

Dicas para melhores resultados

  • Seja específico quanto a nomes, posições e caminhos de arquivo. Quanto mais preciso o pedido, menos correções.
  • Escolha um modelo forte no seu cliente; tarefas com uso intenso de ferramentas se beneficiam disso.
  • No VS Code com Copilot, mude o chat para o modo Agent, ou as ferramentas não serão chamadas.
  • Mantenha curta a lista de ferramentas do agente. Ferramentas ocultas ainda são executadas quando chamadas pelo nome, e menos ferramentas visíveis deixam mais contexto para o raciocínio. Veja Configuração.

A página de Boas práticas no Unity tem mais dicas de prompting.

Próximos passos