# Ferramentas e RQL — Unity · AI Game Developer Wiki

O que um agente de IA pode fazer no Unity Editor com Unity MCP: consultas e mutações RQL, capturas de tela, scripts C#, testes, pacotes e profiling.

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

Esta página explica o que o agente de IA pode fazer no seu projeto Unity depois que o Unity MCP está conectado: quais ferramentas ele enxerga, como o RQL permite ler e alterar quase tudo no Editor e quais ferramentas estão instaladas mas ocultas. A lista completa e pesquisável com parâmetros está no [catálogo de ferramentas do Unity](https://ai-game.dev/docs/tools/unity), e a linguagem de consulta está documentada na [referência do RQL](https://ai-game.dev/docs/rql).

## As ferramentas que o agente enxerga por padrão

Desde a versão 1.0.0 o plugin mantém a lista de ferramentas do agente curta. Estas sete ferramentas ficam visíveis após a instalação:

| Ferramenta | O que ela faz |
| --- | --- |
| `rql-query` | Lê dados do Editor com uma consulta RQL: cenas, GameObjects, componentes, assets, o Console, configurações, testes, o profiler. |
| `rql-mutate` | Altera dados do Editor ou chama operações do Editor com RQL: cria, modifica, move e exclui objetos e assets, abre e salva cenas. |
| `rql-schema` | Descreve as fontes, tipos, membros e chamadas que o RQL pode usar, e imprime guias de tópicos. O agente começa por aqui quando está em dúvida. |
| `script-execute` | Compila e executa código C# no Editor com Roslyn e retorna o resultado. |
| `screenshot-isolated` | Renderiza um GameObject isolado a partir de um ângulo escolhido, opcionalmente como um composto 2x2, para que o modelo possa observá-lo. |
| `tests-run` | Executa testes EditMode ou PlayMode e retorna os resultados por teste. |
| `unity-tool-list` | Lista todas as ferramentas e se o agente as enxerga. |

Uma lista curta custa menos tokens e deixa mais espaço para o modelo raciocinar. As outras ferramentas continuam instaladas; veja [Ferramentas ocultas](https://ai-game.dev/pt-br/docs/wiki/unity/tools-and-rql#hidden-tools).

## RQL: uma linguagem para todo o Editor

RQL é uma linguagem de consulta sobre os dados vivos do Editor. Uma consulta começa com uma **fonte** e passa o resultado por etapas separadas por `|`, como `where`, `select`, `get`, `set` e `call`. Em vez de uma ferramenta por ação (as antigas `gameobject-create`, `scene-save`, `console-get-logs` e dezenas de outras), o agente escreve uma única consulta.

Ler toda a hierarquia das cenas abertas:

```text
roots | recurse children | select name active
```

Encontrar o player:

```text
objects | where name == "Player" | select path name active
```

Criar um plano de chão:

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

Adicionar um componente e salvar:

```text
objects | where name == "Player" | call AddComponent("Rigidbody")
editor | call SaveScenes()
```

Ler apenas os erros do Console:

```text
console | where logType == "Error"
```

Cada chamada de `rql-mutate` é um grupo de Undo, então Ctrl+Z a reverte, e assets, cenas e o prefab aberto alterados são salvos após a mutação. `rql-mutate` também aceita `dry_run` para pré-visualizar o que mudaria e `max_targets` para limitar quantos objetos uma mutação pode afetar.

### Fontes RQL no Unity

| Fonte | Conteúdo |
| --- | --- |
| `scenes`, `roots`, `objects` | Cenas carregadas, seus GameObjects raiz e todos os GameObjects nelas. |
| `selection` | A seleção atual do Editor. |
| `prefab` | O prefab aberto no modo prefab. |
| `editor` | Operações do Editor: criar GameObjects, materiais, pastas e cenas; abrir e salvar cenas e prefabs; copiar, mover e excluir assets; executar itens de menu; estado do modo play. |
| `settings` | Configurações do projeto. |
| `console` | Entradas de log do Editor capturadas. |
| `shaders`, `componentTypes` | Shaders e tipos de componente disponíveis. |
| `tests`, `testResults` | A árvore de testes e os últimos resultados. |
| `profiler` | Dados de memória, renderização, scripts e frames; iniciar, parar, salvar e carregar capturas. |
| `lighting` | O ambiente da cena ativa (ambiente, névoa, skybox, sol, reflexões), as Lighting Settings e o bake. |

Assets são endereçados por caminho com `unity.asset("Assets/…")` ou procurados com `unity.assets("t:Material")`. Cada [extensão](https://ai-game.dev/pt-br/docs/wiki/unity/extensions) instalada adiciona suas próprias fontes e tipos, por exemplo `tilemap` ou `cinemachine`.

Como o RQL funciona por reflexão, o agente também pode ler e definir membros dos seus próprios componentes, não só dos componentes nativos do Unity. Você pode ensinar seus próprios tipos ao RQL com [adaptadores personalizados](https://ai-game.dev/docs/rql/custom-adapters).

## Scripts e execução de C#

`script-execute` compila um trecho de C# com Roslyn e o executa no Editor. Ele recebe o código e, opcionalmente, `className`, `methodName`, `usings` extras e arquivos auxiliares para `include`. É a válvula de escape para tudo o que o RQL não cobre. Pelo terminal, `unity-mcp-cli exec` chama a mesma ferramenta:

```bash
unity-mcp-cli exec 'Application.unityVersion'
```

Para escrever arquivos em vez de executar código, as ferramentas ocultas `script-read`, `script-update-or-create` e `script-delete` gerenciam arquivos `.cs` no projeto. O Unity recompila após uma alteração; a conexão cai brevemente durante o domain reload e volta sozinha.

## Testes

`tests-run` executa testes EditMode ou PlayMode (`testMode`, padrão EditMode). Filtre por assembly, namespace, classe ou método, ou passe uma seleção RQL sobre a fonte `tests` para executar exatamente os testes escolhidos como uma única run. Os resultados podem ser filtrados com RQL sobre `testResults`. Opções controlam se testes aprovados, mensagens, stack traces e logs do Console são incluídos, o que mantém a saída pequena.

```bash
unity-mcp-cli run-tool tests-run ./MyUnityProject --input '{"testMode":"EditMode"}'
```

## Capturas de tela

`screenshot-isolated` fica visível por padrão. Outras três ficam ocultas: `screenshot-scene-view`, `screenshot-game-view` e `screenshot-camera`. As imagens têm no máximo 3840 pixels na maior borda para caber no transporte MCP. Capturas de tela precisam de um dispositivo gráfico: um Editor iniciado com `-nographics` retorna um erro em vez de uma imagem em branco.

## Ferramentas ocultas

Estas estão instaladas, mas não na lista do agente. Uma ferramenta oculta ainda é executada quando chamada pelo nome.

- Capturas de tela: `screenshot-scene-view`, `screenshot-game-view`, `screenshot-camera`.
- Scripts: `script-read`, `script-update-or-create`, `script-delete`.
- Pacotes: `package-list`, `package-search`, `package-add`, `package-remove` para o Unity Package Manager.
- Gerenciamento de ferramentas: `tool-set-visibility`, e seu alias obsoleto `tool-set-enabled-state`.

Mostre-as na janela AI Game Developer (**Tools > Open**), com a ferramenta `tool-set-visibility`, ou com:

```bash
unity-mcp-cli configure ./MyUnityProject --enable-tools package-add,package-list
```

## Prompts e skills

O plugin também inclui 46 prompts MCP (modelos de comando de barra como `setup-basic-scene` ou `add-event-system`) em seis grupos: scripting, GameObjects e componentes, cenas, depuração e testes, gerenciamento de assets, animação e timeline. Eles ficam ocultos por padrão; ative os que quiser em **Prompts > Open**.

**Skills** são arquivos Markdown que o plugin gera na pasta de skills do seu agente. Eles incluem o guia `unity-rql` com a sintaxe RQL para o Unity e cada extensão instalada, além de notas de configuração e de CLI. Ative-as com **Skills > Auto-generate** na janela, ou execute `unity-mcp-cli setup-skills <agent>`.

## Nomes de ferramentas de tutoriais antigos

A versão 1.0.0 removeu as ferramentas de uma por ação. Se um tutorial mencionar uma delas, use o RQL:

- `gameobject-create`, `gameobject-find`, `gameobject-modify`, `gameobject-destroy`, `gameobject-component-*`: RQL sobre `objects`, `roots` e `selection` com `set` e `call`.
- `scene-create`, `scene-open`, `scene-save`: `editor | call NewScene(…)`, `OpenScene(…)`, `SaveScenes()`.
- `assets-*`, `assets-prefab-*`, `assets-material-create`: `unity.asset(…)`, `unity.assets(…)` e chamadas de `editor` como `CreateMaterial`, `CopyAsset`, `InstantiatePrefab`.
- `console-get-logs`, `console-clear-logs`: a fonte `console` e `editor | call ClearConsole()`.
- `editor-application-*`, `editor-selection-*`: membros de `editor` como `isPlaying` e `selection`.
- `reflection-method-find`, `reflection-method-call`, `type-get-json-schema`: `call` do RQL e `rql-schema`.
- `profiler-*`: a fonte `profiler`.

## Páginas relacionadas

- [Catálogo de ferramentas do Unity](https://ai-game.dev/docs/tools/unity) e [referência do RQL](https://ai-game.dev/docs/rql).
- [Ferramentas personalizadas](https://ai-game.dev/pt-br/docs/wiki/unity/custom-tools) para adicionar as suas.
- [Boas práticas do Unity](https://ai-game.dev/docs/best-practices/unity) para prompting.

---

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

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