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

API de paquetes

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.

Actualizado el 19 de noviembre de 2026 Ver como Markdown

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:

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 {}
/** @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

MiembroQué es
ctx.aigdLa API (más abajo)
ctx.packageEste paquete: id, publisher, name, version, displayName, dir, manifest
ctx.subscriptionsAñade aquí cada Disposable; la app los libera cuando el paquete se detiene
ctx.globalState, ctx.projectStatePequeños almacenes clave-valor para este equipo y para este proyecto en este equipo
ctx.globalStoragePath, ctx.projectStoragePathCarpetas en las que tu paquete puede escribir
ctx.logdebug, 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 nombresQué haceEstado
envHost (desktop o cli), versión de la app, plataforma, nodeCommand, fetch a través del proxy del sistema, openExternal, portapapeles (escritorio)Estable
commandsRegistra y ejecuta comandos y comandos de barra, define claves de contexto whenEstable
capabilitiesEstado, activación y asociación por chat de tus interruptores de ToolsEstable
mcpRegistra servidores MCP para este proyectoEstable
agentSirve herramientas de agente en memoria (registerProvider)Estable
gameEnginesImplementa un motor de juego (registerEngine, host)Estable desde la 0.4.0
settingsLee y escribe tus ajustes, observa los cambiosEstable
projectLa ruta del proyecto y getInfo() (motor, versión del motor y los proyectos de motor de la carpeta)Estable
packagesOtros paquetes y sus exportaciones (all, get, getExports)Estable
claudeAñade una carpeta de plugin de Claude Code a los chats de este proyecto (registerPlugin)Estable
editorLas herramientas del editor de motor conectado, para los chats a los que está asociado tu proveedorEstable
accountEl catálogo de capacidades de la cuenta con sesión iniciada (getSnapshot)Estable
mediaRegistra un generador de medios local declarado en contributes.mediaProviders (registerProvider)Estable
windowMensajes, selecciones rápidas, cuadros de entrada, progreso, barra de estado, webviews, vistas de árbol, editores personalizadosEstable, escritorio
tutorialsSolicita y sigue consejos dentro de la appEstable, escritorio
sessionslist(), active() y los eventos en vivo son estables; las transcripciones, los prompts y la configuración por chat son propuestosMixto
storage, downloads, hardwareEl almacén de blobs de la app, las descargas verificadas y la sonda de hardwarePropuesto
tasks, subscriptions, workObservación de tareas en segundo plano, trabajo de larga duración y retenciones de trabajoPropuesto

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:

{ "enabledApiProposals": ["forms"] }
PropuestaMiembros
formswindow.showForm
alertswindow.showAlert
sessionssessions.getTranscript, sendPrompt, create, focusComposer
sessionConfigurationconfiguración de paquete por chat y módulos de Herramientas (sessions.getConfiguration, updateConfiguration, registerToolStateProvider, …)
appFocuswindow.keepInFront
storage, downloads, hardwareel almacén de blobs, el gestor de descargas, la sonda de hardware
backgroundTasks, subscriptions, workHoldstasks.*, subscriptions.open, work.hold
paidOperations, mockJobstrabajos de servidor de pago (solo los paquetes de proveedor propios de AI Game Dev) y su simulación de desarrollo

Comandos y comandos de barra

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:

{
  "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):

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:

{
  "contributes": {
    "capabilities": [{ "id": "acme.helper", "label": "Helper", "description": "Helper tools", "defaultEnabled": true }],
    "agentProviders": [{ "id": "acme.helper.agent", "serverName": "acme--helper", "capabilityId": "acme.helper" }]
  }
}
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:

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

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

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:

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

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

{ "contributes": { "customEditors": [{ "viewType": "acme.level-tools.level", "displayName": "Level preview", "selector": [{ "filenamePattern": "*.level.json" }], "priority": "default" }] } }
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

{ "contributes": { "tutorials": [{ "id": "acme.level-tools.intro", "title": "Count collectibles", "anchor": "slashCommand:/collectibles", "markdown": "tutorials/intro.md" }] } }
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

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.