item.json

Every item in a registry is described by an item.json file at the root of its directory. This is the full schema, with examples drawn from the catalog.

Minimum

{
  "$schema": "https://gamecn.dev/schema/registry-item.json",
  "name": "my-component",
  "type": "registry:component",
  "title": "My Component",
  "description": "A short one-line description.",
  "version": "1.0.0",
  "license": "MIT",
  "author": "your-name",
  "files": [
    {
      "path": "components/MyComponent.ts",
      "target": "{components}/MyComponent.ts",
      "type": "source",
      "language": "typescript"
    }
  ]
}

Required fields

name

Kebab-case identifier. Must be unique within the registry. Forms the URL path (/r/<name>.json) and the install command (gamecn add <name>).

type

The kind of item. One of:

registry:template      registry:scene         registry:component
registry:system        registry:asset         registry:shader
registry:audio         registry:model         registry:tileset
registry:ui            registry:hook          registry:utility
registry:config        registry:recipe        registry:plugin

Pick the most specific. The catalog UI groups items by type.

title, description, version

Human-readable title (separate from name), one-line summary, semver version (1.0.0).

author

Either a string ("your-name") or an object:

{
  "author": {
    "name": "Your Name",
    "url": "https://your-site.example",
    "email": "you@example.com"
  }
}

files

Array of file specs. Each entry has:

You usually don't write content / url / integrity by hand — the builder fills them in.

Optional fields

license, licenseUrl

License identifier and a link to the license text. Cataloged as metadata; not enforced.

tags

Free-form labels. Used for search and "Related items" scoring.

compatibility

Constrains which projects can install this item:

{
  "compatibility": {
    "engines": { "phaser": ">=3.80.0 <4.0.0" },
    "frameworks": ["vanilla", "react"],
    "languages": ["typescript"],
    "bundlers": ["vite"],
    "platforms": ["web", "mobile-web"]
  }
}

The engines map keys an engine name to a semver range. The CLI checks the user's package.json against this on install. See Engine versions for the conventions.

dependencies

{
  "dependencies": {
    "npm": ["phaser@^3.80.0"],
    "registry": ["input-manager"]
  }
}

npm deps trigger a package-manager install. registry deps are resolved recursively as additional registry items (transitive items share the consumer's lockfile).

assets

Structured metadata about embedded assets — image dimensions, sprite animation frames, audio formats, model triangle counts. Used by the catalog UI for richer previews. Optional.

integration

Per-engine wire-up hints. The relevant engine adapter consumes this on install:

{
  "integration": {
    "phaser": {
      "preload": [
        {
          "kind": "spritesheet",
          "key": "player",
          "path": "assets/player.png",
          "frameWidth": 32,
          "frameHeight": 32
        }
      ],
      "usage": [
        "import { MyComponent } from '@/components/MyComponent';",
        "const c = new MyComponent(this, 100, 100);"
      ]
    }
  }
}

The preload block becomes this.load.<kind>(...) calls in the user's preload scene (auto-applied with gamecn add --guided). The usage strings are printed verbatim as instructions.

preview

Display URLs for the catalog page:

{
  "preview": {
    "thumbnail": "https://your-cdn/previews/foo.png",
    "demo": "https://your-cdn/demos/foo/index.html",
    "gif": "https://your-cdn/gifs/foo.gif"
  }
}

For templates, the docs site can also generate demo URLs locally via apps/web/scripts/build-demos.ts.

Validation

The same schema runs in two places:

1. At authoring time. gamecn-registry validate reports every schema error in your tree before you build.
2. At install time. gamecn add runs the manifest through the same Zod schema before planning. Malformed manifests fail with typed errors.

JSON Schema definitions live at https://gamecn.dev/schema/registry-item.json for editor autocomplete. Add $schema at the top of your item.json to get red squigglies in your editor.