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.

Updated November 19, 2026 View as Markdown

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

FieldRequiredWhat it is
publisherYesYour publisher id: 2 to 40 characters, starting with a letter, then lowercase letters, digits and single hyphens, no dots
nameYesThe package name: 2 to 64 characters, lowercase, starting with a letter
versionYesSemver MAJOR.MINOR.PATCH (a prerelease suffix such as 1.3.0-beta.2 is allowed)
engines.aigdYesThe oldest AI Game Dev version the package needs, for example ">=0.18.0"
displayName, descriptionNoShown in the Packages window and the catalog (displayName up to 60 characters, description up to 400)
icon, avatarTextNoA package-relative image, or up to 4 characters drawn as the avatar
licenseNoAn SPDX id (MIT, Apache-2.0) or SEE LICENSE IN <file>
homepage, repository, keywordsNoLinks and up to 20 keywords
mainNoThe code entry (CommonJS or ESM) that exports activate; without it the package is contributions-only
activationEventsNoExtra events that start the code (below)
hostsNo["desktop"], ["cli"] or both (the default); a desktop-only package is skipped by the CLI
dependenciesNoOther packages, { "<publisher.name>": "<range>" }
claudePlugins, claudeMarketplacesNoClaude Code plugins the package needs, and where to find their marketplaces
enabledApiProposalsNoProposed API the package uses; the registry refuses any entry here
dataVersionNoThe version of the data your code stores (informative)
contributesNoEverything 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

PointShapeNotes
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
claudePlugina package-relative folderA 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)
gameEnginessee Game engine packagesOne engine per package
runtimes, imageModels, videoModels, model3dModels, mediaModelsdeclarative, no codeLocal 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 idThe command receivesContext keys for when
commandPalettenothing—
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: 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:

EventWhen
onStartupFinishedAfter 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 are github, git, git-subdir and url.