パッケージマニフェストリファレンス
aigd-package.json の全フィールドを解説します。id とバージョン、engines.aigd、アクティベーションイベント、依存関係、そして各コントリビューションポイントの形式とルールを網羅します。
aigd-package.json は AI Game Dev パッケージのマニフェストです。id、バージョン、対応するアプリのバージョン、そしてパッケージが提供するすべての内容が含まれます。アプリはパッケージのコードを一切実行せずにこれを読み取るため、パッケージがアクティブになる前に、すべてのメニュー項目、スラッシュコマンド、Tools スイッチ、ビューが表示されます。このページでは、すべてのフィールドとコントリビューションポイントをそのルールとともに一覧します。gamedev pkg init で作成した新しいパッケージには、有効なマニフェストと、エディタでの補完用の JSON Schema ($schema で指定) がすでに含まれています。
トップレベルのフィールド
| フィールド | 必須 | 内容 |
|---|---|---|
publisher | はい | パブリッシャー ID: 2〜40 文字、先頭は英字、以降は小文字英字・数字・単一のハイフンのみで、ドットは使用不可 |
name | はい | パッケージ名: 2〜64 文字、小文字、先頭は英字 |
version | はい | セマンティックバージョニング MAJOR.MINOR.PATCH (1.3.0-beta.2 のようなプレリリース接尾辞も可) |
engines.aigd | はい | パッケージが必要とする最も古い AI Game Dev バージョン (例: ">=0.18.0") |
displayName、description | いいえ | Packages ウィンドウとカタログに表示される (displayName は最大 60 文字、description は最大 400 文字) |
icon、avatarText | いいえ | パッケージからの相対パスの画像、またはアバターとして描画される最大 4 文字 |
license | いいえ | SPDX ID (MIT、Apache-2.0) または SEE LICENSE IN <file> |
homepage、repository、keywords | いいえ | リンクと最大 20 個のキーワード |
main | いいえ | activate をエクスポートするコードのエントリ (CommonJS または ESM)。これがない場合、パッケージはコントリビューションのみとなる |
activationEvents | いいえ | コードを起動する追加イベント (後述) |
hosts | いいえ | ["desktop"]、["cli"]、または両方 (デフォルト)。デスクトップ専用パッケージは CLI ではスキップされる |
dependencies | いいえ | 他のパッケージ、{ "<publisher.name>": "<range>" } |
claudePlugins、claudeMarketplaces | いいえ | パッケージが必要とする Claude Code プラグインと、そのマーケットプレイスの入手先 |
enabledApiProposals | いいえ | パッケージが使用する提案中の API。レジストリはここへのエントリを一切受け付けない |
dataVersion | いいえ | コードが保存するデータのバージョン (情報用) |
contributes | いいえ | パッケージが追加するすべてのもの (後述) |
パッケージ ID は publisher.name です (例: acme.level-tools)。これはパッケージがインストールされるキーと一致していなければならず、一致しない場合は何も実行されません (id-mismatch)。パブリッシャー aigd は AI Game Dev のものであり、エンジン名 unity、godot、unreal、brutal、bevy、threejs は予約されています。
アプリのバージョン: engines.aigd
engines.aigd は下限を示します (例: ">=0.18.0")。これより古いアプリはパッケージを拒否し、必要なバージョンを表示します。アプリのベータ版は、それがプレビューするリリースとして扱われます: 0.32.0-beta.1 は ">=0.32.0" を満たします。アプリがなお読み込む最も古い下限は 0.18.0 です。ご自身がテストした最も古いアプリに設定してください。ゲームエンジンのパッケージには ">=0.32.0" が必要です。
インストールは id とバージョンでキャッシュされます。公開する変更には必ずより高い version が必要です。
パッケージが所有する ID
パッケージが提供するものはすべて自身の ID の内側で命名されるため、2 つのパッケージが衝突することはありません:
- コマンド、パネル、ビュー、ビューコンテナ、サブメニュー、ステータスバー項目、チュートリアル、カスタムエディタ:
<package id>.<local>(例:acme.level-tools.export)。 - ケイパビリティ: パッケージ ID そのもの、または
<package id>.<local>。ケイパビリティ ID はチャットごとに保存されるため、名前を変更しないでください。 - MCP サーバー名:
<publisher>--<name>または<publisher>--<name>-<suffix>、最大 96 文字:acme.level-toolsはacme--level-toolsとacme--level-tools-previewを所有します。モデルはすべてのツール名の中でこの名前を見るため、ドットの代わりに--が使われています。修飾のない名前はエラーです。 aigd.commands.setContextで設定するコンテキストキー:<package id>.<key>。
gamedev pkg validate は、あなたのものではないすべての ID をそのフィールドとともに指摘します。
コントリビューションポイント
| ポイント | 形式 | 備考 |
|---|---|---|
commands | {command, title, shortTitle?, category?, icon?, palette?, hosts?, enablement?} | パレットのエントリ。enablement は when 句 |
slashCommands | {name, description, argumentHint?, hosts?} | 入力どおりの name (例: /export)。名前が衝突した場合は組み込みコマンドが優先され、次に id 順で最初のパッケージが優先される |
capabilities | {id, label, description, defaultEnabled?, mcpServer?, gatesClaudePlugin?, statusful?, hidden?, icon?} | チャットの Tools 行にあるスイッチ。mcpServer はそれがオンにするサーバーを指定する |
mcpServers | { "<server name>": {command, args?, env?} or {type: "http" or "sse", url, headers?} } | Stdio サーバーは ${node}、${packageDir}、${projectDir}、${globalStorage} を使用できる |
agentProviders | {id, serverName, capabilityId, sessionToolViewId?} | コードが aigd.agent.registerProvider を通じてメモリ上で提供するツール |
settings | { "<key>": {type, default?, description, enum?, scope?, …} } | 型は string、number、boolean、string[]、path |
menus | { "<menu id>": [{command or submenu, group?, when?, alt?}] } | 固定のメニュー ID(下記) |
submenus | {id, label, icon?} | サブメニュー ID はメニューのキーにもなる |
keybindings | {command, key, mac?, win?, linux?, when?, args?} | デスクトップのみ。mac を指定しない限り、ctrl は macOS では Cmd を意味する |
statusBar | {id, text, tooltip?, command?, alignment?, priority?, when?} | デスクトップ |
panels | {viewType, title, icon?} | コードが開く Webview パネル |
viewsContainers | {left?: [{id, title, icon}], right?: [...]} | 新しいサイドパネルのタブ |
views | { "left" or "right" or "<container id>": [{id, name, type: "tree" or "webview", icon?, when?, welcome?, titleBar?}] } | サイドパネル内のツリービューと Webview ビュー |
customEditors | {viewType, displayName, selector: [{filenamePattern}], priority?} | priority が default(既定値)の場合、一致するファイルの組み込みプレビューを置き換える。option の場合は「Open With」に表示される |
tutorials | {id, title, anchor, markdown? and media? or webview?, size?, trigger?, when?, after?, priority?} | アプリ内の短いヒント。ユーザーごとに 1 回だけ表示される |
claudePlugin | パッケージからの相対フォルダ | パッケージ内に同梱される Claude Code プラグイン |
mediaProviders | {id, capabilityId, execution: "local"} | コードが aigd.media.registerProvider で登録するローカルメディアジェネレーター |
sessionTools | {id, capabilityId, title, modules?} | チャットのツールにおけるケイパビリティの設定画面(コードが解決する Webview ビュー) |
gameEngines | ゲームエンジンパッケージを参照 | 1 パッケージにつき 1 エンジン |
runtimes、imageModels、videoModels、model3dModels、mediaModels | 宣言のみ、コード不要 | ローカル生成ランタイムとそれが実行するモデル、およびクラウドモデルファミリー |
アイコンは $(name)(アプリのアイコンセットのアイコン)か、パッケージ内のパスです。composerButtons は今も読み込まれますが非推奨です。composer/toolbar のメニュー項目を使用してください。
メニュー ID
| メニュー ID | コマンドが受け取る引数 | when 用のコンテキストキー |
|---|---|---|
commandPalette | なし | — |
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} | リソースのキー、activeCustomEditor、previewKind |
preview/<kind>/toolbar | {path} | リソースのキー、previewKind |
view/title | {viewId} | view |
view/item/context | {viewId, itemId} | view、viewItem |
packages/item/context | {packageId} | packageId、packageLevel、packageState |
statusBar/item/context | {itemId} | statusBarItem |
グループ navigation はインラインのツールバーボタンになります。それ以外のグループは「…」オーバーフローメニューに入り、group@order でグループ内の並び順を指定できます。プレビューの種類は code diff image svg texture audio video model font markdown table binary です。不明なメニュー ID はエラーではなく警告になるため、新しいバージョンのアプリ向けに書かれたパッケージも読み込まれます。
when 句
メニュー、enablement、キーバインド、ビュー、ステータスバー項目、チュートリアルは、VS Code 構文の when 句を受け付けます: ! && || == != < <= > >= =~ /regex/ in と not in、および括弧。グローバルキーには host、platform、projectOpen、projectEngine、activePane、activeFilePath、activeFileExtname、sessionActive、sessionRunning、attachedCapabilities、activePackages、installedPackages、workspaceEngines があり、開いているフォルダ内のエンジンごとに workspaceHasEngine:<engine> があります。設定は config.<package id>.<key> として、独自のキーは <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" }]
}
}
}解析できない句はマニフェストエラーとなり、そのコントリビューションは破棄されます。
設定
{
"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"(既定値)はユーザーレベルに書き込みます。scope: "project"はプロジェクトレベルに書き込み、これはコミットされてチームと共有されます。- 値はローカルレベル、プロジェクト、ユーザーレベルの順に読み取られ、最後にマニフェストの既定値が使われます。
type: "path"は絶対パスを受け取ります。directories: falseはファイルを要求し、mustBeWritableとshowFreeSpaceはフォームにチェックを追加します。userLevelOnly: true(scope: "machine"と併用)はキーをマシン全体に適用し、プロジェクトとローカルの値は無視されます。enumは固定の選択肢を提供します。options: { "provider": "<id>" }は実行時にプロバイダーから選択肢を取得します(現時点ではアプリ自身のプロバイダーのみ)。
アクティベーションイベント
ほとんどのパッケージでは不要です。提供するコマンド、スラッシュコマンド、ビュー、カスタムエディター、ステータス付きケイパビリティ、webview チュートリアル、ゲームエンジンはそれぞれコードを自動的に起動します。別のタイミングでコードを実行する必要がある場合は、activationEvents に追加のイベントを列挙します:
| イベント | タイミング |
|---|---|
onStartupFinished | アプリの最初のレンダリング後、または CLI の最初のプロンプト時(main を持ち、他のイベントがないパッケージのデフォルト) |
onCommand:<id>, onSlashCommand:/<name> | コマンドの実行前 |
onView:<viewId>, onCustomEditor:<viewType> | ビューが最初に表示されたとき、一致するファイルが開かれたとき |
onFileType:.<ext> | その拡張子のファイルが任意のペインで開かれたとき |
onCapability:<id>, onAgentProvider:<id> | ケイパビリティまたはプロバイダーが最初に必要になったとき |
onTutorial:<id>, onWebviewPanel:<viewType> | webview チュートリアルが表示される前、保存されたパネルが復元されたとき |
onGameEngine:<id> | 開いているフォルダーにそのエンジンのプロジェクトがあるとき |
* | ホストの起動時(非推奨) |
依存関係と Claude プラグイン
{
"dependencies": { "acme.core-3d": "^1.0.0" },
"claudePlugins": { "level-design@acme-marketplace": "*" },
"claudeMarketplaces": { "acme-marketplace": { "source": "github", "repo": "acme/claude-plugins" } }
}- プロジェクトは各パッケージにつき1つのバージョンだけを実行します。すべての範囲を満たす中で最も高いバージョンがアプリに受け入れられます。依存関係は、それに依存するパッケージより先にアクティベートされます。競合、循環、除外された依存関係は、それを必要とするパッケージ上に表示されます。
- Claude プラグインはプロジェクトごとにアプリ独自のキャッシュにインストールされ、プロジェクトのロックファイル内のコミットに固定されて、そのプロジェクトのチャットに渡されます。あなた自身の
~/.claudeには一切触れません。マーケットプレイスのソースはgithub、git、git-subdir、urlです。
関連ページ
- Package API では、これらのコントリビューションの背後にあるコードについて説明しています。
- Lifecycle, hosts and permissions では、アクティベーション、状態、バージョニングについて説明しています。
- Registry rules and checks では、レジストリが受け入れるものについて説明しています。