# Package manifest reference

Every field of aigd-package.json: ids and versions, engines.aigd, activation events, dependencies, and each contribution point with its shape and rules.

_Last updated: 2026-11-19_

`aigd-package.json` is the manifest of an AI Game Dev package: its id, its version, the app versions it works with and everything it contributes. The app reads it without running any package code, so every menu item, slash command, Tools switch and view is visible before the package activates. This page lists every field and contribution point with its rules. A new package from `gamedev pkg init` already has a valid manifest and its JSON Schema (named by `$schema`) for completion in your editor.

## Top-level fields

| Field | Required | What it is |
| --- | --- | --- |
| `publisher` | Yes | Your publisher id: 2 to 40 characters, starting with a letter, then lowercase letters, digits and single hyphens, no dots |
| `name` | Yes | The package name: 2 to 64 characters, lowercase, starting with a letter |
| `version` | Yes | Semver `MAJOR.MINOR.PATCH` (a prerelease suffix such as `1.3.0-beta.2` is allowed) |
| `engines.aigd` | Yes | The oldest AI Game Dev version the package needs, for example `">=0.18.0"` |
| `displayName`, `description` | No | Shown in the Packages window and the catalog (`displayName` up to 60 characters, `description` up to 400) |
| `icon`, `avatarText` | No | A package-relative image, or up to 4 characters drawn as the avatar |
| `license` | No | An SPDX id (`MIT`, `Apache-2.0`) or `SEE LICENSE IN <file>` |
| `homepage`, `repository`, `keywords` | No | Links and up to 20 keywords |
| `main` | No | The code entry (CommonJS or ESM) that exports `activate`; without it the package is contributions-only |
| `activationEvents` | No | Extra events that start the code (below) |
| `hosts` | No | `["desktop"]`, `["cli"]` or both (the default); a desktop-only package is skipped by the CLI |
| `dependencies` | No | Other packages, `{ "<publisher.name>": "<range>" }` |
| `claudePlugins`, `claudeMarketplaces` | No | Claude Code plugins the package needs, and where to find their marketplaces |
| `enabledApiProposals` | No | Proposed API the package uses; the registry refuses any entry here |
| `dataVersion` | No | The version of the data your code stores (informative) |
| `contributes` | No | Everything the package adds (below) |

The package id is `publisher.name`: `acme.level-tools`. It must equal the key the package is installed under, or nothing runs (`id-mismatch`). The publisher `aigd` belongs to AI Game Dev, and the engine names `unity`, `godot`, `unreal`, `brutal`, `bevy` and `threejs` are reserved.

## The app version: engines.aigd

`engines.aigd` is a minimum, such as `">=0.18.0"`. An app older than that refuses the package and says which version it needs. A beta of the app counts as the release it previews: `0.32.0-beta.1` satisfies `">=0.32.0"`. The oldest floor the app still loads is `0.18.0`; set yours to the oldest app you tested with. A game engine package needs `">=0.32.0"`.

Installs are cached by id and version: every change you publish needs a higher `version`.

## Ids your package owns

Everything a package contributes is named inside its own id, so two packages never collide:

- Commands, panels, views, view containers, submenus, status bar items, tutorials and custom editors: `<package id>.<local>`, for example `acme.level-tools.export`.
- Capabilities: the package id itself or `<package id>.<local>`. A capability id is stored per chat, so never rename one.
- MCP server names: `<publisher>--<name>` or `<publisher>--<name>-<suffix>`, at most 96 characters: `acme.level-tools` owns `acme--level-tools` and `acme--level-tools-preview`. The model sees this name in every tool name, which is why it uses `--` instead of a dot. An unqualified name is an error.
- Context keys you set with `aigd.commands.setContext`: `<package id>.<key>`.

`gamedev pkg validate` names every id that is not yours, with its field.

## Contribution points

