# Referencia del manifiesto de paquete — App y CLI de AI Game Dev · AI Game Developer Wiki

Todos los campos de aigd-package.json: ids y versiones, engines.aigd, eventos de activación, dependencias y cada punto de contribución con sus reglas.

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

`aigd-package.json` es el manifiesto de un paquete de AI Game Dev: su id, su versión, las versiones de la app con las que funciona y todo lo que aporta. La app lo lee sin ejecutar código del paquete, así que cada elemento de menú, comando de barra, interruptor de Tools y vista están visibles antes de que el paquete se active. Esta página enumera todos los campos y puntos de contribución con sus reglas. Un paquete nuevo creado con `gamedev pkg init` ya tiene un manifiesto válido y su JSON Schema (indicado por `$schema`) para autocompletar en tu editor.

## Campos de nivel superior

| Campo | Obligatorio | Qué es |
| --- | --- | --- |
| `publisher` | Sí | Tu id de publisher: de 2 a 40 caracteres, empieza por una letra y sigue con letras minúsculas, dígitos y guiones simples, sin puntos |
| `name` | Sí | El nombre del paquete: de 2 a 64 caracteres, en minúsculas y empezando por una letra |
| `version` | Sí | Semver `MAJOR.MINOR.PATCH` (se permite un sufijo de prerelease como `1.3.0-beta.2`) |
| `engines.aigd` | Sí | La versión más antigua de AI Game Dev que necesita el paquete, por ejemplo `">=0.18.0"` |
| `displayName`, `description` | No | Se muestra en la ventana Packages y en el catálogo (`displayName` hasta 60 caracteres, `description` hasta 400) |
| `icon`, `avatarText` | No | Una imagen relativa al paquete, o hasta 4 caracteres dibujados como avatar |
| `license` | No | Un id SPDX (`MIT`, `Apache-2.0`) o `SEE LICENSE IN <file>` |
| `homepage`, `repository`, `keywords` | No | Enlaces y hasta 20 palabras clave |
| `main` | No | La entrada de código (CommonJS o ESM) que exporta `activate`; sin ella, el paquete es solo de contribuciones |
| `activationEvents` | No | Eventos adicionales que inician el código (más abajo) |
| `hosts` | No | `["desktop"]`, `["cli"]` o ambos (por defecto); la CLI omite un paquete solo para escritorio |
| `dependencies` | No | Otros paquetes, `{ "<publisher.name>": "<range>" }` |
| `claudePlugins`, `claudeMarketplaces` | No | Plugins de Claude Code que necesita el paquete, y dónde encontrar sus marketplaces |
| `enabledApiProposals` | No | API propuesta que usa el paquete; el registro rechaza cualquier entrada aquí |
| `dataVersion` | No | La versión de los datos que guarda tu código (informativa) |
| `contributes` | No | Todo lo que añade el paquete (más abajo) |

El id del paquete es `publisher.name`: `acme.level-tools`. Debe coincidir con la clave bajo la que se instala el paquete, o no se ejecuta nada (`id-mismatch`). El publisher `aigd` pertenece a AI Game Dev, y los nombres de motores `unity`, `godot`, `unreal`, `brutal`, `bevy` y `threejs` están reservados.

## La versión de la app: engines.aigd

`engines.aigd` es un mínimo, como `">=0.18.0"`. Una app más antigua que eso rechaza el paquete e indica qué versión necesita. Una beta de la app cuenta como la versión que previsualiza: `0.32.0-beta.1` satisface `">=0.32.0"`. El mínimo más antiguo que la app aún carga es `0.18.0`; pon el tuyo en la app más antigua con la que hayas probado. Un paquete de motor de juego necesita `">=0.32.0"`.

Las instalaciones se cachean por id y versión: cada cambio que publiques necesita una `version` superior.

## Ids que posee tu paquete

Todo lo que aporta un paquete se nombra dentro de su propio id, así que dos paquetes nunca colisionan:

- Comandos, paneles, vistas, contenedores de vistas, submenús, elementos de la barra de estado, tutoriales y editores personalizados: `<package id>.<local>`, por ejemplo `acme.level-tools.export`.
- Capacidades: el propio id del paquete o `<package id>.<local>`. El id de una capacidad se guarda por chat, así que nunca cambies el nombre de una.
- Nombres de servidores MCP: `<publisher>--<name>` o `<publisher>--<name>-<suffix>`, como máximo 96 caracteres: `acme.level-tools` posee `acme--level-tools` y `acme--level-tools-preview`. El modelo ve este nombre en cada nombre de herramienta, por eso usa `--` en lugar de un punto. Un nombre sin cualificar es un error.
- Claves de contexto que defines con `aigd.commands.setContext`: `<package id>.<key>`.

`gamedev pkg validate` indica cada id que no es tuyo, con su campo.

## Puntos de contribución

