Ferramentas

Esta página descreve o que um agente de IA pode fazer no Unreal Editor com o Unreal MCP. O plugin traz 27 ferramentas em 7 famílias. Você raramente chama uma ferramenta pelo nome: peça em linguagem natural e o agente escolhe a ferramenta. Conhecer as famílias ajuda você a pedir coisas que o agente realmente consegue fazer.

Para ver os cards e parâmetros de cada ferramenta, consulte o catálogo de ferramentas do Unreal.

RQL: uma linguagem de consulta para os dados do editor#

O Unreal MCP não tem uma ferramenta por operação do editor. Em vez disso, os dados do editor passam pelo RQL, uma linguagem de consulta que lê e altera actors, componentes, assets, níveis e o estado do editor em uma única chamada.

Alguns exemplos de como o RQL se parece (o agente escreve isso para você):

actors | where $ is PointLight | select $ref Label Intensity
actors | where Label == "Door_01" | set Location = "(0, 0, 100)"
editor | call SpawnActor("PointLight")
console | where Verbosity == "Error"

Além de actors e componentes, o RQL alcança:

• Assets e níveis: criar, copiar, mover, excluir e importar assets, criar pastas e instâncias de material, abrir, criar e salvar níveis, adicionar subníveis de streaming.
• Estado do editor: seleção, estado do Play In Editor, histórico de desfazer, o log do editor.
• DataTables: ler e editar linhas (Rows["Sword"].Damage), adicionar, remover, renomear e duplicar linhas.
• Gameplay tags: listar, adicionar, remover e renomear tags.
• Project Settings e Editor Preferences: ler e alterar propriedades de configuração, salvas no arquivo .ini correto.
• Grafos de Blueprint: adicionar chamadas de função, variáveis, eventos, casts, branches e loops, conectar pinos e então call Compile().
• Widget Blueprints: percorrer e editar a árvore de widgets, adicionar widgets e definir o layout.
• Structs definidas pelo usuário: adicionar, remover e renomear campos.
• Level Sequences: vincular actors, adicionar trilhas e chaves.

Toda mutação é uma transação do editor, então Ctrl+Z a reverte. O agente aprende a linguagem com a skill unreal-rql, que também lista o que as extensões instaladas acrescentam.

Exemplos de prompts:

• "Liste todas as point lights do nível com sua intensidade e depois dobre a intensidade das mais fracas."
• "Crie 20 cubos em uma grade de 5 por 4, com 200 unidades de distância entre eles."
• "Adicione uma linha Bow com Damage 7 à DataTable DT_Weapons."
• "Defina o mapa padrão do jogo como /Game/Maps/Arena."

Família Blueprint#

A criação de Blueprints é a principal superfície de script do Unreal, e o agente tem um ciclo de feedback completo: criar, editar, compilar, ler os erros, corrigir.

Exemplo: "Crie um Blueprint de Actor BP_Door com um componente static mesh e uma variável bool IsOpen, compile e coloque uma instância na origem."

Família Source / C++#

Todas as operações de arquivo são limitadas a <Project>/Source/. Exemplo: "Crie um componente C++ UHealthComponent com MaxHealth e uma função TakeDamage, compile e corrija quaisquer erros."

Família Python#

A última expressão é retornada como resultado, a saída de print volta como logs e os erros apontam para a linha que falhou. include adiciona arquivos ou pastas auxiliares de <Project>/.ai-game-dev/snippets, e timeout (padrão de 30 segundos) interrompe um script descontrolado. O plugin habilita o Python Editor Script Plugin do Unreal; o Python é exclusivo do editor e nunca vai junto em um jogo empacotado. A ligação de grafos de Blueprint não é exposta ao Python; use as ferramentas de Blueprint ou o RQL para isso.

Você também pode executar Python a partir de um terminal com unreal-mcp-cli exec, veja a referência da CLI.

Família de capturas de tela#

As imagens voltam como conteúdo PNG que o modelo pode examinar, 1024 pixels por padrão e no máximo 2048 por lado. Elas exigem um editor com GPU; em -nullrhi retornam um erro. Exemplo: "Tire uma captura de tela de CameraActor_Main e me diga se a iluminação está escura demais."

Console e lista de ferramentas#

A leitura do log, do estado do Play In Editor e da seleção passa pelo RQL.

Ferramentas que o agente nunca vê#

Algumas ferramentas de sistema atendem à CLI e ao app e não são mostradas aos agentes de IA:

• ping: verifica a cadeia de plugin, bridge e servidor.
• unreal-skill-generate: grava um SKILL.md por ferramenta em uma pasta de skills (padrão .claude/skills); o botão Generate skill files usa essa ferramenta.
• unreal-skill-create: gera um novo arquivo de ferramenta em C++ no módulo de editor do plugin. É preciso ter o plugin instalado a partir do código-fonte e recompilar o editor antes que a ferramenta funcione.
• editor-quit: salva e fecha um editor iniciado por uma sessão da CLI.

Prompts e recursos#

O plugin também traz um prompt MCP, level-design-brief (um briefing de level design a partir de um tema), e dois recursos: unreal://project/levels (um snapshot JSON do mundo ativo e seus níveis) e unreal://project/icon.

Controle o que o agente vê#

Oculte as ferramentas de que você não precisa na janela MCP Tools, ou sirva apenas um conjunto fixo com UNREAL_MCP_TOOLS. Veja Configuração. Para adicionar capacidades, instale extensões ou escreva ferramentas personalizadas.

Somente no editor#

Todas as 27 ferramentas controlam o editor. Várias são poderosas (rql-mutate, console-run-command, python-execute), então nenhuma delas é compilada em um jogo empacotado. Um jogo que opta por uma conexão em tempo de execução expõe apenas as ferramentas que ele mesmo registra.

Dicas para aproveitar ao máximo essas ferramentas estão em Boas práticas para Unreal.