game-pipeline

Game Pipeline Skill

Overview

This skill orchestrates the full game development lifecycle: SCAFFOLD → ASSETS → DESIGN → AUDIO → QA → DEPLOY. Each phase can be entered independently — you do not need to start from SCAFFOLD. The orchestrator never writes game code directly; it delegates each phase to the appropriate engine-specific skill or domain reference.

Scope: Use for any browser-based game (Three.js, Phaser, or vanilla canvas), cross-cutting concerns that span engines (audio, QA, promo, deploy), and iOS export via Capacitor. Skip Unity/Godot/native engines, non-game web apps, and server-side logic.

Reference Loading Table

Instructions

Entry Point Detection

Before executing any phase, determine which phase applies:

If the entry phase is not SCAFFOLD, skip to that phase. Phases are independently re-enterable.

Phase 1: SCAFFOLD

Goal: Initialize the project and delegate engine-specific setup.

Step 1: Detect engine

Step 2: Initialize project structure

game/
├── index.html
├── src/
│   └── main.js
├── assets/
│   └── assets_index.json   # Asset manifest (required for Capacitor iOS)
└── dist/                   # Build output

assets_index.json format:

{
  "version": "1.0",
  "assets": {
    "player": "assets/player.png",
    "bgm": "assets/music.ogg"
  }
}

Step 3: Wire EventBus

Every game needs an EventBus before any feature — it is the integration contract that lets audio, effects, and analytics attach without touching game logic:

// src/EventBus.js
export const EventBus = new EventTarget();
export const emit = (name, detail = {}) =>
  EventBus.dispatchEvent(new CustomEvent(name, { detail }));
export const on = (name, fn) =>
  EventBus.addEventListener(name, (e) => fn(e.detail));

Pre-wire these event names so downstream phases attach immediately: ENEMY_HIT, PLAYER_DEATH, LEVEL_UP, GAME_OVER, SCORE_CHANGE, SPECTACLE_*

Gate: Engine chosen, project structure created, EventBus wired.

Phase 2: ASSETS

Goal: Source or generate game assets and register them in the asset manifest.

Step 1: Audit what exists

ls assets/
cat assets/assets_index.json

Step 2: Delegate to game-asset-generator

Dispatch a subagent with: asset list, art style, output format (PNG spritesheet for Phaser, GLB for Three.js), target path assets/.

Step 3: Update asset manifest

After generation, update assets/assets_index.json. This manifest is read by both the web game and the Capacitor iOS wrapper — use relative paths only.

Gate: All assets generated, manifest updated, assets load in-game without errors.

Phase 3: DESIGN

Goal: Add visual polish and "juice" — effects that make a game feel great.

Load reference: Read references/game-designer.md for patterns.

Key principle: Design polish wires to the EventBus, not to game logic. Effects can be added, removed, or swapped without touching gameplay code.

Core effects:

Opening moment rule: The first 3 seconds must hook the player — immediate visual spectacle, never a loading screen or empty scene.

Gate: At least 3 juice effects wired to EventBus events. Opening moment is compelling. No effects hardcoded into gameplay logic.

Phase 4: AUDIO

Goal: Add background music and sound effects using Web Audio API.

Load reference: Read references/game-audio.md for patterns.

Key constraint: Create AudioContext only on first user interaction — browser autoplay policy silently blocks contexts created before a gesture.

AudioManager pattern:

// src/AudioManager.js
let ctx = null;
export function getCtx() {
  if (!ctx) ctx = new AudioContext();
  return ctx;
}

AudioBridge — wire to EventBus:

import { on } from './EventBus.js';
import { getCtx } from './AudioManager.js';

on('ENEMY_HIT', () => playSFX('hit'));
on('LEVEL_UP',  () => { stopBGM(); startBGM('level2'); });
on('GAME_OVER', () => playSFX('gameover'));

Volume hierarchy: master gain → category gains (music, sfx, ambient) → individual sources. Never set volume directly on sources.

Gate: AudioContext created on user interaction only. BGM plays. At least 2 SFX events wired. Volume controls work.

Phase 5: QA

Goal: Automated testing via Playwright with visual regression and canvas test seams.

Load reference: Read references/game-qa.md for patterns.

Scripts (run from project root):

python3 skills/game/game-pipeline/scripts/imgdiff.py baseline.png current.png
python3 skills/game/game-pipeline/scripts/with_server.py "npx playwright test"

Test seam — inject into game bootstrap:

const TEST_MODE = new URLSearchParams(location.search).get('test') === '1';
const SEED = parseInt(new URLSearchParams(location.search).get('seed') || '0');
if (TEST_MODE) window.__TEST__ = { seed: SEED, state: null };

Visual regression workflow:

1. Take baseline: npx playwright screenshot --save-as baseline.png
2. Make change
3. Diff: python3 skills/game/game-pipeline/scripts/imgdiff.py baseline.png current.png
4. RMS > 5.0 means investigate the diff image

Gate: At least 1 Playwright test passes. Visual baseline captured. Canvas test seam exists.

Phase 6: DEPLOY

Goal: Ship the game to a live URL.

Load reference: Read references/deploy.md. Load references/capacitor-ios.md if iOS export needed. Load references/promo-video.md if recording gameplay for social.

Pre-deploy checklist (mandatory before any deploy):

npm run build
ls dist/
grep -r "localhost" dist/ && echo "FAIL: localhost refs" || echo "OK"
grep -r 'src="/' dist/ && echo "WARN: absolute paths" || echo "OK"

Deploy targets:

Gate: Build succeeds. Deploy URL live. Game loads. No console errors.

Error Handling

Error: AudioContext Blocked

Cause: AudioContext created outside a user gesture handler Fix: Use the getCtx() lazy-init pattern from game-audio.md. First call must happen inside click/keydown handler.

Error: Playwright Can't Interact With Canvas

Cause: No test seams, non-deterministic state, or missing readiness signal Fix: Add window.__TEST__ with ?test=1&seed=42. Wait for game.events.once('ready') before asserting. Use render_game_to_text() to expose state as text.

Error: imgdiff.py FAIL With Unexpected Diff

Cause: Font rendering or anti-aliasing differences between platforms Fix: python3 skills/game/game-pipeline/scripts/imgdiff.py a.png b.png --tolerance 10.0. If still failing, retake baseline on the same platform.

Error: Capacitor iOS Build Fails

Cause: Absolute paths in dist/, missing webDir config, or CocoaPods conflict Fix: All asset paths must be relative. Check capacitor.config.ts has webDir: 'dist'. Capacitor 5+ uses SPM — run npx cap sync, not pod install. See capacitor-ios.md.

Error: Assets Missing After Deploy

Cause: Absolute asset paths (/assets/player.png instead of assets/player.png) Fix: grep -r '"/assets/' dist/. Fix paths in build config or source — use relative paths everywhere.

Error: Promo Video Looks Choppy

Cause: Screenshot rate too slow or FFmpeg framerate mismatch Fix: Use CDP screencast instead of screenshot loop. Set game speed to 0.5 before recording, encode with -r 50 in FFmpeg. See promo-video.md.

References