Publishing packages

Publish a package to the AI Game Dev community registry: claim a publisher, upload, release notes, beta channels, deprecation, yanking, other sources.

Updated November 19, 2026 View as Markdown

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.

The package catalog on ai-game.dev: a featured engine package, category filters and rows of official and community packages
The package catalog: official packages and community packages, each with its install command.

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

The 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:

StateMeaning
uploaded, checkingWaiting for or running the automatic checks
publishedPassed every check; in the signed index within about a minute
rejectedA check failed; the report names each failure. Fix it and upload the same version again
yankedWithdrawn by its publisher: ranges skip it, existing installs keep it
revokedRemoved 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.

A package's page in the catalog: name, publisher, version, install button and command, starter previews, an About panel and the latest release
A community package's page in the catalog. Users install it with one click or one command.

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.md

Without --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: latest is 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, latest included.
  • 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 named alpha, beta, rc, next, preview, canary, nightly, dev or experimental moves 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@beta writes the channel into packages.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 as AI_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 file gamedev pkg pack wrote); otherwise the repository at that commit, so aigd-package.json must be at the root and dist/ committed.
  • npm: npm publish the package folder. The npm archive must contain aigd-package.json and dist/; add "engines": { "aigd": "<range>" } to package.json too, 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.json and every teammate gets the same version, pinned by the project's lock file.