Gameforge — Game Generation Orchestrator

Drives the full game-creation pipeline. The host agent (you) is the one calling LLM-bearing sub-skills; this skill describes the pipeline shape, the shared state file, validation gates, and halt conditions. All image generation goes through GPT Image 2 (gpt-image-2) at quality: low by default.

When to use

• "Make me a game where …"
• "Generate a Phaser game called …"
• "Refine the QA failures from the last run"
• Any request involving an 8-bit / pixel-art / 2D HTML5 game described in natural language

Pipeline

description
    ↓
game-designer  →  GDD + style.palette + levelHints
    ↓
world-architect  →  levels.json
    ↓
┌──────────────┬──────────────┬──────────────┬──────────────┐
sprite-artist   tile-artist    bg-artist      audio-composer  ← parallel
└──────────────┴──────────────┴──────────────┴──────────────┘
    ↓
palette-enforcer  ← quantize all PNGs to chosen 8-bit palette
    ↓
codesmith  →  src/scenes/Game.js  (imports AudioManager when state.audio is set)
    ↓
manifest-auditor   →  catches anim/texture key mismatches (fast, no browser)
mobile-compat-checker --fix  →  auto-patches roundPixels + image-rendering CSS
    ↓
parallel-qa-orchestra  →  4 workers concurrently:
  ├── static (BFS reachability, border, jump arcs)
  ├── golden-path (boot, walk, jump, attack, win scenarios)
  ├── fuzzer (stuck, spawn-trap, no-progress, NaN)
  └── physics-debug (hitbox alignment)
    ↓
VLM intent gate  ← host agent reviews screenshot vs original description
    ↓ pass
  Ship  ←— refiner (loop, max 3) ←— fail

1. game-designer turns prompt → GDD JSON (includes style.palette auto-selection by genre).
2. world-architect turns GDD → levels.json (tile-based level layouts).
3. sprite-artist turns GDD entities → sprite sheets + manifest. Uses GPT Image 2 (gpt-image-2) by default at quality: low.
4. tile-artist turns GDD tile palette → tiles.png + tile metadata.
5. bg-artist generates a parallax background image. Optional — skipped for top-down-adventure, abstract puzzle.
6. audio-composer generates sfx.json, music.json, and AudioManager.js from genre presets. Runs in parallel with art stages 3–5.
7. palette-enforcer quantizes all generated PNGs to a named 8-bit palette (e.g. pico8, sweetie-16, endesga-32) for visual coherence.
8. codesmith turns GDD + levels + manifest → src/scenes/Game.js. Imports AudioManager and calls AudioManager.init(this) in create() when state.audio is set.
9. manifest-auditor cross-references every animation/texture key in Game.js against manifest.json. Feeds mismatches to refiner before any browser is opened.
10. mobile-compat-checker (with --fix) auto-patches roundPixels: true and image-rendering: pixelated CSS; flags touch-input and audio-unlock gaps for refiner.
11. parallel-qa-orchestra replaces the serial playtester→gap-checker chain. Runs 4 workers concurrently; merges into one failure list for the refiner.
12. refiner consumes failures + current source → patched files. Loop back to parallel-qa-orchestra. Cap at 3 iterations.

Stages 3, 4, 5, 6 can run in parallel (independent inputs). Stage 7 is a fan-in (all art must be done first). Stages 9 and 10 are fast linting passes (no browser).

Shared state — game-state.json

Single source of truth at the project root. Every sub-skill reads/writes it. Schema:

{
  "version": 1,
  "name": "<project-name>",
  "prompt": "<original user description>",
  "genre": "top-down-adventure | platformer | shoot-em-up | puzzle | dungeon-crawler | top-down-rpg",
  "createdAt": "<ISO timestamp>",
  "gdd":     <output from game-designer or null>,
  "levels":  [<output from world-architect>],
  "assets": {
    "sprites": [<manifest entries from sprite-artist>],
    "tiles":   <manifest from tile-artist or null>
  },
  "code":  { "entryPoint": "src/main.js", "scenes": ["Boot","Preload","Game"] },
  "qa":    [<last 5 reports from playtester>]
}

Validate with scripts/validate_state.mjs <project-dir> after every mutation. Reject any change that breaks the schema.

Project layout (per generated game)

