發佈套件
將套件發佈到 AI Game Dev 社群登錄庫:認領發佈者、上傳、發行說明、beta 通道、棄用、撤回,以及其他來源。
社群登錄庫是使用者依 id 尋找與安裝套件的地方:gamedev pkg add acme.level-tools,或在 Packages 視窗中按 Browse,並具備自動更新與 1 到 5 星評分。任何註冊的 ai-game.dev 帳號都能發佈,套件免費,而且每個版本都會通過自動檢查,不需人工審核。本頁涵蓋完整流程:你的發佈者、首次上傳、發行說明、預先發行通道、棄用、撤回,以及其他分享套件的方式。

認領發佈者
你的發佈者 id 是你所發佈的每個套件 id 的前半段(acme.level-tools 中的 acme)。只需認領一次;先搶先贏:
gamedev login
gamedev pkg publisher claim acme --name "Acme Tools"發佈者 id 為 2 到 40 個小寫字母、數字與單一連字號。AI Game Dev 自家的 id(aigd)、引擎名稱(unity、godot、unreal、brutal、bevy、threejs)、商標,以及 un1ty 或 unity-tools 這類相似名稱皆為保留。帳號需要已驗證的電子郵件,且最多可持有 3 個發佈者。
認領發佈者的帳號就是它的 owner。擁有者可依電子郵件新增 maintainers;維護者可以上傳、撤回、棄用、編輯發行說明、移動通道以及簽發權杖。只有擁有者能管理成員與信任的發佈者。
發佈版本
在 aigd-package.json 中放入 "publisher": "acme",調高 version,建置,然後:
gamedev pkg publish level-toolsCLI 會打包資料夾(與 gamedev pkg pack 相同的檢查與位元組)、上傳,並等待檢查結果。版本會經歷這些狀態:
| 狀態 | 說明 |
|---|---|
uploaded、checking | 等待中或正在執行自動檢查 |
published | 通過所有檢查;約一分鐘內進入簽署索引 |
rejected | 某項檢查失敗;報告會列出每一項失敗。修正後重新上傳同一版本 |
yanked | 由發佈者撤回:版本範圍會略過它,已安裝的則保留 |
revoked | 由 AI Game Dev 移除(惡意軟體、帳號遭盜用):所有應用程式都會將它停用 |
版本不可變。 已發佈、已撤回或已撤銷的版本號永遠無法再次上傳;只有被拒絕的可以。修正請以新版本發佈。

