# Pacotes de engine de jogo — App e CLI do AI Game Dev · AI Game Developer Wiki

Ensine uma engine inteira ao AI Game Dev com um pacote: detecção de projetos, diálogo de criação, Play, game view e ferramentas ao vivo do agente.

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

Um pacote de engine de jogo ensina uma engine inteira ao AI Game Dev: quais pastas são seus projetos, como criar um, como executá-lo, como mostrar o jogo em execução e quais ferramentas ao vivo o agente recebe enquanto ele roda. As engines próprias do app (Unity, Godot, Unreal Engine, BRUTAL, Bevy, Web) implementam o mesmo contrato dentro do app; um pacote o implementa a partir do Extension Host. Pacotes de engine exigem AI Game Dev 0.32.0 ou mais recente e são publicados no registro da comunidade como qualquer outro pacote.

## Comece pelo template

```bash
gamedev pkg init forge --engine --id acme.forge
cd ~/projects && gamedev pkg dev ~/src/forge      # then open a folder, or create a Forge project
gamedev pkg logs acme.forge -f
```

O template é a engine de exemplo `samples.toy-engine`: ela detecta pastas que contêm `toy-engine.json`, cria projetos a partir de dois starters, executa o jogo como um pequeno servidor Node.js em `127.0.0.1` que o painel do jogo exibe, fornece ao agente duas ferramentas ao vivo e encerra o jogo. Ela não precisa de binários nativos.

## A metade declarativa: contributes.gameEngines

O app lê isso sem executar seu código, então um projeto é detectado, listado, desenhado e oferecido no diálogo de criação antes que seu pacote inicie. Uma engine por pacote; seu `id` é o id do pacote.

```json
{
  "engines": { "aigd": ">=0.32.0" },
  "contributes": {
    "gameEngines": [{
      "id": "acme.forge",
      "contractVersion": 1,
      "displayName": "Forge",
      "icon": "media/forge.svg",
      "explorerIcons": { "folder": "media/forge.svg", "folderOpen": "media/forge.svg" },
      "detect": [{ "exists": "forge.json", "type": "file" }],
      "ignoreDirs": [".forge"],
      "editor": "none",
      "connection": "package",
      "gameView": "browser",
      "starters": [
        { "id": "empty", "label": "Empty", "description": "A blank canvas", "preview": "media/starter-empty.webp", "blank": true },
        { "id": "platformer", "label": "Platformer", "description": "A small playable level", "preview": "media/starter-platformer.webp", "recommended": true, "game": true }
      ],
      "defaultProjectName": "forgegame",
      "showcase": { "accent": "#ff8a3d", "pitch": "A tiny canvas engine, run by a package", "languages": "JavaScript", "tags": ["JavaScript", "Canvas"] }
    }]
  }
}
```

| Campo | O que faz |
| --- | --- |
| `detect` | Qualquer regra correspondente marca uma pasta como projeto: `exists` (um caminho relativo, com até 3 segmentos), `glob` (um padrão de nome de arquivo na pasta), `contains` (um literal nos primeiros 64 KB do arquivo correspondido), `allOf` (2 a 4 marcadores). Cada engine tem 2 segundos por varredura, então mantenha os marcadores baratos. |
| `editor` | `"app"` quando a engine tem um aplicativo de editor para iniciar; caso contrário, `"none"` |
| `connection` | `"package"`: seu pacote fornece as ferramentas ao vivo do agente; `"none"`: sem ferramentas |
| `gameView` | `"browser"`: o jogo em execução é uma página web que o painel do jogo exibe |
| `starters` | 1 a 8 starters para o diálogo de criação; no máximo um `recommended`; `preview` é uma imagem larga (cerca de 16:7, por exemplo 640×280); `blank` e `game` informam ao diálogo como um starter se parece (deixe-os de fora para dar suporte ao app 0.32.0-beta.1 e anteriores, que os recusam) |
| `showcase` | Como o diálogo de criação apresenta a engine: cores `accent` e `accent2` (`#rrggbb`), `pitch` (80 caracteres), `summary`, `languages`, até 5 `tags`, `shortName` |
| `editorInstall` | `{url, label}`: onde obter o que é necessário para abrir um projeto |
| `skills` | Uma pasta do pacote com `<skill>/SKILL.md` que o agente carrega para os projetos desta engine |

Um pacote nunca reclassifica um projeto Unity, Godot, Unreal ou BRUTAL. Um campo inválido descarta toda a entrada da engine; `gamedev pkg validate` indica qual.

## A metade de código: registerEngine