<project>/
├── game-state.json           # shared state
├── package.json              # phaser + vite
├── vite.config.mjs
├── index.html
├── public/
│   ├── assets/
│   │   ├── entities.png      # from sprite-artist (one or more)
│   │   ├── tiles.png         # from tile-artist
│   │   └── manifest.json     # row/col labels per sheet
│   └── data/
│       └── levels.json       # from world-architect
└── src/
    ├── main.js               # Phaser bootstrap (template, never edit)
    ├── config.js             # game config: pixelArt, FIT, RND seed
    └── scenes/
        ├── Boot.js           # template, never edit
        ├── Preload.js        # builds anims from manifest, never edit
        └── Game.js           # codesmith-written

Boot.js and Preload.js are fixed across every game — they read manifest.json, build animations as <ENTITY_ID>-<state> (lowercased state), and stash levels + manifest on this.registry. Codesmith's Game.js consumes by name only.

Animation key convention

Every animation is <ENTITY_ID>-<state-lowercase>, e.g. KNIGHT-walk, SLIME-hurt, BULLET-idle. Frame index = row * cols + col, where row is the entity's index in the sheet's rows[] and col is the state's index in the sheet's cols[]. Codesmith MUST look these up via the manifest, never hard-code.

Workflow when invoked

Path A — fresh project from a description

1. Ask user for project name (or accept arg). Run scripts/init_project.mjs <name> to scaffold.
2. Invoke game-designer with the user's description. Save GDD into game-state.json. Validate.
3. Invoke world-architect with the GDD. Save levels. Validate.
4. In parallel:
   • Invoke sprite-artist (default: GPT Image 2 at quality: low; --placeholder for free iteration).
   • Invoke tile-artist (generateTilesetGPT() via src/lib/sprites.js — one GPT Image 2 call per tile type, 512×512 → 32×32; auto-falls back to solid-color if no FAL_KEY).
   • Invoke bg-artist (generate_bg.mjs --theme <theme>). Skip when genre is top-down-adventure or abstract puzzle.
5. Write public/assets/manifest.json and public/data/levels.json from state (the asset skills merge into the manifest as they go).
6. Invoke codesmith with GDD + levels + manifest. Writes src/scenes/Game.js (and optional helpers under src/). Codesmith reads manifest.bg and adds the parallax-background pattern when present.
7. Invoke playtester. If failures, invoke refiner. Loop max 3.
8. Report final status: passed / failed / partial. If passed, tell user to cd <project> && npm run dev.

Refine an existing project

1. Read game-state.json and the latest QA report (qa/qa-report.json).
2. If passed === true, stop.
3. Invoke refiner with failures + current source files. Apply edits.
4. Invoke playtester. Loop until passed or 3 iterations.

Halt conditions

• Schema validation failure at any stage → halt, surface to user with the validation error. Do not loop.
• 3 refiner iterations without pass → halt, surface failures. Do not silently mark complete.
• FAL_KEY and OPENAI_API_KEY both missing when an asset skill wants GPT Image 2 → fall back to procedural sprites/tiles and skip bg-artist.
• User cancels (SIGINT) → exit 130.

Optional: multiplayer

Add multiplayer to any generated game via the multiplayer skill:

# After game is generated and running:
node skills/multiplayer/scripts/init_server.mjs <project-dir>   # Colyseus WebSocket server
node skills/multiplayer/scripts/patch_game.mjs <project-dir>    # patches Game.js for network sync

# Optional extras:
node skills/multiplayer/scripts/init_server.mjs <project-dir> --voice   # PeerJS voice/video
node skills/multiplayer/scripts/init_server.mjs <project-dir> --lobby   # React lobby frontend

Supports up to 4 players, 20 Hz tick rate, TypeScript shared schemas. See skills/multiplayer/SKILL.md.

References

• references/pipeline.md — detailed stage interfaces and data flow
• references/state-schema.md — full JSON schema with examples
• references/phaser-cookbook.md — Phaser 3 patterns the codesmith MUST follow

Scripts

• scripts/init_project.mjs <name> [--dir path] — scaffold from templates/phaser-game/
• scripts/validate_state.mjs <project-dir> — schema check + invariant verification
• scripts/run_pipeline.mjs <project-dir> — invoke the full pipeline (host agent drives all LLM sub-skills; no separate API key needed)