# Primeiros passos — Unreal Engine · AI Game Developer Wiki

Conecte o Unreal MCP pela primeira vez, entre no ai-game.dev, configure seu cliente de IA e execute seus primeiros prompts de 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/getting-started).

Esta página leva você de um plugin instalado até sua primeira alteração feita por IA no Unreal Editor. Ela pressupõe que você já concluiu a [Instalação](https://ai-game.dev/pt-br/docs/wiki/unreal/installation).

## Etapa 1: abra a janela do AI Game Developer

1. Abra seu projeto no Unreal Editor (pelo app com **Open Editor**, com `unreal-mcp-cli open ./YourProject`, ou como você costuma fazer).
2. Abra o menu **Tools** e escolha **AI Game Developer**.

A janela é a base do plugin. De cima para baixo, ela mostra o nível de log, um botão para abrir a pasta de logs e a versão do plugin; a seção **Connection**; a seção **AI agent**; a seção **Extensions**; e links para ajuda e relatos de bugs.

## Etapa 2: conecte-se ao servidor

A seção **Connection** tem um seletor **Custom / Cloud**. **Cloud** é o padrão e a escolha certa para a maioria das pessoas: ele usa o servidor hospedado em ai-game.dev, então não há nada para rodar localmente.

1. Verifique se **Cloud** está selecionado.
2. Clique em **Authorize**. A janela mostra um link de verificação e um código de usuário curto.
3. Abra o link (ou use **Open verification page**), entre no ai-game.dev, digite o código e aprove.
4. A janela informa **Authorized — signed in to AI Game Dev.**

Se você já entrou com `unreal-mcp-cli login` ou com o app AI Game Dev nesta máquina, o editor pode reaproveitar esse login. Depois da primeira aprovação, as próximas inicializações do editor se reconectam sem nenhum clique.

Fique de olho na linha de status. **Unreal: Connected** com um ponto verde significa que o plugin, a bridge e o servidor estão vinculados. **Unreal: Connecting…** é normal por alguns segundos enquanto a bridge inicia.

**Nota:** Quer manter tudo na sua própria máquina? Escolha **Custom** e rode um `gamedev-mcp-server` local. [Conectando clientes de IA](https://ai-game.dev/pt-br/docs/wiki/unreal/connecting-ai-clients#custom) explica como.

## Etapa 3: conecte seu cliente de IA

A seção **AI agent** configura clientes de IA para você.

1. Escolha seu agente na lista suspensa, por exemplo Claude Code, Cursor, Visual Studio Code (Copilot), Codex ou Gemini.
2. Clique em **Configure**. O plugin grava uma entrada do Unreal MCP no arquivo de configuração MCP desse agente.
3. Reinicie ou recarregue o agente se ele já estiver em execução, para que ele carregue o novo servidor.

Em um terminal, você pode fazer o mesmo com a CLI. Para o Claude Code:

```bash
unreal-mcp-cli setup-mcp claude-code --path ./YourProject
```

Isso grava `.mcp.json` na pasta do projeto. Execute `unreal-mcp-cli setup-mcp --list` para ver todos os agentes suportados e onde fica a configuração de cada um. Todas as opções estão em [Conectando clientes de IA](https://ai-game.dev/pt-br/docs/wiki/unreal/connecting-ai-clients).

Quando o agente se conecta, ele aparece na linha **AI agents** da seção Connection.

## Etapa 4: verifique a conexão

Faça ao seu agente uma pergunta que só o editor pode responder:

```text
List the actors in the current level with their class names.
```

O agente deve chamar `rql-query` e responder com os atores reais do nível aberto. Se ele disser que não tem ferramentas do Unreal, o cliente não carregou o servidor MCP; veja [Solução de problemas](https://ai-game.dev/pt-br/docs/wiki/unreal/troubleshooting#agent-no-tools).

## Etapa 5: seus primeiros prompts de verdade

Comece pequeno e concreto. Alguns prompts que mostram famílias de ferramentas diferentes:

```text
Spawn three cubes in a row and a point light above them.
```

```text
Create a new Actor Blueprint called BP_Coin with a static mesh component
using the engine sphere, compile it, and place three of them in the level.
```

```text
Take a screenshot of the viewport and tell me what you see.
```

```text
Create a C++ actor class called AHealthPickup with a float Heal property,
then compile the project and fix any errors.
```

Cada alteração no editor feita via RQL é um único passo de desfazer, então **Ctrl+Z** no editor reverte a mudança. As ferramentas de compilação retornam listas de erros estruturadas, então "compile e corrija os erros" é um bom prompt de acompanhamento.

**Dica:** As ferramentas de screenshot precisam de um editor real, com GPU. Elas retornam um erro quando o editor roda com `-nullrhi`.

## Bons hábitos para IA no Unreal Editor

- **Dê nomes às coisas.** "Altere a intensidade da luz chamada KeyLight" funciona melhor do que "altere a luz".
- **Peça que ele olhe primeiro.** "Mostre os componentes de BP\_Door antes de alterar" dá ao agente os fatos de que ele precisa.
- **Deixe que ele verifique.** Peça um screenshot ou uma compilação depois de uma alteração.
- **Salve seu trabalho.** Peça ao agente para salvar o nível, ou salve no editor, antes de alterações maiores.
- **Mantenha as sessões focadas.** Uma tarefa por conversa mantém o contexto do agente pequeno e preciso.

Mais conselhos estão em [Boas práticas para Unreal](https://ai-game.dev/docs/best-practices/unreal).

## Próximos passos

- Veja tudo o que o agente pode fazer em [Ferramentas](https://ai-game.dev/pt-br/docs/wiki/unreal/tools).
- Adicione Niagara, PCG, Enhanced Input e mais com [Extensões](https://ai-game.dev/pt-br/docs/wiki/unreal/extensions).
- Ajuste visibilidade, timeouts e logs em [Configuração](https://ai-game.dev/pt-br/docs/wiki/unreal/configuration).
- Controle o editor a partir de scripts com a [referência da CLI](https://ai-game.dev/pt-br/docs/wiki/unreal/cli).

---

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

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