`activate` é executado em `onGameEngine:<id>`, na primeira vez que o app precisa da engine, e registra a implementação:

```typescript
import type { PackageContext, GameEngineImplementation } from "./types/aigd";

export async function activate(ctx: PackageContext): Promise<void> {
  if (!ctx.aigd.gameEngines) return;                 // an app older than 0.32.0
  const host = ctx.aigd.gameEngines.host;            // the app's services, scoped to this package
  const engine: GameEngineImplementation = { project: { /* … */ }, plugin: { /* … */ }, editor: { /* … */ }, tools: { /* … */ } };
  ctx.subscriptions.push(await ctx.aigd.gameEngines.registerEngine("acme.forge", engine));
}
```

O app chama seus métodos; todo método é async, recebe e retorna JSON simples e **nunca lança exceção**: uma falha é um resultado, como `{ success: false, errorMessage }`.

| Método | O app o chama |
| --- | --- |
| `project.validate(path)` | Para confirmar que uma pasta detectada é um projeto |
| `project.create({ projectPath, name, starter?, force? })` | A partir do diálogo de criação |
| `plugin.status`, `install`, `update(projectPath)` | Para configurar dentro do projeto o que ele precisa |
| `editor.availability()` | Antes de uma inicialização: a engine consegue rodar neste computador |
| `editor.launch(projectPath, { operationId? })` | No Play e quando o agente se conecta |
| `editor.diagnose(projectPath)` | Para o status do painel Projects |
| `editor.health?`, `editor.stop?`, `editor.gameView?`, `editor.runIdentity?`, `editor.prepare?` | Opcionais: explicar uma falha, encerrar o jogo, a URL do game view, diferenciar execuções, preparar sob demanda |
| `tools.list(projectPath)`, `tools.call(projectPath, call)` | As ferramentas ao vivo do agente (`connection: "package"`) |

Métodos opcionais que você omitir recebem uma resposta neutra: sem stop, sem game view, sem ferramentas.

## Uma execução, passo a passo

1. **Detectar.** O usuário abre uma pasta; a varredura corresponde aos seus marcadores e lista o projeto com seu ícone e nome.
2. **Ativar.** O app dispara `onGameEngine:<id>` e espera até 30 segundos por `registerEngine`.
3. **Iniciar.** O Play chama `editor.launch` com um `operationId`. Relate linhas com `host.progress({ operationId, message })` (uma mensagem como `"Building 40%"` desenha uma barra) e verifique `await host.cancelled(operationId)` entre as etapas. Uma chamada termina após 15 minutos sem progresso, ou 3 horas no total.
4. **Mostrar.** Com `gameView: "browser"`, o painel do jogo carrega a URL que `editor.gameView` retorna.
5. **Conectar.** Em um chat, a conexão do agente lista `tools.list` como as ferramentas do projeto; cada chamada vai para `tools.call`. Um nome de ferramenta tem de 1 a 64 caracteres de `A-Z a-z 0-9 _ -`; dê a cada uma um `inputSchema`.
6. **Pare.** `editor.stop` encerra o que `launch` iniciou, e apenas isso.

Os serviços do host são `logger(scope)`, `progress`, `cancelled`, `compareVersions(a, b)`, além de locks de arquivo e remoção de quarentena do macOS para caminhos dentro das suas próprias pastas de armazenamento. Mantenha o estado que sobrevive a uma chamada (um registro de execução, um runtime baixado) em `ctx.globalStoragePath` ou `ctx.projectStoragePath`.

## Teste

- `gamedev pkg validate`: o manifesto e os arquivos que ele nomeia.
- Vincule-o a uma pasta de teste, crie um projeto pelo diálogo, pressione Play, conecte-se em um chat, chame cada ferramenta, pare; depois leia `gamedev pkg logs <id>` para ver a execução inteira.
- `contractVersion` nomeia o contrato de engine que você implementa (apenas `1` hoje). Adições mantêm a versão; uma mudança incompatível seria lançada como versão 2 ao lado da 1.

## Páginas relacionadas

- [Projetos e engines](https://ai-game.dev/pt-br/docs/wiki/app/projects-and-engines) para saber como os usuários trabalham com projetos de engine.
- [Package API](https://ai-game.dev/pt-br/docs/wiki/app/package-api) para o restante de `ctx.aigd`.
- [Publicando pacotes](https://ai-game.dev/pt-br/docs/wiki/app/publishing-packages) para compartilhar sua engine.

---

Source (HTML): https://ai-game.dev/pt-br/docs/wiki/app/game-engine-packages

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