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.
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 -fO 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"] }
}]
}
}| 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:
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
- Detectar. O usuário abre uma pasta; a varredura corresponde aos seus marcadores e lista o projeto com seu ícone e nome.
- Ativar. O app dispara
onGameEngine:<id>e espera até 30 segundos porregisterEngine. - Iniciar. O Play chama
editor.launchcom umoperationId. Relate linhas comhost.progress({ operationId, message })(uma mensagem como"Building 40%"desenha uma barra) e verifiqueawait host.cancelled(operationId)entre as etapas. Uma chamada termina após 15 minutos sem progresso, ou 3 horas no total. - Mostrar. Com
gameView: "browser", o painel do jogo carrega a URL queeditor.gameViewretorna. - Conectar. Em um chat, a conexão do agente lista
tools.listcomo as ferramentas do projeto; cada chamada vai paratools.call. Um nome de ferramenta tem de 1 a 64 caracteres deA-Z a-z 0-9 _ -; dê a cada uma uminputSchema. - Pare.
editor.stopencerra o quelaunchiniciou, 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. contractVersionnomeia o contrato de engine que você implementa (apenas1hoje). 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 para saber como os usuários trabalham com projetos de engine.
- Package API para o restante de
ctx.aigd. - Publicando pacotes para compartilhar sua engine.