Paquetes de motores de juego
Enseña a AI Game Dev un motor completo con un paquete: detección de proyectos, diálogo de creación, Play, vista del juego y herramientas en vivo.
Un paquete de motor de juego enseña a AI Game Dev un motor completo: qué carpetas son sus proyectos, cómo crear uno, cómo ejecutarlo, cómo mostrar el juego en ejecución y qué herramientas en vivo recibe el agente mientras se ejecuta. Los motores propios de la app (Unity, Godot, Unreal Engine, BRUTAL, Bevy, Web) implementan el mismo contrato dentro de la app; un paquete lo implementa desde el Extension Host. Los paquetes de motor necesitan AI Game Dev 0.32.0 o superior y se publican en el registro de la comunidad como cualquier otro paquete.
Empieza desde la plantilla
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 -fLa plantilla es el motor de ejemplo samples.toy-engine: detecta carpetas que contienen toy-engine.json, crea proyectos a partir de dos starters, ejecuta el juego como un pequeño servidor Node.js en 127.0.0.1 que muestra el panel del juego, da al agente dos herramientas en vivo y detiene el juego. No necesita binarios nativos.
La mitad declarativa: contributes.gameEngines
La app lee esto sin ejecutar tu código, así que un proyecto se detecta, se lista, se dibuja y se ofrece en el diálogo de creación antes de que arranque tu paquete. Un motor por paquete; su id es el id del paquete.
{
"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 | Qué hace |
|---|---|
detect | Cualquier regla que coincida marca una carpeta como proyecto: exists (una ruta relativa, de hasta 3 segmentos), glob (un patrón de nombre de archivo en la carpeta), contains (un literal en los primeros 64 KB del archivo coincidente), allOf (de 2 a 4 marcadores). Cada motor dispone de 2 segundos por escaneo, así que mantén los marcadores baratos. |
editor | "app" cuando el motor tiene una aplicación de editor que lanzar; si no, "none" |
connection | "package": tu paquete sirve las herramientas en vivo del agente; "none": sin herramientas |
gameView | "browser": el juego en ejecución es una página web que muestra el panel del juego |
starters | De 1 a 8 starters para el diálogo de creación; como máximo un recommended; preview es una imagen ancha (aproximadamente 16:7, por ejemplo 640×280); blank y game indican al diálogo qué aspecto tiene un starter (omítelos para dar soporte a la app 0.32.0-beta.1 y anteriores, que los rechazan) |
showcase | Cómo presenta el motor el diálogo de creación: colores accent y accent2 (#rrggbb), pitch (80 caracteres), summary, languages, hasta 5 tags, shortName |
editorInstall | {url, label}: dónde conseguir lo necesario para abrir un proyecto |
skills | Una carpeta del paquete con <skill>/SKILL.md que el agente carga para los proyectos de este motor |
Un paquete nunca reetiqueta un proyecto de Unity, Godot, Unreal o BRUTAL. Un campo no válido descarta toda la entrada del motor; gamedev pkg validate la nombra.
La mitad de código: registerEngine
activate se ejecuta en onGameEngine:<id>, la primera vez que la app necesita el motor, y registra la implementación:
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));
}La app llama a tus métodos; cada método es asíncrono, recibe y devuelve JSON simple y nunca lanza excepciones: un fallo es un resultado, como { success: false, errorMessage }.
| Método | La app lo llama |
|---|---|
project.validate(path) | Para confirmar que una carpeta detectada es un proyecto |
project.create({ projectPath, name, starter?, force? }) | Desde el diálogo de creación |
plugin.status, install, update(projectPath) | Para preparar dentro del proyecto lo que este necesita |
editor.availability() | Antes de un lanzamiento: puede el motor ejecutarse en este ordenador |
editor.launch(projectPath, { operationId? }) | Al pulsar Play y cuando el agente se conecta |
editor.diagnose(projectPath) | Para el estado del panel Projects |
editor.health?, editor.stop?, editor.gameView?, editor.runIdentity?, editor.prepare? | Opcional: explicar un fallo, detener el juego, la URL de la vista del juego, distinguir ejecuciones, preparar a petición |
tools.list(projectPath), tools.call(projectPath, call) | Las herramientas en vivo del agente (connection: "package") |
Los métodos opcionales que omitas reciben una respuesta neutra: sin detención, sin vista del juego, sin herramientas.
Una ejecución, paso a paso
- Detección. El usuario abre una carpeta; el escaneo coincide con tus marcadores y lista el proyecto con tu icono y tu nombre.
- Activación. La app dispara
onGameEngine:<id>y espera hasta 30 segundos aregisterEngine. - Lanzamiento. Play llama a
editor.launchcon unoperationId. Informa de líneas conhost.progress({ operationId, message })(un mensaje como"Building 40%"dibuja una barra) y compruebaawait host.cancelled(operationId)entre pasos. Una llamada termina tras 15 minutos sin progreso, o 3 horas en total. - Mostrar. Con
gameView: "browser"el panel del juego carga la URL que devuelveeditor.gameView. - Conexión. En un chat, la conexión del agente lista
tools.listcomo las herramientas del proyecto; cada llamada va atools.call. El nombre de una herramienta tiene de 1 a 64 caracteres deA-Z a-z 0-9 _ -; dale a cada una uninputSchema. - Detener.
editor.stoptermina lo quelaunchinició, y solo eso.
Los servicios del host son logger(scope), progress, cancelled, compareVersions(a, b), y bloqueos de archivos y eliminación de la cuarentena de macOS para rutas dentro de tus propias carpetas de almacenamiento. Guarda el estado que sobrevive a una llamada (un registro de ejecución, un runtime descargado) en ctx.globalStoragePath o ctx.projectStoragePath.
Pruébalo
gamedev pkg validate: el manifiesto y los archivos que menciona.- Enlázalo en una carpeta de pruebas, crea un proyecto desde el diálogo, pulsa Play, conéctate en un chat, llama a cada herramienta, detén; luego lee
gamedev pkg logs <id>para ver toda la ejecución. contractVersionindica el contrato de motor que implementas (solo1hoy). Las adiciones mantienen la versión; un cambio incompatible se publicaría como versión 2 junto a la 1.
Páginas relacionadas
- Proyectos y motores para saber cómo trabajan los usuarios con proyectos de motor.
- Package API para el resto de
ctx.aigd. - Publicar paquetes para compartir tu motor.