Publishing packages
Publish a package to the AI Game Dev community registry: claim a publisher, upload, release notes, beta channels, deprecation, yanking, other sources.
The community registry is where users find and install packages by id: gamedev pkg add acme.level-tools, or Browse in the Packages window, with automatic updates and 1 to 5 star ratings. Any registered ai-game.dev account can publish, packages are free, and every version passes automatic checks instead of a manual review. This page covers the whole path: your publisher, the first upload, release notes, pre-release channels, deprecation, yanking, and the other ways to share a package.

Claim a publisher
Your publisher id is the first half of every package id you publish (acme in acme.level-tools). Claim it once; it is first come, first served:
gamedev login
gamedev pkg publisher claim acme --name "Acme Tools"A publisher id is 2 to 40 lowercase letters, digits and single hyphens. AI Game Dev's own id (aigd), engine names (unity, godot, unreal, brutal, bevy, threejs), trademarks and look-alikes such as un1ty or unity-tools are reserved. An account needs a verified email and may hold up to 3 publishers.
The account that claims a publisher is its owner. An owner can add maintainers by email; maintainers may upload, yank, deprecate, edit release notes, move channels and mint tokens. Only an owner manages members and trusted publishers.
Publish a version
Put "publisher": "acme" in aigd-package.json, raise version, build, then:
gamedev pkg publish level-toolsThe CLI packs the folder (the same checks and bytes as gamedev pkg pack), uploads it and waits for the checks. A version moves through these states:
| State | Meaning |
|---|---|
uploaded, checking | Waiting for or running the automatic checks |
published | Passed every check; in the signed index within about a minute |
rejected | A check failed; the report names each failure. Fix it and upload the same version again |
yanked | Withdrawn by its publisher: ranges skip it, existing installs keep it |
revoked | Removed by AI Game Dev (malware, a stolen account): every app turns it off |
Versions are immutable. A published, yanked or revoked version number can never be uploaded again; only a rejected one can. Ship a fix as a new version.

Release notes
Every version can carry release notes in Markdown. Users see them per version in the Packages window (Versions), and in the publisher panel. Give them with the upload:
gamedev pkg publish level-tools --notes RELEASE_NOTES.mdWithout --notes, the registry takes the section of your CHANGELOG.md (in the package folder, shipped in the archive) from the heading of the version (## 1.2.0, ## [1.2.0] or ## v1.2.0) up to the next heading of the same or a higher level, clipped to 20 KB:
# Changelog
## [1.2.0]
- Export levels as glTF.
- Fix the collectible count in nested scenes.Notes are at most 20 KB of Markdown, sanitized like a README and checked for prompt injection like every other text in a package. A member can edit them later in the publisher panel. The signed index carries the first 4 KB, with a link to the rest.
Channels: latest, beta and others
A channel (a dist-tag) names the version users get when they ask for it by name:
gamedev pkg add acme.level-tools # the latest channel
gamedev pkg add acme.level-tools@beta # whatever beta points to- A prerelease (
1.3.0-beta.1) is never installed by default:latestis the highest published stable version unless you set it, and it can never point at a prerelease. - Other channels are yours to name (
beta,next,nightly): lowercase, starting with a letter, up to 16 characters. A package has at most 5 channels,latestincluded. - A yanked or revoked version cannot be tagged; a channel pointing at a version that gets yanked is removed.
- Publish a prerelease as a semver prerelease (
1.3.0-beta.2). A prerelease namedalpha,beta,rc,next,preview,canary,nightly,devorexperimentalmoves that channel to itself automatically, unless a member set the channel by hand; any channel can also be moved in the publisher panel (Channels). gamedev pkg add acme.level-tools@betawrites the channel intopackages.json,{ "source": "^1.3.0-beta.1", "channel": "beta" }. Testers get the channel's version while it is newer than the newest stable one, and move to the stable release once it is out, on their next update.
Deprecate a package or a version
Deprecation tells users to move on without breaking anything that is installed:
- A package: a message (up to 300 characters) and, optionally, the id of a replacement package. The app and the CLI show the message and the replacement; installed copies keep working and the package can still be added.
- A version: a message such as "data loss when exporting nested scenes, update to 1.2.1".
When choosing a version, the app prefers one that is not deprecated. Both kinds are reversible and recorded in the registry's audit log. Set them in the publisher panel.
Yank and revoke
Yank a version you published by mistake: version ranges skip it from then on, and installs that already have it keep it. Yanking is reversible, and a publisher token may yank. Revocation is AI Game Dev's kill switch for a malicious or stolen version: it leaves the index and every app that has it turns it off on its next index read.
Publish from CI
Two ways, both shown in Trusted Publishing:
- Trusted Publishing (recommended): GitHub Actions or GitLab CI proves which repository and workflow is publishing; no secret is stored anywhere and every version records its provenance. A ready GitHub Action and GitLab CI template, IvanMurzak/gamedev-publish-action, are described there.
- A publisher token:
gamedev pkg publisher token create acme --label ci --days 90, stored as a CI secret and passed asAI_GAME_DEV_PUBLISHER_TOKEN.
The publisher panel
Everything a publisher manages after the first upload is in the publisher panel at ai-game.dev/publisher, for signed-in owners and maintainers: your publishers and packages, every version with its state and check report, release notes, channels, deprecation and yanking, members and roles, publisher tokens, and trusted publishers with copyable workflow snippets. See Registry rules and checks.
Other sources: GitHub, npm and folders
The registry is not the only way to share a package. These sources install without the registry's checks, so run gamedev pkg validate yourself, and they are the way to share a package that uses 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: with a tag, the app downloads a release asset whose name ends in
.aigd.tgz(attach the filegamedev pkg packwrote); otherwise the repository at that commit, soaigd-package.jsonmust be at the root anddist/committed. - npm:
npm publishthe package folder. The npm archive must containaigd-package.jsonanddist/; add"engines": { "aigd": "<range>" }topackage.jsontoo, so the app skips versions it cannot run without downloading them. - Teams: add the package at the Project level so it is committed in
.ai-game-dev/packages.jsonand every teammate gets the same version, pinned by the project's lock file.
Related pages
- Trusted Publishing for CI without a stored secret.
- Registry rules and checks for what the checks refuse.
- Package CLI reference for every
publishoption.