# Ferramentas — Unreal Engine · AI Game Developer Wiki

As 27 ferramentas MCP integradas do Unreal - RQL, Blueprints, C++, Python, capturas de tela e console - e exemplos de prompts para IA no Unreal Editor.

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

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

| Ferramenta | O que faz |
| --- | --- |
| `rql-query` | Consulta somente leitura sobre o editor em execução, com resultados em tabela compacta |
| `rql-mutate` | Uma consulta que termina com `set` ou `call`; tudo ou nada, um único passo de desfazer, e uma prévia com `dry_run` |
| `rql-schema` | Lista fontes, funções e classes; com um tipo, lista os membros e métodos desse tipo |

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

```text
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](https://ai-game.dev/pt-br/docs/wiki/unreal/extensions) 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.

| Ferramenta | O que faz |
| --- | --- |
| `blueprint-create` | Cria uma classe Blueprint a partir de uma classe pai |
| `blueprint-get` | Resume um Blueprint: variáveis, componentes, funções e eventos, cadeia de classes pai |
| `blueprint-add-component` | Adiciona um componente ao construction script |
| `blueprint-remove-component` | Remove um componente |
| `blueprint-add-variable` | Adiciona uma variável membro tipada |
| `blueprint-modify-variable` | Altera uma variável membro |
| `blueprint-set-default` | Define uma propriedade padrão da classe |
| `blueprint-add-function` | Adiciona um stub de função |
| `blueprint-add-event` | Adiciona um evento como BeginPlay ou Tick |
| `blueprint-compile` | Compila e retorna uma lista estruturada de erros e avisos |
| `blueprint-spawn` | Coloca uma instância do Blueprint no nível |

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++

| Ferramenta | O que faz |
| --- | --- |
| `source-read` | Lê um arquivo C++ do projeto, em partes |
| `source-create-class` | Gera a estrutura de uma nova classe C++ (header e source) |
| `source-update` | Edita um arquivo de código-fonte |
| `source-delete` | Exclui um arquivo de código-fonte |
| `source-list` | Lista os arquivos de código-fonte do módulo |
| `source-compile` | Compila com o Live Coding quando ele está ativo, caso contrário com o Unreal Build Tool, e retorna um relatório de erros estruturado |

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

| Ferramenta | O que faz |
| --- | --- |
| `python-execute` | Executa Python no editor com o módulo `unreal` já importado |

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](https://ai-game.dev/pt-br/docs/wiki/unreal/cli#exec).

## Família de capturas de tela

| Ferramenta | O que ela faz |
| --- | --- |
| `screenshot-viewport` | Captura o viewport ativo do editor |
| `screenshot-game-view` | Captura a visão de jogo do Play In Editor |
| `screenshot-camera` | Renderiza a partir de um ator de câmera |
| `screenshot-isolated` | Renderiza um único ator isoladamente |

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

| Ferramenta | O que ela faz |
| --- | --- |
| `console-run-command` | Executa um comando de console do Unreal ou define uma variável de console |
| `unreal-tool-list` | Lista todas as ferramentas, incluindo as ocultas, com filtro opcional, descrições e entradas |

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](https://ai-game.dev/pt-br/docs/wiki/unreal/configuration#tool-visibility). Para adicionar capacidades, instale [extensões](https://ai-game.dev/pt-br/docs/wiki/unreal/extensions) ou escreva [ferramentas personalizadas](https://ai-game.dev/pt-br/docs/wiki/unreal/custom-tools).

## 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](https://ai-game.dev/pt-br/docs/wiki/unreal/custom-tools#runtime) 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](https://ai-game.dev/docs/best-practices/unreal).

---

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

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