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

發佈套件

將套件發佈到 AI Game Dev 社群登錄庫:認領發佈者、上傳、發行說明、beta 通道、棄用、撤回,以及其他來源。

更新於 2026年11月19日 以 Markdown 檢視

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

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-tools

CLI 會打包資料夾(與 gamedev pkg pack 相同的檢查與位元組)、上傳,並等待檢查結果。版本會經歷這些狀態:

狀態說明
uploaded、checking等待中或正在執行自動檢查
published通過所有檢查;約一分鐘內進入簽署索引
rejected某項檢查失敗;報告會列出每一項失敗。修正後重新上傳同一版本
yanked由發佈者撤回:版本範圍會略過它,已安裝的則保留
revoked由 AI Game Dev 移除(惡意軟體、帳號遭盜用):所有應用程式都會將它停用

版本不可變。 已發佈、已撤回或已撤銷的版本號永遠無法再次上傳;只有被拒絕的可以。修正請以新版本發佈。

目錄中某個套件的頁面:名稱、發佈者、版本、安裝按鈕與指令、入門範例預覽、About 面板以及最新版本
目錄中某個社群套件的頁面。使用者只要一鍵或一行指令就能安裝。

發行說明

每個版本都可以附上 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,每位隊友都會取得相同版本,並由專案的鎖定檔固定。