Esta página se tradujo automáticamente del inglés. Lee el original en inglés.

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.

Actualizado el 19 de noviembre de 2026 Ver como Markdown

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 -f

La 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"] }
    }]
  }
}
CampoQué hace
detectCualquier 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
startersDe 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)
showcaseCó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
skillsUna 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étodoLa 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

  1. Detección. El usuario abre una carpeta; el escaneo coincide con tus marcadores y lista el proyecto con tu icono y tu nombre.
  2. Activación. La app dispara onGameEngine:<id> y espera hasta 30 segundos a registerEngine.
  3. Lanzamiento. Play llama a editor.launch con un operationId. Informa de líneas con host.progress({ operationId, message }) (un mensaje como "Building 40%" dibuja una barra) y comprueba await host.cancelled(operationId) entre pasos. Una llamada termina tras 15 minutos sin progreso, o 3 horas en total.
  4. Mostrar. Con gameView: "browser" el panel del juego carga la URL que devuelve editor.gameView.
  5. Conexión. En un chat, la conexión del agente lista tools.list como las herramientas del proyecto; cada llamada va a tools.call. El nombre de una herramienta tiene de 1 a 64 caracteres de A-Z a-z 0-9 _ -; dale a cada una un inputSchema.
  6. Detener. editor.stop termina lo que launch inició, 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.
  • contractVersion indica el contrato de motor que implementas (solo 1 hoy). Las adiciones mantienen la versión; un cambio incompatible se publicaría como versión 2 junto a la 1.