gamecn add

Install one or more items into the current project.

npx gamecn add <spec...> [options]

Examples

# From the official registry (bare name shorthand)
npx gamecn add platformer-player

# Multiple at once
npx gamecn add platformer-player input-manager save-load

# From a custom namespace configured in gamecn.json
npx gamecn add @studio/internal-camera

# From GitHub
npx gamecn add gh:OpusGameLabs/gamecn/registry-dist/r/orbit-scene.json#main

# From any HTTPS URL
npx gamecn add https://example.com/r/my-item.json

# From a local file
npx gamecn add ./my-item.json

The bare-name form (platformer-player) routes through the implicit @main registry. Configure @main in gamecn.json#registries to override which URL it resolves against.

What happens

  1. Resolve. The spec is matched against the resolver chain (namespace → github → bare-name → https → local file) and the manifest is fetched.
  2. Plan. gamecn computes the file targets, conflicts (existing files not owned by this lockfile entry), npm dependencies still missing, and engine-version compatibility.
  3. Confirm. A summary prints. By default the CLI prompts before writing; pass --yes for non-interactive runs.
  4. Install. Files are written atomically, content-addressed assets are fetched and verified against their SRI hashes, the lockfile is updated.
  5. Adapter post-install. The engine's adapter (Phaser, Three, etc.) prints integration instructions. With --guided, it can also apply marker-based source edits to your scene files.

Options

Flag Effect
--yes Skip all confirmation prompts.
--force Overwrite existing files and bypass version-compatibility checks.
--guided Apply marker-based source edits where the adapter offers them. See Markers.
--dry-run Print the install plan without writing anything.

Idempotency

Re-running gamecn add for an item already in your lockfile at the same version is a no-op. The CLI prints "already installed" and exits cleanly.

Conflicts

If a target file already exists and isn't tracked in your gamecn-lock.json under this item's name, the install bails:

gamecn-lock.json doesn't list src/components/PlatformerPlayer.ts as
installed by 'platformer-player'. To overwrite, re-run with --force.

This is a guardrail against accidentally clobbering hand-written code. --force overrides it.

Engine version mismatch

Items declare which engine versions they support via compatibility.engines. If your project's package.json has a phaser version that doesn't satisfy the item's range, the install fails:

platformer-player requires phaser >=3.80.0 <4.0.0, but ^4.0.0 is installed.

Pass --force to override (you accept the breakage). See Engine versions for how authors declare ranges.