Configuration

A gamecn project is any directory with a gamecn.json at its root. Run npx gamecn init in your project to generate one with sensible defaults, or hand-author it.

Minimal example

{
  "$schema": "https://gamecn.dev/schema/gamecn.json",
  "engine": "phaser",
  "framework": "vanilla",
  "language": "typescript",
  "paths": {
    "src": "src",
    "assets": "public/assets"
  }
}

Fields

engine — required

The game engine your project uses. Drives which adapter runs after gamecn add.

Allowed values:

  • "phaser" — Phaser 3 or 4
  • "three" — Three.js
  • "pixi" — PixiJS (adapter not yet supported)
  • "vanilla" — DOM / no engine

framework — required

"vanilla" or "react". Influences which framework adapter runs and where installed source files land (.tsx vs .ts defaults).

language — required

"typescript" or "javascript". Currently informational; future revisions may use it to pick file extensions during install.

packageManager — optional

"npm" | "pnpm" | "yarn" | "bun". If set, gamecn add uses this PM to install npm dependencies. If unset, gamecn detects from your lockfile (bun.lock, pnpm-lock.yaml, yarn.lock, package-lock.json) and prompts when ambiguous.

paths — required

A map from logical names to actual directories in your project. The required keys are src and assets. Optional keys override the defaults that items use:

Placeholder Default Purpose
{src} required Top-level source directory
{assets} required Static assets (audio, sprites)
{components} {src}/components Reusable game components
{systems} {src}/systems Game systems (audio, input, save)
{scenes} {src}/scenes Phaser/Three scenes
{shaders} {src}/shaders GLSL/WGSL shader files
{ui} {src}/ui UI overlays

When an item declares "target": "{components}/Foo.ts", gamecn substitutes your project's path. If you want components in src/game/components/ instead of src/components/, set paths.components: "src/game/components".

registries — optional

Custom registry namespaces. See Custom registries for the full shape.

Path traversal protection

Items can declare any target, but gamecn refuses to install files outside your project root. An item declaring target: "../../etc/passwd" fails with PathEscapeError before any write happens.