| Point | Shape | Notes |
| --- | --- | --- |
| `commands` | `{command, title, shortTitle?, category?, icon?, palette?, hosts?, enablement?}` | Palette entries; `enablement` is a `when` clause |
| `slashCommands` | `{name, description, argumentHint?, hosts?}` | `name` as typed, `/export`; a built-in command wins a name clash, then the first package by id |
| `capabilities` | `{id, label, description, defaultEnabled?, mcpServer?, gatesClaudePlugin?, statusful?, hidden?, icon?}` | A switch in a chat's Tools row; `mcpServer` names the server it turns on |
| `mcpServers` | `{ "<server name>": {command, args?, env?} or {type: "http" or "sse", url, headers?} }` | Stdio servers may use `${node}`, `${packageDir}`, `${projectDir}`, `${globalStorage}` |
| `agentProviders` | `{id, serverName, capabilityId, sessionToolViewId?}` | Tools your code serves in memory through `aigd.agent.registerProvider` |
| `settings` | `{ "<key>": {type, default?, description, enum?, scope?, …} }` | Types `string`, `number`, `boolean`, `string[]`, `path` |
| `menus` | `{ "<menu id>": [{command or submenu, group?, when?, alt?}] }` | Fixed menu ids (below) |
| `submenus` | `{id, label, icon?}` | A submenu id is also a menu key |
| `keybindings` | `{command, key, mac?, win?, linux?, when?, args?}` | Desktop; `ctrl` means Cmd on macOS unless `mac` is given |
| `statusBar` | `{id, text, tooltip?, command?, alignment?, priority?, when?}` | Desktop |
| `panels` | `{viewType, title, icon?}` | Webview panels your code opens |
| `viewsContainers` | `{left?: [{id, title, icon}], right?: [...]}` | New side-panel tabs |
| `views` | `{ "left" or "right" or "<container id>": [{id, name, type: "tree" or "webview", icon?, when?, welcome?, titleBar?}] }` | Tree views and webview views in the side panels |
| `customEditors` | `{viewType, displayName, selector: [{filenamePattern}], priority?}` | `priority` `default` (the default) replaces the built-in preview for matching files; `option` appears in Open With |
| `tutorials` | `{id, title, anchor, markdown? and media? or webview?, size?, trigger?, when?, after?, priority?}` | Short in-app tips, shown once per user |
| `claudePlugin` | a package-relative folder | A Claude Code plugin shipped inside the package |
| `mediaProviders` | `{id, capabilityId, execution: "local"}` | A local media generator your code registers with `aigd.media.registerProvider` |
| `sessionTools` | `{id, capabilityId, title, modules?}` | A configuration surface for a capability in a chat's Tools (a webview view your code resolves) |
| `gameEngines` | see [Game engine packages](https://ai-game.dev/docs/wiki/app/game-engine-packages) | One engine per package |
| `runtimes`, `imageModels`, `videoModels`, `model3dModels`, `mediaModels` | declarative, no code | Local generation runtimes and the models they run, and cloud model families |

Icons are either `$(name)`, an icon of the app's icon set, or a path inside the package. `composerButtons` still loads but is deprecated: use a `composer/toolbar` menu item.

### Menu ids

| Menu id | The command receives | Context keys for `when` |
| --- | --- | --- |
| `commandPalette` | nothing | — |
| `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}` | the resource keys, `activeCustomEditor`, `previewKind` |
| `preview/<kind>/toolbar` | `{path}` | the resource keys, `previewKind` |
| `view/title` | `{viewId}` | `view` |
| `view/item/context` | `{viewId, itemId}` | `view`, `viewItem` |
| `packages/item/context` | `{packageId}` | `packageId`, `packageLevel`, `packageState` |
| `statusBar/item/context` | `{itemId}` | `statusBarItem` |

The group `navigation` makes an inline toolbar button; other groups go to the "…" overflow menu, and `group@order` sorts within a group. Preview kinds are `code diff image svg texture audio video model font markdown table binary`. An unknown menu id is a warning, not an error, so a package written for a newer app still loads.

### when clauses

Menus, `enablement`, keybindings, views, status bar items and tutorials take a `when` clause in the VS Code syntax: `! && || == != < <= > >= =~ /regex/ in` and `not in`, with parentheses. Global keys include `host`, `platform`, `projectOpen`, `projectEngine`, `activePane`, `activeFilePath`, `activeFileExtname`, `sessionActive`, `sessionRunning`, `attachedCapabilities`, `activePackages`, `installedPackages`, `workspaceEngines` and one `workspaceHasEngine:<engine>` per engine in the open folder. Your settings are readable as `config.<package id>.<key>` and your own keys as `<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" }]
    }
  }
}
```

An unparsable clause is a manifest error and drops that contribution.

### Settings

```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"` (the default) writes to the user level; `scope: "project"` writes to the project level, which is committed and shared with the team.
- A value is read from the local level, then the project, then the user level, then the manifest default.
- `type: "path"` takes an absolute path; `directories: false` asks for a file, `mustBeWritable` and `showFreeSpace` add checks to the form.
- `userLevelOnly: true` (with `scope: "machine"`) makes a key machine-wide: project and local values are ignored.
- `enum` gives fixed choices; `options: { "provider": "<id>" }` takes them from a provider at run time (the app's own providers only, for now).

### Activation events

Most packages need none: every contributed command, slash command, view, custom editor, statusful capability, webview tutorial and game engine starts the code by itself. List extra events in `activationEvents` when the code must run at another moment:

| Event | When |
| --- | --- |
| `onStartupFinished` | After the app's first render, or the CLI's first prompt (the default for a package with `main` and no other event) |
| `onCommand:<id>`, `onSlashCommand:/<name>` | Before the command runs |
| `onView:<viewId>`, `onCustomEditor:<viewType>` | When the view is first shown, when a matching file opens |
| `onFileType:.<ext>` | When a file with that extension opens in any pane |
| `onCapability:<id>`, `onAgentProvider:<id>` | When a capability or provider is first needed |
| `onTutorial:<id>`, `onWebviewPanel:<viewType>` | Before a webview tutorial shows, when a saved panel is restored |
| `onGameEngine:<id>` | When the open folder holds a project of that engine |
| `*` | At host start (discouraged) |

## Dependencies and Claude plugins

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

- A project runs one version of each package: the highest version that satisfies every range, accepted by the app. Dependencies activate before their dependents. A conflict, a cycle or an excluded dependency is shown on the package that needs it.
- Claude plugins are installed per project into the app's own cache, pinned to a commit in the project's lock file, and handed to that project's chats. They never touch your own `~/.claude`. Marketplace sources are `github`, `git`, `git-subdir` and `url`.

## Related pages

- [Package API](https://ai-game.dev/docs/wiki/app/package-api) for the code behind these contributions.
- [Lifecycle, hosts and permissions](https://ai-game.dev/docs/wiki/app/package-lifecycle) for activation, state and versioning.
- [Registry rules and checks](https://ai-game.dev/docs/wiki/app/package-registry) for what the registry accepts.

---

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