本页由英文机器翻译而成。阅读英文原文。

发布包

将包发布到 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,注册表会从版本标题(## 1.2.0、## [1.2.0] 或 ## v1.2.0)开始,一直取到下一个同级或更高级标题之前的 CHANGELOG.md(位于包文件夹中,随归档一起分发)内容,截断至 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 会把 channel 写入 packages.json,即 { "source": "^1.3.0-beta.1", "channel": "beta" }。测试者在 channel 的版本比最新稳定版更新时获得该版本,并在稳定版发布后于下一次更新时切换到稳定版。

弃用包或版本

弃用会提示用户迁移,同时不破坏任何已安装的内容:

  • 包: 一条消息(最多 300 个字符),以及可选的替代包 id。应用和 CLI 会显示该消息和替代包;已安装的副本继续工作,并且该包仍然可以被添加。
  • 版本: 一条消息,例如“导出嵌套场景时会发生数据丢失,请更新到 1.2.1”。

选择版本时,应用会优先选择未被弃用的版本。两种弃用操作都可撤销,并记录在 registry 的审计日志中。在 publisher 面板中设置。

撤下与吊销

撤下误发布的版本:此后版本范围会跳过它,而已经安装它的用户会保留它。撤下是可撤销的,publisher token 可以执行撤下。吊销是 AI Game Dev 针对恶意或被盗版本的“ kill switch”:它会被移出索引,所有已安装该版本的应用会在下一次读取索引时将其关闭。

从 CI 发布

有两种方式,均展示于 Trusted Publishing:

  • Trusted Publishing(推荐): GitHub Actions 或 GitLab CI 证明是哪个仓库和工作流在发布;无需在任何地方存储密钥,并且每个版本都会记录其来源。那里还介绍了现成的 GitHub Action 和 GitLab CI 模板 IvanMurzak/gamedev-publish-action。
  • publisher token: gamedev pkg publisher token create acme --label ci --days 90,将其存为 CI 密钥,并作为 AI_GAME_DEV_PUBLISHER_TOKEN 传入。

publisher 面板

首次上传后发布者需要管理的一切都在 ai-game.dev/publisher 的 publisher 面板中,面向已登录的 owner 和 maintainer:你的 publisher 和包、每个版本及其状态和检查报告、发布说明、channel、弃用与撤下、成员和角色、publisher token,以及带可复制工作流片段的受信任发布者。参见 Registry 规则与检查。

其他来源:GitHub、npm 和文件夹

registry 并非共享包的唯一方式。这些来源安装时不会经过 registry 的检查,因此请自行运行 gamedev pkg validate;它们也是共享使用提案中 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 资源(附上 gamedev pkg pack 写出的文件);否则使用该提交处的仓库,因此 aigd-package.json 必须位于根目录,且 dist/ 需已提交。
  • npm: 对包文件夹执行 npm publish。npm 归档必须包含 aigd-package.json 和 dist/;还要在 package.json 中添加 "engines": { "aigd": "<range>" },这样应用无需下载就能跳过无法运行的版本。
  • 团队: 在 Project 级别添加包,使其提交到 .ai-game-dev/packages.json,每位队友都能获得相同版本,并由项目的 lock 文件固定。