本頁面由英文機器翻譯而成。閱讀英文原文。

套件資訊清單參考

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否顯示於套件視窗與目錄中(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指令會收到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。