Custom registries

A registry is a static-hosted JSON tree of items. gamecn knows how to resolve against any URL that follows the schema. You can:

• Override the default @main registry to point at a copy you control
• Add private team registries with auth headers
• Mix multiple registries in one project

Adding a registry

Set gamecn.json#registries to a record of namespace → URL or config:

{
  "registries": {
    "@main": "https://my-cdn.example/gamecn/r/{name}.json",
    "@studio": {
      "url": "https://internal.example/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${STUDIO_TOKEN}"
      }
    }
  }
}

The string form sets just the URL. The object form lets you attach headers — useful for private registries behind auth.

URL templates

The URL must contain {name} as a placeholder. gamecn substitutes the item name when resolving:

https://my-cdn.example/r/{name}.json
                            ↓
https://my-cdn.example/r/platformer-player.json

Environment variable interpolation

Header values can reference environment variables with ${VAR} syntax:

{
  "registries": {
    "@studio": {
      "url": "https://internal.example/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${STUDIO_TOKEN}",
        "X-Team": "${TEAM_ID}"
      }
    }
  }
}

Variables are read from process.env at install time. Missing variables fail loudly with MissingEnvVarError — gamecn never sends an empty Authorization header.

Overriding @main

The bare-name shortcut (gamecn add platformer-player) resolves through @main. To point your project at a fork or private mirror, just set @main in gamecn.json#registries:

{
  "registries": {
    "@main": "http://localhost:8787/r/{name}.json"
  }
}

This is the recommended way to test against a local gamecn-registry dev server during development.

GitHub-hosted registries

Any GitHub repo with built registry output works as-is via the gh: spec form. You can also configure a namespace pointing at a raw URL:

{
  "registries": {
    "@studio": {
      "url": "https://raw.githubusercontent.com/your-org/registry/main/dist/r/{name}.json",
      "headers": {
        "Authorization": "token ${GITHUB_TOKEN}"
      }
    }
  }
}

Authenticated GitHub raw URLs are subject to higher rate limits than unauthenticated ones.

Caching

Each manifest fetch is cached at ~/.gamecn/cache/manifests/. Subsequent runs send If-None-Match with the stored ETag — your CDN's ETag / Last-Modified headers determine how often gamecn revalidates.

Asset downloads are content-addressed by sha256 hash and cached at ~/.gamecn/cache/assets/. Once an asset is downloaded once, every project on the machine reuses it.

Override the cache directory with the GAMECN_CACHE_DIR environment variable.