發行說明
每個版本都可以附上 Markdown 格式的發行說明。使用者會在 Packages 視窗(Versions)以及發佈者面板中依版本看到。上傳時一併提供:
gamedev pkg publish level-tools --notes RELEASE_NOTES.md若沒有 --notes,登錄庫會從你的 CHANGELOG.md(位於套件資料夾中,並隨封存檔一起送出)擷取該版本標題(## 1.2.0、## [1.2.0] 或 ## v1.2.0)到下一個同級或更高級標題之間的段落,上限 20 KB:
# Changelog
## [1.2.0]
- Export levels as glTF.
- Fix the collectible count in nested scenes.發行說明最多為 20 KB 的 Markdown,會像 README 一樣經過清理,並與套件中其他文字一樣接受提示注入檢查。成員之後可在發佈者面板中編輯。簽署索引會攜帶前 4 KB,並附上其餘內容的連結。
通道:latest、beta 與其他
通道(dist-tag)指定使用者依名稱索取時取得的版本:
gamedev pkg add acme.level-tools # the latest channel
gamedev pkg add acme.level-tools@beta # whatever beta points to- 預先發行版本(
1.3.0-beta.1)預設永遠不會被安裝:latest是你未設定時最高的已發佈穩定版本,且永遠不能指向預先發行版本。 - 其他通道由你命名(
beta、next、nightly):小寫、以字母開頭、最多 16 個字元。一個套件最多 5 個通道,包含latest。 - 已撤回或已撤銷的版本無法標記;指向被撤回版本的通道會被移除。
- 以 semver 預先發行版本的形式發佈預先發行版本(
1.3.0-beta.2)。若預先發行版本命名為alpha、beta、rc、next、preview、canary、nightly、dev或experimental,會自動將該通道移到它身上,除非成員手動設定過該通道;任何通道也可在發佈者面板(Channels)中移動。 gamedev pkg add acme.level-tools@beta會把該通道寫進packages.json,內容為{ "source": "^1.3.0-beta.1", "channel": "beta" }。只要通道版本比最新的穩定版還新,測試者就會取得該通道版本;等穩定版推出後,他們下一次更新就會轉移到穩定版。
棄用套件或版本
棄用會在不得破壞任何已安裝內容的前提下,提示使用者改用其他版本:
- 套件: 一則訊息(最多 300 個字元),以及可選的替代套件 id。應用程式與 CLI 會顯示該訊息與替代套件;已安裝的副本仍可繼續運作,該套件也仍然可以加入。
- 版本: 一則訊息,例如「匯出巢狀場景時會遺失資料,請更新至 1.2.1」。
選擇版本時,應用程式會偏好未被棄用的版本。兩種棄用都可復原,並會記錄在 registry 的稽核記錄中。請在發佈者面板中設定。
撤回與撤銷
撤回你不小心發佈的版本:此後版本範圍會略過它,但已經安裝它的使用者仍會保留。撤回是可復原的,發佈者權杖也可以執行撤回。撤銷則是 AI Game Dev 針對惡意或被竊取版本的緊急關閉機制:它會從索引中移除,而每個已安裝該版本的應用程式會在下一次讀取索引時將它關閉。
從 CI 發佈
有兩種方式,皆說明於受信任發佈:
- 受信任發佈(建議): 由 GitHub Actions 或 GitLab CI 證明是哪個儲存庫與工作流程在發佈;不需要在任何地方儲存密鑰,且每個版本都會記錄其來源。該頁也說明了可直接使用的 GitHub Action 與 GitLab CI 範本:IvanMurzak/gamedev-publish-action。
- 發佈者權杖:
gamedev pkg publisher token create acme --label ci --days 90,儲存為 CI 密鑰並以AI_GAME_DEV_PUBLISHER_TOKEN傳遞。
發佈者面板
首次上傳後,發佈者需要管理的一切都在 ai-game.dev/publisher 的發佈者面板中,供已登入的擁有者與維護者使用:你的發佈者與套件、每個版本及其狀態與檢查報告、發行說明、通道、棄用與撤回、成員與角色、發佈者權杖,以及附有可複製工作流程片段的受信任發佈者。請參閱 Registry 規則與檢查。
其他來源:GitHub、npm 與資料夾
registry 並不是分享套件的唯一方式。這些來源在安裝時不會經過 registry 的檢查,因此請自行執行 gamedev pkg validate;而要分享使用 proposed API 的套件,也只能靠這些來源:
gamedev pkg add github:acme/level-tools # the default branch: moves with each push
gamedev pkg add github:acme/level-tools@v1.2.0 # a tag: pinned, never auto-updated
gamedev pkg add npm:acme-level-tools@^1.2.0 # an npm package and range
gamedev pkg add file:../level-tools # a folder- GitHub: 若使用標籤,應用程式會下載名稱以
.aigd.tgz結尾的 release asset(請附上gamedev pkg pack產生的檔案);否則會取得該 commit 的儲存庫,因此aigd-package.json必須位於根目錄,且dist/必須已提交。 - npm: 對套件資料夾執行
npm publish。npm 封存檔必須包含aigd-package.json與dist/;也請在package.json中加入"engines": { "aigd": "<range>" },這樣應用程式就能略過無法執行的版本,而不必先下載它們。 - 團隊: 在 Project 層級加入套件,讓它提交到
.ai-game-dev/packages.json,每位隊友都會取得相同版本,並由專案的鎖定檔固定。
相關頁面
- 受信任發佈:不需儲存密鑰的 CI。
- Registry 規則與檢查:了解檢查會拒絕哪些內容。
- 套件 CLI 參考:了解每個
publish選項。