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.
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 exampleacme.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-toolsownsacme--level-toolsandacme--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 | 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>.
{
"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
{
"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: falseasks for a file,mustBeWritableandshowFreeSpaceadd checks to the form.userLevelOnly: true(withscope: "machine") makes a key machine-wide: project and local values are ignored.enumgives 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
{
"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 aregithub,git,git-subdirandurl.
Related pages
- Package API for the code behind these contributions.
- Lifecycle, hosts and permissions for activation, state and versioning.
- Registry rules and checks for what the registry accepts.