| Punto | Forma | Notas |
| --- | --- | --- |
| `commands` | `{command, title, shortTitle?, category?, icon?, palette?, hosts?, enablement?}` | Entradas de la paleta; `enablement` es una cláusula `when` |
| `slashCommands` | `{name, description, argumentHint?, hosts?}` | `name` tal como se escribe, `/export`; un comando integrado gana un conflicto de nombres, luego el primer paquete por id |
| `capabilities` | `{id, label, description, defaultEnabled?, mcpServer?, gatesClaudePlugin?, statusful?, hidden?, icon?}` | Un interruptor en la fila Tools de un chat; `mcpServer` nombra el servidor que activa |
| `mcpServers` | `{ "<server name>": {command, args?, env?} or {type: "http" or "sse", url, headers?} }` | Los servidores stdio pueden usar `${node}`, `${packageDir}`, `${projectDir}`, `${globalStorage}` |
| `agentProviders` | `{id, serverName, capabilityId, sessionToolViewId?}` | Herramientas que tu código sirve en memoria mediante `aigd.agent.registerProvider` |
| `settings` | `{ "<key>": {type, default?, description, enum?, scope?, …} }` | Tipos `string`, `number`, `boolean`, `string[]`, `path` |
| `menus` | `{ "<menu id>": [{command or submenu, group?, when?, alt?}] }` | Ids de menú fijos (abajo) |
| `submenus` | `{id, label, icon?}` | Un id de submenú es también una clave de menú |
| `keybindings` | `{command, key, mac?, win?, linux?, when?, args?}` | Escritorio; `ctrl` significa Cmd en macOS a menos que se indique `mac` |
| `statusBar` | `{id, text, tooltip?, command?, alignment?, priority?, when?}` | Escritorio |
| `panels` | `{viewType, title, icon?}` | Paneles webview que abre tu código |
| `viewsContainers` | `{left?: [{id, title, icon}], right?: [...]}` | Nuevas pestañas de panel lateral |
| `views` | `{ "left" or "right" or "<container id>": [{id, name, type: "tree" or "webview", icon?, when?, welcome?, titleBar?}] }` | Vistas de árbol y vistas webview en los paneles laterales |
| `customEditors` | `{viewType, displayName, selector: [{filenamePattern}], priority?}` | `priority` `default` (el valor predeterminado) sustituye la vista previa integrada para los archivos coincidentes; `option` aparece en Open With |
| `tutorials` | `{id, title, anchor, markdown? and media? or webview?, size?, trigger?, when?, after?, priority?}` | Consejos breves dentro de la aplicación, que se muestran una vez por usuario |
| `claudePlugin` | una carpeta relativa al paquete | Un plugin de Claude Code incluido en el paquete |
| `mediaProviders` | `{id, capabilityId, execution: "local"}` | Un generador de medios local que tu código registra con `aigd.media.registerProvider` |
| `sessionTools` | `{id, capabilityId, title, modules?}` | Una superficie de configuración para una capacidad en Tools de un chat (una vista webview que resuelve tu código) |
| `gameEngines` | consulta [Paquetes de motores de juego](https://ai-game.dev/es/docs/wiki/app/game-engine-packages) | Un motor por paquete |
| `runtimes`, `imageModels`, `videoModels`, `model3dModels`, `mediaModels` | declarativo, sin código | Runtimes de generación locales y los modelos que ejecutan, y familias de modelos en la nube |

Los iconos son `$(name)`, un icono del conjunto de iconos de la aplicación, o una ruta dentro del paquete. `composerButtons` todavía se carga, pero está obsoleto: usa un elemento de menú `composer/toolbar`.

### Ids de menú

| Id de menú | El comando recibe | Claves de contexto para `when` |
| --- | --- | --- |
| `commandPalette` | nada | — |
| `composer/toolbar` | `{sessionId}` | `sessionId` |
| `session/title` | `{sessionId}` | `sessionId` |
| `session/tool` | `{sessionId, capabilityId}` | `sessionId`, `capability`, `capabilityPackage`, `sessionToolModule` |
| `session/context` | `{sessionId}` | `sessionId`, `sessionState` |
| `chat/message/context` | `{sessionId, messageId, role}` | `sessionId`, `messageRole` |
| `explorer/context` | `{path, isDirectory}` | `resourcePath`, `resourceFilename`, `resourceExtname`, `resourceDirname`, `resourceRelativePath`, `explorerResourceIsFolder` |
| `editor/title` | `{path, viewType}` | las claves de recurso, `activeCustomEditor`, `previewKind` |
| `preview/<kind>/toolbar` | `{path}` | las claves de recurso, `previewKind` |
| `view/title` | `{viewId}` | `view` |
| `view/item/context` | `{viewId, itemId}` | `view`, `viewItem` |
| `packages/item/context` | `{packageId}` | `packageId`, `packageLevel`, `packageState` |
| `statusBar/item/context` | `{itemId}` | `statusBarItem` |

El grupo `navigation` crea un botón de barra de herramientas en línea; los demás grupos van al menú desbordante «…», y `group@order` ordena dentro de un grupo. Los tipos de vista previa son `code diff image svg texture audio video model font markdown table binary`. Un id de menú desconocido es una advertencia, no un error, así que un paquete escrito para una versión más reciente de la aplicación se sigue cargando.

### Cláusulas when

Los menús, `enablement`, los atajos de teclado, las vistas, los elementos de la barra de estado y los tutoriales aceptan una cláusula `when` con la sintaxis de VS Code: `! && || == != < <= > >= =~ /regex/ in` y `not in`, con paréntesis. Las claves globales incluyen `host`, `platform`, `projectOpen`, `projectEngine`, `activePane`, `activeFilePath`, `activeFileExtname`, `sessionActive`, `sessionRunning`, `attachedCapabilities`, `activePackages`, `installedPackages`, `workspaceEngines` y una `workspaceHasEngine:<engine>` por cada motor de la carpeta abierta. Tus ajustes se pueden leer como `config.<package id>.<key>` y tus propias claves como `<package id>.<key>`.

```json
{
  "contributes": {
    "commands": [{ "command": "acme.level-tools.export", "title": "Export level", "enablement": "projectEngine == 'godot'" }],
    "menus": {
      "explorer/context": [{ "command": "acme.level-tools.export", "when": "resourceExtname == '.tscn'", "group": "navigation" }]
    }
  }
}
```

Una cláusula que no se puede analizar es un error de manifiesto y descarta esa contribución.

### Ajustes

```json
{
  "contributes": {
    "settings": {
      "outputDir": { "type": "path", "description": "Where exports go", "scope": "project", "mustBeWritable": true },
      "quality": { "type": "string", "enum": ["draft", "final"], "default": "draft", "description": "Export quality" },
      "cachePath": { "type": "path", "description": "A cache on this computer", "userLevelOnly": true }
    }
  }
}
```

- `scope: "machine"` (el valor predeterminado) escribe en el nivel de usuario; `scope: "project"` escribe en el nivel de proyecto, que se confirma y se comparte con el equipo.
- Un valor se lee del nivel local, luego del proyecto, luego del nivel de usuario y por último del valor predeterminado del manifiesto.
- `type: "path"` toma una ruta absoluta; `directories: false` pide un archivo, `mustBeWritable` y `showFreeSpace` añaden comprobaciones al formulario.
- `userLevelOnly: true` (con `scope: "machine"`) hace que una clave sea para toda la máquina: se ignoran los valores de proyecto y locales.
- `enum` ofrece opciones fijas; `options: { "provider": "<id>" }` las toma de un proveedor en tiempo de ejecución (solo los proveedores propios de la app, por ahora).

### Eventos de activación

La mayoría de los paquetes no necesita ninguno: cada comando, slash command, vista, editor personalizado, capacidad con estado, tutorial de webview y motor de juego aportado arranca el código por sí mismo. Enumera eventos adicionales en `activationEvents` cuando el código deba ejecutarse en otro momento:

| Evento | Cuándo |
| --- | --- |
| `onStartupFinished` | Tras el primer renderizado de la app, o el primer prompt de la CLI (el valor por defecto para un paquete con `main` y ningún otro evento) |
| `onCommand:<id>`, `onSlashCommand:/<name>` | Antes de que se ejecute el comando |
| `onView:<viewId>`, `onCustomEditor:<viewType>` | Cuando se muestra la vista por primera vez, cuando se abre un archivo coincidente |
| `onFileType:.<ext>` | Cuando se abre un archivo con esa extensión en cualquier panel |
| `onCapability:<id>`, `onAgentProvider:<id>` | Cuando se necesita una capacidad o un proveedor por primera vez |
| `onTutorial:<id>`, `onWebviewPanel:<viewType>` | Antes de que se muestre un tutorial de webview, cuando se restaura un panel guardado |
| `onGameEngine:<id>` | Cuando la carpeta abierta contiene un proyecto de ese motor |
| `*` | Al iniciar el host (desaconsejado) |

## Dependencias y plugins de Claude

```json
{
  "dependencies": { "acme.core-3d": "^1.0.0" },
  "claudePlugins": { "level-design@acme-marketplace": "*" },
  "claudeMarketplaces": { "acme-marketplace": { "source": "github", "repo": "acme/claude-plugins" } }
}
```

- Un proyecto ejecuta una sola versión de cada paquete: la versión más alta que satisface todos los rangos y que la app acepta. Las dependencias se activan antes que sus dependientes. Un conflicto, un ciclo o una dependencia excluida se muestra en el paquete que la necesita.
- Los plugins de Claude se instalan por proyecto en la caché propia de la app, fijados a un commit del archivo de lock del proyecto, y se entregan a los chats de ese proyecto. Nunca tocan tu propio `~/.claude`. Las fuentes del marketplace son `github`, `git`, `git-subdir` y `url`.

## Páginas relacionadas

- [Package API](https://ai-game.dev/es/docs/wiki/app/package-api) para el código que hay detrás de estas contribuciones.
- [Lifecycle, hosts and permissions](https://ai-game.dev/es/docs/wiki/app/package-lifecycle) para la activación, el estado y el versionado.
- [Registry rules and checks](https://ai-game.dev/es/docs/wiki/app/package-registry) para saber qué acepta el registro.

---

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

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