このページは英語から機械翻訳されています。英語の原文を読む。

パッケージマニフェストリファレンス

aigd-package.json の全フィールドを解説します。id とバージョン、engines.aigd、アクティベーションイベント、依存関係、そして各コントリビューションポイントの形式とルールを網羅します。

2026年11月19日に更新 Markdownで表示

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コマンドが受け取る引数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 では、レジストリが受け入れるものについて説明しています。