套件資訊清單參考
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 | 否 | 顯示於套件視窗與目錄中(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"。比它更舊的應用程式會拒絕此套件,並說明它需要哪個版本。應用程式的 beta 版視同它所預覽的正式版本:0.32.0-beta.1 可滿足 ">=0.32.0"。應用程式仍可載入的最低門檻是 0.18.0;請把你測試過的最舊應用程式版本設為你的值。遊戲引擎套件需要 ">=0.32.0"。
安裝會依 id 與版本快取:你發佈的每次變更都需要更高的 version。
套件擁有的 id
套件貢獻的所有項目都命名於自己的 id 之內,因此兩個套件永遠不會衝突:
- 命令、面板、檢視、檢視容器、子選單、狀態列項目、教學與自訂編輯器:
<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 則會出現在「開啟方式」中 |
tutorials | {id, title, anchor, markdown? and media? or webview?, size?, trigger?, when?, after?, priority?} | 應用程式內的簡短提示,每位使用者只顯示一次 |
claudePlugin | 相對於套件的資料夾 | 隨套件一起提供的 Claude Code 外掛 |
mediaProviders | {id, capabilityId, execution: "local"} | 你的程式碼透過 aigd.media.registerProvider 註冊的本機媒體產生器 |
sessionTools | {id, capabilityId, title, modules?} | 聊天室「工具」中某項能力的設定介面(由你的程式碼解析的 webview 檢視) |
gameEngines | 請參閱 遊戲引擎套件 | 每個套件一個引擎 |
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" }]
}
}
}無法解析的子句屬於 manifest 錯誤,並會捨棄該項貢獻。
設定
{
"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"會寫入專案層級,該層級會提交並與團隊共用。- 值的讀取順序為本機層級、專案、使用者層級,最後才是 manifest 預設值。
type: "path"接受絕對路徑;directories: false表示要求選擇檔案,mustBeWritable與showFreeSpace會為表單加上檢查。userLevelOnly: true(搭配scope: "machine")會讓該鍵適用於整台機器:專案與本機的值都會被忽略。enum提供固定選項;options: { "provider": "<id>" }則在執行時向 provider 取得(目前僅限應用程式自家的 provider)。
啟用事件
大多數套件都不需要:每個提供的命令、斜線命令、檢視、自訂編輯器、具狀態的能力、webview 教學和遊戲引擎都會自行啟動程式碼。當程式碼必須在其他時機執行時,請在 activationEvents 中列出額外事件:
| 事件 | 時機 |
|---|---|
onStartupFinished | 應用程式首次渲染後,或 CLI 首次提示後(具有 main 且沒有其他事件的套件之預設值) |
onCommand:<id>, onSlashCommand:/<name> | 命令執行前 |
onView:<viewId>, onCustomEditor:<viewType> | 檢視首次顯示時,或開啟符合的檔案時 |
onFileType:.<ext> | 該副檔名的檔案在任何窗格中開啟時 |
onCapability:<id>, onAgentProvider:<id> | 首次需要某項能力或 provider 時 |
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" } }
}- 一個專案對每個套件只執行一個版本:在應用程式接受的前提下,滿足所有版本範圍的最高版本。相依套件會在其依賴者之前啟用。衝突、循環相依或被排除的相依性會顯示在需要它的套件上。
- Claude 外掛會依專案安裝到應用程式自家的快取中,鎖定在專案鎖定檔中的某個 commit,並提供給該專案的對話使用。它們絕不會動到你自己的
~/.claude。市集來源有github、git、git-subdir和url。
相關頁面
- 套件 API 說明這些貢獻背後的程式碼。
- 生命週期、主機與權限 說明啟用、狀態與版本控管。
- 註冊表規則與檢查 說明註冊表接受哪些內容。