# API de paquetes — App y CLI de AI Game Dev · AI Game Developer Wiki

La API ctx.aigd de los paquetes de AI Game Dev: espacios de nombres, miembros estables y propuestos, llamadas solo de escritorio y ejemplos reales.

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

El código de tu paquete llega a la app a través de un único objeto, `ctx.aigd`, que se entrega a `activate(ctx)`. Esta página enumera sus espacios de nombres, indica qué miembros son estables y cuáles son propuestos, y muestra ejemplos funcionales de las llamadas que hacen la mayoría de los paquetes: comandos, comandos de barra, herramientas de agente, ajustes, mensajes, webviews, vistas de árbol, editores personalizados, tutoriales y estado almacenado. La versión de la API de paquetes es la 0.4.0.

## Tipos

`gamedev pkg init` escribe toda la API en un único archivo autocontenido, `src/types/aigd.d.ts`, generado a partir del propio contrato de la app y coincidente con la versión de la app que lo escribió. TypeScript lo importa; JavaScript lo usa desde JSDoc:

```typescript
import type { PackageContext } from "./types/aigd";

export async function activate(ctx: PackageContext): Promise<void> {
  ctx.subscriptions.push(ctx.aigd.commands.registerCommand("acme.level-tools.hello", () => "hi"));
}

export function deactivate(): void {}
```

```javascript
/** @param {import("./types/aigd").PackageContext} ctx */
exports.activate = function activate(ctx) { /* … */ };
```

Un `gamedev pkg init` más reciente en una carpeta temporal te da una copia más nueva de los tipos. Hay un paquete npm de tipos (`@ai-game-dev/package-api`) preparado pero aún sin publicar.

Cada llamada cruza un límite de proceso (tu código se ejecuta en el Extension Host de la app), así que los argumentos y los resultados deben ser valores JSON, y todos los métodos que hablan con la app son asíncronos. Los pocos miembros síncronos (`env`, `project.path`, `settings.get`) leen el estado que la app envió al iniciarse el paquete.

## El contexto

| Miembro | Qué es |
| --- | --- |
| `ctx.aigd` | La API (más abajo) |
| `ctx.package` | Este paquete: `id`, `publisher`, `name`, `version`, `displayName`, `dir`, `manifest` |
| `ctx.subscriptions` | Añade aquí cada `Disposable`; la app los libera cuando el paquete se detiene |
| `ctx.globalState`, `ctx.projectState` | Pequeños almacenes clave-valor para este equipo y para este proyecto en este equipo |
| `ctx.globalStoragePath`, `ctx.projectStoragePath` | Carpetas en las que tu paquete puede escribir |
| `ctx.log` | `debug`, `info`, `warn`, `error`: líneas etiquetadas `pkg:<id>` en el log de la app |
| `ctx.asAbsolutePath(rel)` | Una ruta dentro de la carpeta del paquete |
| `ctx.reportError(err, subject?)` | Registra un error en la lista Errors de la ventana Packages |

## Espacios de nombres

| Espacio de nombres | Qué hace | Estado |
| --- | --- | --- |
| `env` | Host (`desktop` o `cli`), versión de la app, plataforma, `nodeCommand`, `fetch` a través del proxy del sistema, `openExternal`, portapapeles (escritorio) | Estable |
| `commands` | Registra y ejecuta comandos y comandos de barra, define claves de contexto `when` | Estable |
| `capabilities` | Estado, activación y asociación por chat de tus interruptores de Tools | Estable |
| `mcp` | Registra servidores MCP para este proyecto | Estable |
| `agent` | Sirve herramientas de agente en memoria (`registerProvider`) | Estable |
| `gameEngines` | Implementa un motor de juego (`registerEngine`, `host`) | Estable desde la 0.4.0 |
| `settings` | Lee y escribe tus ajustes, observa los cambios | Estable |
| `project` | La ruta del proyecto y `getInfo()` (motor, versión del motor y los proyectos de motor de la carpeta) | Estable |
| `packages` | Otros paquetes y sus exportaciones (`all`, `get`, `getExports`) | Estable |
| `claude` | Añade una carpeta de plugin de Claude Code a los chats de este proyecto (`registerPlugin`) | Estable |
| `editor` | Las herramientas del editor de motor conectado, para los chats a los que está asociado tu proveedor | Estable |
| `account` | El catálogo de capacidades de la cuenta con sesión iniciada (`getSnapshot`) | Estable |
| `media` | Registra un generador de medios local declarado en `contributes.mediaProviders` (`registerProvider`) | Estable |
| `window` | Mensajes, selecciones rápidas, cuadros de entrada, progreso, barra de estado, webviews, vistas de árbol, editores personalizados | Estable, escritorio |
| `tutorials` | Solicita y sigue consejos dentro de la app | Estable, escritorio |
| `sessions` | `list()`, `active()` y los eventos en vivo son estables; las transcripciones, los prompts y la configuración por chat son propuestos | Mixto |
| `storage`, `downloads`, `hardware` | El almacén de blobs de la app, las descargas verificadas y la sonda de hardware | Propuesto |
| `tasks`, `subscriptions`, `work` | Observación de tareas en segundo plano, trabajo de larga duración y retenciones de trabajo | Propuesto |

