Esta página foi traduzida automaticamente do inglês. Leia o original em inglês.

Pacotes de engine de jogo

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.

Atualizado em 19 de novembro de 2026 Ver como Markdown

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

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.

{
  "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"] }
    }]
  }
}
CampoO que faz
detectQualquer 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
starters1 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)
showcaseComo 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
skillsUma 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:

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étodoO 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.