Spec forms

The <spec> argument to gamecn add accepts five forms. The CLI tries each resolver in order and uses the first one that matches.

Bare name

gamecn add platformer-player

Resolves via the implicit @main registry. Equivalent to writing @main/platformer-player explicitly. The default @main URL is https://gamecn.dev/r/{name}.json; override it by setting @main in gamecn.json#registries.

Bare names must match [a-z0-9][a-z0-9_-]* (npm-style).

Namespace

gamecn add @studio/internal-camera

Looks up @studio in gamecn.json#registries and substitutes {name} in the configured URL template. Useful for private registries or shared team libraries.

GitHub shorthand

gamecn add gh:owner/repo/path/to/item.json
gamecn add gh:owner/repo/path/to/item.json#v1.2.0
gamecn add gh:owner/repo/path/to/item.json#feature/some-branch

Translates to a raw.githubusercontent.com URL at the given ref. The ref defaults to HEAD (non-reproducible — the CLI prints a warning). Pin a tag, branch, or commit SHA after # for reproducibility.

If the env var GITHUB_TOKEN is set, the CLI attaches it as a bearer token to avoid rate limits. github: is an accepted alias for gh:.

HTTPS URL

gamecn add https://example.com/r/my-item.json

Direct fetch from any URL. Cached on disk by URL. ETag-aware revalidation on subsequent runs.

Local file

gamecn add ./my-item.json
gamecn add ../shared/items/foo.json
gamecn add /abs/path/foo.json

Reads a manifest off disk. Companion source files are resolved relative to the manifest's directory. Useful for one-off authoring or workspace items not yet published.

Resolver order

The composite resolver checks specs in this order, taking the first that matches:

  1. Namespace (^@[name]/[name]$)
  2. GitHub (gh: or github:)
  3. Bare name ([a-z0-9][a-z0-9_-]*, no slashes, no .json)
  4. HTTPS (http://, https://)
  5. Local file (./, ../, absolute path, or anything ending in .json)

Specs that match none — like something with spaces or multi/word/no-json — fail with a clear error explaining the available forms.