Los miembros marcados con `@desktop` en `aigd.d.ts` no hacen nada en la CLI: se resuelven a `undefined` o devuelven un objeto inerte, y el host registra una línea. Comprueba `aigd.env.host` cuando tu paquete deba comportarse de forma distinta en la terminal.

## API estable y propuesta

Un miembro **estable** conserva su significado en todas las versiones de la app. Los cambios son solo adiciones; un miembro estable solo se elimina tras al menos dos versiones menores de la app con avisos de deprecación (una línea por paquete y sesión en `gamedev pkg logs`), junto con una subida de la versión más antigua de `engines.aigd` que carga la app.

Un miembro **propuesto** puede cambiar o desaparecer en cualquier versión. Para llamar a uno, declara su propuesta; una llamada sin la declaración falla con un mensaje que nombra la propuesta:

```json
{ "enabledApiProposals": ["forms"] }
```

| Propuesta | Miembros |
| --- | --- |
| `forms` | `window.showForm` |
| `alerts` | `window.showAlert` |
| `sessions` | `sessions.getTranscript`, `sendPrompt`, `create`, `focusComposer` |
| `sessionConfiguration` | configuración de paquete por chat y módulos de Herramientas (`sessions.getConfiguration`, `updateConfiguration`, `registerToolStateProvider`, …) |
| `appFocus` | `window.keepInFront` |
| `storage`, `downloads`, `hardware` | el almacén de blobs, el gestor de descargas, la sonda de hardware |
| `backgroundTasks`, `subscriptions`, `workHolds` | `tasks.*`, `subscriptions.open`, `work.hold` |
| `paidOperations`, `mockJobs` | trabajos de servidor de pago (solo los paquetes de proveedor propios de AI Game Dev) y su simulación de desarrollo |

**Advertencia**

