Ferramentas e 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, e a linguagem de consulta está documentada na referência do 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:

Uma lista curta custa menos tokens e deixa mais espaço para o modelo raciocinar. As outras ferramentas continuam instaladas; veja Ferramentas ocultas.

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:

roots | recurse children | select name active

Encontrar o player:

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

Criar um plano de chão:

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

Adicionar um componente e salvar:

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

Ler apenas os erros do Console:

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#

Assets são endereçados por caminho com unity.asset("Assets/…") ou procurados com unity.assets("t:Material"). Cada extensão 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.

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:

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.

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:

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 e referência do RQL.
• Ferramentas personalizadas para adicionar as suas.
• Boas práticas do Unity para prompting.