# Primeiros passos — Unity · AI Game Developer Wiki

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.

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

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](https://ai-game.dev/pt-br/docs/wiki/unity/installation).

## 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](https://ai-game.dev/docs/auth).

**Nota**

Você não precisa de uma conta para experimentar o plugin. Mude a conexão para **Custom** para rodar um MCP server local na sua máquina. Veja [Configuração](https://ai-game.dev/pt-br/docs/wiki/unity/configuration#connection-modes).

## 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:

```bash
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](https://ai-game.dev/pt-br/docs/wiki/unity/connecting-ai-clients).

## 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:

```text
Explain my scene hierarchy.
```

```text
Create 3 spheres stacked on top of each other, then save the scene.
```

```text
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:

```text
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:

```text
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](https://ai-game.dev/pt-br/docs/wiki/unity/configuration#tools-prompts-resources).

A página de [Boas práticas no Unity](https://ai-game.dev/docs/best-practices/unity) tem mais dicas de prompting.

## Próximos passos

- [Ferramentas e RQL](https://ai-game.dev/pt-br/docs/wiki/unity/tools-and-rql): tudo o que o agente pode fazer.
- [Extensões](https://ai-game.dev/pt-br/docs/wiki/unity/extensions): adicione Animation, Cinemachine, ProBuilder, Tilemap e outros pacotes.
- [Ferramentas personalizadas](https://ai-game.dev/pt-br/docs/wiki/unity/custom-tools): exponha seus próprios métodos C# ao agente.
- Travou? Veja [Solução de problemas](https://ai-game.dev/pt-br/docs/wiki/unity/troubleshooting).

---

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

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