El registro de la comunidad rechaza todo paquete que declare una propuesta. Un paquete que necesite una aún puede compartirse desde GitHub, npm o una carpeta; consulta [Publicar paquetes](https://ai-game.dev/es/docs/wiki/app/publishing-packages#other-sources).

## Comandos y comandos de barra

```typescript
const ID = "acme.level-tools";

ctx.subscriptions.push(
  aigd.commands.registerCommand(`${ID}.count`, async (...args) => {
    const n = await countCollectibles();
    await aigd.window.showInformationMessage(`${n} collectibles in this level`);
    return n;
  }),
  aigd.commands.registerSlashCommand("/collectibles", async (inv) => {
    inv.say("Counting…");                       // a system line in the chat, live
    const n = await countCollectibles(inv.args.trim());
    inv.say(`${n} collectibles.`);
  }),
);

await aigd.commands.setContext(`${ID}.hasLevel`, true);   // usable in when clauses
await aigd.commands.executeCommand("aigd.packages.open", { packageId: ID });
```

Un comando de barra recibe el texto que sigue a su nombre (`inv.args`), el chat en el que se escribió (`inv.sessionId`), `say()` para líneas en vivo y `cancelled`, una promesa que se resuelve cuando el usuario pulsa Esc o Stop. Los comandos de barra funcionan igual en el chat de escritorio y en la CLI. Entre los comandos de la app que tu paquete puede ejecutar están `aigd.packages.open`, `aigd.packages.reload`, `aigd.packages.checkForUpdates`, `aigd.session.focus`, `aigd.settings.open` y `aigd.tutorials.show`.

## Dar herramientas al agente

**Un servidor MCP, declarado.** La forma más sencilla: declara el servidor y una capacidad que lo active por chat. No hace falta código; el servidor es tu propio script iniciado con el Node de la app:

```json
{
  "contributes": {
    "capabilities": [
      { "id": "acme.level-tools", "label": "Level tools", "description": "Counts collectibles in level files.", "mcpServer": "acme--level-tools" }
    ],
    "mcpServers": {
      "acme--level-tools": { "command": "${node}", "args": ["${packageDir}/server.js"] }
    }
  }
}
```

**Un servidor MCP, registrado en tiempo de ejecución.** Para un servidor cuya dirección solo conoces cuando algo ya se ha iniciado (el puerto de una app externa):

```typescript
await aigd.mcp.registerServer("acme--level-tools", { type: "http", url: `http://127.0.0.1:${port}/mcp` });
```

**Herramientas servidas desde tu código.** Un proveedor de agente mantiene las herramientas en tu paquete, sin proceso de servidor. Decláralo con su capacidad y luego regístralo:

```json
{
  "contributes": {
    "capabilities": [{ "id": "acme.helper", "label": "Helper", "description": "Helper tools", "defaultEnabled": true }],
    "agentProviders": [{ "id": "acme.helper.agent", "serverName": "acme--helper", "capabilityId": "acme.helper" }]
  }
}
```

```typescript
ctx.subscriptions.push(await aigd.agent.registerProvider("acme.helper.agent", {
  getTools: () => [{
    name: "status",
    description: "Read the helper's status",
    inputSchema: { type: "object", properties: {}, additionalProperties: false },
  }],
  getInstructions: () => "Use the helper's status tool when working in this project.",
  invokeTool: async (name, args, context) => ({ content: [{ type: "text", text: context.project.path }] }),
}));
```

El esquema de entrada de una herramienta debe tener una raíz de tipo objeto, sin `oneOf`, `anyOf` ni `allOf` en el nivel superior. Los resultados pueden incluir texto e imágenes (`{ type: "image", data, mimeType }`, PNG, JPEG o WebP); una imagen que no pase las comprobaciones de la app se sustituye por una nota, nunca por un error. El plazo predeterminado de las herramientas es de 60 segundos (`executionTimeoutMs`, hasta una hora).

**Una capacidad con estado.** Marca `statusful: true` en la capacidad cuando activarla requiera trabajo (iniciar una app externa). La app entonces muestra tu estado en el interruptor y llama a tu manejador de activación:

```typescript
ctx.subscriptions.push(
  aigd.capabilities.registerStatusProvider("acme.level-tools", async () =>
    (await isRunning()) ? { phase: "connected", detail: "Editor 4.2" } : { phase: "idle" }),
  aigd.capabilities.registerActivationHandler("acme.level-tools", async (req) => {
    req.progress("Starting the level server…");
    try { await start(); return { ok: true }; }
    catch (e) { return { ok: false, failure: { code: "start-failed", text: String(e) } }; }
  }),
);
```

## Ajustes

```typescript
const quality = aigd.settings.get<string>("quality") ?? "draft";
await aigd.settings.update("quality", "final", "project");   // user, project or local
ctx.subscriptions.push(aigd.settings.onDidChange((e) => ctx.log.info(`${e.key} is now ${String(e.value)}`)));
```

Las claves son tuyas (sin el prefijo del paquete) y deben declararse en `contributes.settings`. Cada escritura se valida contra la declaración.

## Mensajes, selectores y progreso

```typescript
const choice = await aigd.window.showWarningMessage("Overwrite the export?", { modal: true }, "Overwrite", "Keep");
const level = await aigd.window.showQuickPick(["forest", "cave", "castle"], { title: "Export which level?" });
const name = await aigd.window.showInputBox({ prompt: "File name", value: "level-1" });

await aigd.window.withProgress({ title: "Exporting", cancellable: true }, async (progress, cancelled) => {
  progress.report({ message: "Meshes", increment: 50 });
  progress.report({ message: "Textures", increment: 50 });
});

const item = aigd.window.createStatusBarItem("acme.level-tools.status", { alignment: "left" });
item.text = "3 levels";
item.command = "acme.level-tools.count";
item.show();
ctx.subscriptions.push(item);
```

En la CLI, los mensajes se imprimen como líneas de sistema; un mensaje modal, un selector rápido o un cuadro de entrada se convierten en un prompt de terminal mientras se ejecuta tu comando de barra. Fuera de un comando de barra, la CLI rechaza los prompts con un `PromptRefusedError` (código `prompt_refused`), así que un paquete que hace preguntas debería hacerlas desde un comando de barra o comprobar `aigd.env.host`.

## Webviews: paneles, vistas laterales y ventanas

Una webview es tu propia página HTML dentro de la app (escritorio). La misma página funciona en un panel, en una pestaña del panel lateral o en su propia ventana:

```typescript
const panel = aigd.window.createWebviewPanel("acme.level-tools.map", "Level map");
const script = panel.webview.asWebviewUri(ctx.asAbsolutePath("dist/map.js"));
panel.webview.html = `<!doctype html><html><body><canvas id="map"></canvas>
  <script type="module" src="${script}"></script></body></html>`;
panel.webview.onDidReceiveMessage((msg) => ctx.log.info(`page says ${JSON.stringify(msg)}`));
await panel.webview.postMessage({ type: "level", tiles });
```

```javascript
// dist/map.js, inside the page
const api = acquireAigdApi();
api.postMessage({ type: "ready" });
window.addEventListener("message", (e) => draw(e.data));
api.setState({ zoom: 2 });             // restored with the pane after a relaunch
```

- **Pestaña del panel lateral:** declara `{ "id": "acme.level-tools.side", "name": "Levels", "type": "webview" }` en `contributes.views.right` y registra `aigd.window.registerWebviewViewProvider("acme.level-tools.side", { resolveWebviewView(view) { view.webview.html = page(); } })`. `"titleBar": "hidden"` permite que tu página dibuje su propia cabecera.
- **Ventana propia:** `aigd.window.createWebviewWindow(viewType, title)` abre una ventana nativa redimensionable, una por tipo de vista y proyecto. Su página se ejecuta bajo una política de seguridad de contenido estricta: solo los archivos del propio paquete, sin red, sin `eval`.
- **Tema:** la página recibe `<html data-theme="light|dark">` y la paleta de la app como variables CSS `--aigd-*` (`--aigd-bg`, `--aigd-surface`, `--aigd-text`, `--aigd-primary`, …), que se reenvían en cada cambio de tema.
- **API de página:** `acquireAigdApi()` ofrece `postMessage`, `getState`, `setState`, `executeCommand` (tus propios comandos y los de la app), `getContext()` y `close()`.

## Vistas de árbol

```typescript
const tree = aigd.window.createTreeView("acme.level-tools.levels", {
  treeDataProvider: {
    getChildren: async (parent) => parent
      ? listObjects(parent.id).map((o) => ({ id: o.id, label: o.name, icon: "$(box)" }))
      : listLevels().map((l) => ({ id: l.id, label: l.name, collapsible: "collapsed", contextValue: "level" })),
  },
});
tree.message = "3 levels";
ctx.subscriptions.push(tree);
```

La vista se declara con `"type": "tree"` en `contributes.views`. `contextValue` se convierte en `viewItem` para los menús `view/item/context`; los elementos pueden llevar casillas de verificación, insignias y un comando de clic.

## Editores personalizados

```json
{ "contributes": { "customEditors": [{ "viewType": "acme.level-tools.level", "displayName": "Level preview", "selector": [{ "filenamePattern": "*.level.json" }], "priority": "default" }] } }
```

```typescript
ctx.subscriptions.push(aigd.window.registerCustomEditorProvider("acme.level-tools.level", {
  resolveCustomEditor(document, panel) {
    panel.webview.html = renderLevel(fs.readFileSync(document.path, "utf8"));
  },
}));
```

Un editor `default` sustituye la vista previa propia de la app para los archivos coincidentes; un editor `option` aparece en Abrir con. Los documentos son de solo lectura desde el lado de la app: tu paquete escribe los archivos por su cuenta y el panel se recarga cuando el archivo cambia en disco. `aigd.window.openPreview(path)` muestra un archivo del proyecto en la vista previa, igual que un clic en el Explorador.

## Tutoriales

```json
{ "contributes": { "tutorials": [{ "id": "acme.level-tools.intro", "title": "Count collectibles", "anchor": "slashCommand:/collectibles", "markdown": "tutorials/intro.md" }] } }
```

```typescript
ctx.subscriptions.push(aigd.tutorials.request("acme.level-tools.intro"));
```

Un consejo se muestra una vez por usuario, en un momento tranquilo, apuntando a su ancla: `capability:`, `statusBar:`, `view:`, `slashCommand:`, `command:` o `menu:` seguido de un id, `composer`, o `none`. `markdown` con hasta 8 archivos `media`, o una página `webview` para contenido enriquecido. `request(id, { force: true })` lo muestra de nuevo; `isSeen` y `setSeen` leen y establecen el estado de visto.

## Estado almacenado

```typescript
const DATA = 2;
if ((ctx.globalState.dataVersion ?? 0) < DATA) {
  await migrate(ctx.globalState);
  await ctx.globalState.setDataVersion(DATA);
}
await ctx.projectState.update("lastExport", new Date().toISOString());
const last = ctx.projectState.get<string>("lastExport");
```

`globalState` se comparte entre todos los proyectos de este ordenador; `projectState` pertenece a este proyecto en este ordenador. Ambos sobreviven a las actualizaciones y a la desinstalación (volver a añadir el paquete los restaura); **Remove data** en la ventana Packages los elimina. La aplicación nunca migra tus datos: `dataVersion` es tuyo para compararlo y aumentarlo.

## Páginas relacionadas

- [Referencia del manifiesto del paquete](https://ai-game.dev/es/docs/wiki/app/package-manifest) para las declaraciones con las que se emparejan estas llamadas.
- [Ciclo de vida, hosts y permisos](https://ai-game.dev/es/docs/wiki/app/package-lifecycle) para saber cuándo se ejecuta tu código y qué puede hacer.
- [Paquetes de motores de juego](https://ai-game.dev/es/docs/wiki/app/game-engine-packages) para `aigd.gameEngines`.

---

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

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