# Paquetes de motores de juego — App y CLI de AI Game Dev · AI Game Developer Wiki

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.

Esta página se tradujo automáticamente del inglés. [Lee el original en inglés](https://ai-game.dev/docs/wiki/app/game-engine-packages).

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

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

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.

```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 | 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:

```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));
}
```

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

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.

## Páginas relacionadas

- [Proyectos y motores](https://ai-game.dev/es/docs/wiki/app/projects-and-engines) para saber cómo trabajan los usuarios con proyectos de motor.
- [Package API](https://ai-game.dev/es/docs/wiki/app/package-api) para el resto de `ctx.aigd`.
- [Publicar paquetes](https://ai-game.dev/es/docs/wiki/app/publishing-packages) para compartir tu motor.

---

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

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