notque/vexjoy-agent / skills/game/game-dev
game-dev
FlaggedGame development: design, asset pipelines, Phaser, Unity CLI and builds, vanilla JS frontend, GM mode, match booking.
references/game-pipeline.md
View on GitHub# 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 Godot and native engines, non-game web apps, and server-side logic. For Unity projects, use Unity mode in `SKILL.md`.
---
## Reference Loading Table
| Signal | Load These Files | Why |
|---|---|---|
| `references/game-audio.md` | `game-audio.md` | AUDIO |
| `references/game-qa.md` | `game-qa.md` | QA |
| `references/game-designer.md` | `game-designer.md` | DESIGN |
| `references/promo-video.md` | `promo-video.md` | DEPLOY |
| `references/deploy.md` | `deploy.md` | DEPLOY |
| `references/capacitor-ios.md` | `capacitor-ios.md` | DEPLOY |
| "3D model", GLB, mesh, rig, meshy | `game-asset-generator.md`, `meshyai.md` | 3D model generation |
| "environment", "gaussian splat", "world labs" | `game-asset-generator.md`, `worldlabs.md` | Environment generation |
| "sprite", "pixel art", "tile", "palette quantize" | `game-asset-generator.md`, `pixel-art-sprites.md` | 2D sprite / pixel art |
| "image", "texture", "concept art", fal.ai | `game-asset-generator.md`, `fal-ai-image.md` | Image / texture generation |
| "free asset", "find model", "sketchfab" | `game-asset-generator.md`, `asset-sources.md` | Existing asset sources |
| "mocap", "BVH", "motion data", "animation pipeline" | `motion-pipeline.md` | Motion data import / processing |
| "contact detection", "IK solve", "FABRIK" | `motion-pipeline.md` | Contact / IK solving |
| "motion blend", "bone trajectory", "root extraction" | `motion-pipeline.md` | Motion decomposition / blending |
## Instructions
### Entry Point Detection
**Before executing any phase**, determine which phase applies:
| User request | Entry phase |
|---|---|
| "make a game", "start a game", "new game" | SCAFFOLD |
| "generate assets", "add sprites", "need art" | ASSETS |
| "add juice", "game feels flat", "particles", "screen shake" | DESIGN |
| "add audio", "background music", "sound effects" | AUDIO |
| "test my game", "visual regression", "playwright", "game qa" | QA |
| "deploy", "ship", "publish", "github pages", "promo video", "ios" | DEPLOY |
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**
| Signal | Engine | Delegate to |
|---|---|---|
| `import * as THREE`, three.js in package.json | Three.js | `threejs-builder` skill |
| `new Phaser.Game()`, phaser in package.json | Phaser | `phaser-gamedev` skill |
| No engine signal | Ask user before proceeding | — |
**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:
```json
{
"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:
```javascript
// 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**
```bash
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**:
| Effect | Trigger event | Impact |
|---|---|---|
| Screen shake | `ENEMY_HIT`, `EXPLOSION` | Impact weight |
| Hit freeze frame | `ENEMY_HIT` (big) | Dramatic pause |
| Particle burst | `ENEMY_HIT`, `GAME_OVER` | Visual feedback |
| Floating score text | `SCORE_CHANGE` | Progress reward |
| Combo text | `COMBO_REACHED` | Achievement surge |
**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**:
```javascript
// src/AudioManager.js
let ctx = null;
export function getCtx() {
if (!ctx) ctx = new AudioContext();
return ctx;
}
```
**AudioBridge — wire to EventBus**:
```javascript
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):
```bash
python3 skills/game/game-dev/scripts/imgdiff.py baseline.png current.png
python3 skills/game/game-dev/scripts/with_server.py "npx playwright test"
```
**Test seam** — inject into game bootstrap:
```javascript
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-dev/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):
```bash
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**:
| Target | Command | Notes |
|---|---|---|
| GitHub Pages | `npx gh-pages -d dist` | Public repo or GitHub Pro |
| Vercel | `vercel --prod` | Best for preview URLs |
| Static host | Upload `dist/` | Works anywhere |
| iOS (Capacitor) | See `capacitor-ios.md` | Requires Xcode |
**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-dev/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
| Reference | Phase | Content |
|---|---|---|
| `references/game-audio.md` | AUDIO | Web Audio API: AudioManager, BGM sequencer, SFX pool, AudioBridge, volume hierarchy |
| `references/game-qa.md` | QA | Playwright: visual regression, canvas seams, deterministic mode, imgdiff patterns |
| `references/game-designer.md` | DESIGN | Juice: particles, screen shake, hit freeze, combo text, spectacle events |
| `references/promo-video.md` | DEPLOY | Slow-mo trick, Playwright recording, FFmpeg assembly, mobile portrait format |
| `references/deploy.md` | DEPLOY | GitHub Pages, Vercel, static hosting, pre-deploy checklist |
| `references/capacitor-ios.md` | DEPLOY | Capacitor 5+ iOS: SPM setup, asset contracts, touch controls, debugging |
| `references/game-asset-generator.md` | ASSETS | Game asset generation: 3D models, environments, sprites, textures, free sources |
| `references/meshyai.md` | ASSETS | Meshy API: text-to-3D, image-to-3D, rig, animate, optimize-glb |
| `references/worldlabs.md` | ASSETS | World Labs Marble API: SPZ generation, SplatMesh renderer, Y-flip |
| `references/fal-ai-image.md` | ASSETS | fal.ai: model endpoints, queue API, cost tracking, chroma-key |
| `references/asset-sources.md` | ASSETS | Sketchfab, Poly Haven, Poly.pizza search and download |
| `references/pixel-art-sprites.md` | ASSETS | Canvas sprite matrices, palette system, animation frames |
| `references/motion-pipeline.md` | ASSETS | CPU-only motion pipeline: BVH import, contacts, decompose, blend, IK |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |