How to Install & Use OpenGame#

1
# 1. Clone the repository
2
git clone https://github.com/leigest519/OpenGame.git
3
cd OpenGame
4

5
# 2. Create and activate the Conda environment
6
conda create -n opengame python=3.10 -y
7
conda activate opengame
8

9
# 3. Install core dependencies
10
pip install -r requirements.txt
11
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
12

13
# 4. Install Playwright for automated game testing
14
playwright install chromium
15

16
# 5. (Optional) Download GameCoder-27B locally
17
# If you don't have a powerful GPU, skip this and use API-based LLMs instead
18
huggingface-cli login
19
huggingface-cli download leigest519/GameCoder-27B --local-dir ./models/GameCoder-27B

1
python run_pipeline.py --prompt "A 2D platformer where the player jumps between moving platforms and collects gems while avoiding spikes"

1
Stage 1: PLANNING     → "Design doc generated: 3-level platformer with gem system"
2
Stage 2: TEMPLATE     → "Selected: platformer-side-scrolling (85% match)"
3
Stage 3: GENERATION   → "Created 4 files: index.html, game.js, player.js, level.js"
4
Stage 4: VERIFICATION → "Testing in headless browser... 0 errors, 2 warnings"
5
Stage 5: OUTPUT       → "Game ready at ./output/game-20260425/index.html"

1
# Specify output directory
2
python run_pipeline.py --prompt "..." --output-dir ./my-games
3

4
# Use GPT-4o instead of running local model
5
python run_pipeline.py --prompt "..." --backend openai --model gpt-4o
6

7
# Control generation complexity (low/medium/high)
8
python run_pipeline.py --prompt "..." --complexity medium
9

10
# Force a specific template
11
python run_pipeline.py --prompt "..." --template platformer-basic
12

13
# Verbose debug logging
14
python run_pipeline.py --prompt "..." --debug
15

16
# Batch generate from a file of prompts
17
python run_pipeline.py --prompt-file prompts.txt --output-dir ./batch

Key Features Deep Dive#

1
{
2
  "genre": "platformer",
3
  "mechanics": ["jump", "collect", "avoid"],
4
  "entities": {"player": {type: "character", canJump: true}, "gem": {type: "collectible"}, "spike": {type: "hazard"}},
5
  "winCondition": "collect_all_gems",
6
  "loseCondition": "hit_spikes",
7
  "controls": {"left": "ArrowLeft", "right": "ArrowRight", "jump": "Space"}
8
}

1
game/
2
├── index.html          → Entry point, canvas setup, style imports
3
├── game.js             → Game loop (update/render), state machine, scene manager
4
├── player.js           → Player entity: movement, physics, collision response
5
├── level.js            → Level layout, platform definitions, spawn points
6
├── gem.js              → Collectible gem logic, spawn positions, score tracking
7
├── input.js            → Keyboard/mouse/touch handler, key state map
8
├── renderer.js         → Canvas drawing: sprites, backgrounds, UI overlays
9
└── utils.js            → Shared helpers: collision detection, random, math

1
📁 Template: platformer-basic
2
├── index.html           → Canvas setup, viewport meta, CSS import
3
├── src/
4
│   ├── main.js          → Game loop (update/dt + render/ctx), run()
5
│   ├── Player.js        → x, y, vx, vy, jump(), update(dt), render(ctx)
6
│   ├── Platform.js      → x, y, w, h, type (static/moving), render(ctx)
7
│   ├── Collectible.js   → x, y, type, collected flag, spawn pulse animation
8
│   ├── Enemy.js         → AI patrol pattern, collision rect, death animation
9
│   ├── Level.js         → Tile map loader, entity spawn points, camera bounds
10
│   ├── Physics.js       → AABB overlap, gravity, friction, collision resolution
11
│   ├── InputManager.js  → Keyboard state map, event binding/cleanup, touch mapper
12
│   ├── Camera.js        → Follow player, smooth lerp, boundary clamping
13
│   ├── HUD.js           → Score display, lives, timer, game-over overlay
14
│   └── AssetLoader.js   → Preload images/keyframes, fallback on error, progress callback
15
├── assets/
16
│   ├── sprites/         → Placeholder sprite sheets (PNG) with named keys
17
│   └── audio/           → Placeholder SFX (WAV/OGG) with named keys
18
├── styles.css           → Full-screen canvas, UI font, overlay styles
19
└── README.md            → Controls, known issues, modification guide

1
debug-protocol/
2
├── canvas/
3
│   ├── context-lost.md        → Recreate context, rebind events, restore state
4
│   ├── retina-blur.md         → Set canvas.width = window.width * devicePixelRatio
5
│   ├── flicker.md             → Enable double-buffering via offscreen canvas
6
│   └── webgl-fallback.md      → Detect WebGL context loss, fallback to Canvas2D
7
├── physics/
8
│   ├── aabb-tunneling.md      → Swept AABB for fast-moving objects + CCD
9
│   ├── one-way-platforms.md   → Only collide when player.y + height < platform.y
10
│   └── object-clipping.md     → Clamp position AFTER collision resolution
11
├── audio/
12
│   ├── context-suspended.md   → resume() on first user gesture (addEventListener)
13
│   ├── playback-delay.md      → Pre-decode audio buffers, use AudioBufferSourceNode
14
│   └── multiple-play.md       → Stop previous instance before creating new one
15
├── performance/
16
│   ├── memory-leak-rafs.md    → Cancel all RAFs on scene destroy, remove listeners
17
│   ├── sprite-bloat.md        → Implement object pooling, max 100 concurrent sprites
18
│   └── slow-render.md         → Cull off-screen objects, batch draw calls
19
├── input/
20
│   ├── key-conflict.md        → Debounce simultaneous opposite keys (left+right)
21
│   ├── touch-mapping.md       → Map touch.position to game world coordinates
22
│   └── focus-loss.md          → Pause game on window blur, resume on focus
23
└── game-logic/
24
    ├── scene-transition.md    → Clean destroy + init cycle between scenes
25
    ├── score-race.md          → Use frame-independent scoring (delta time scaled)
26
    └── game-over-stuck.md     → Ensure game-over screen has restart handler

1
## Symptom
2
"Uncaught TypeError: Cannot read properties of null (reading 'getContext')"
3

4
## Root Cause
5
Canvas element not yet mounted when getContext() is called. Happens when
6
scripts load before DOMContentLoaded fires.
7

8
## Fix
9
Wrap all canvas initialization in DOMContentLoaded listener:
10
```javascript
11
document.addEventListener('DOMContentLoaded', () => {
12
  const canvas = document.getElementById('game-canvas');
13
  const ctx = canvas.getContext('2d');
14
  // ... rest of initialization
15
});

Verification#

1. Re-run game in headless browser
2. Confirm no “getContext” error in console
3. Verify canvas renders at least 1 frame

Tags#

engine | severity | verified:5 symptom-pattern: /getContext|Cannot read properties of null/

1
When the pipeline detects a runtime error, the Debug Skill:
2
1. Matches the error text against `symptom-pattern` regex of all fixes (takes ~50ms for 200 patterns)
3
2. Retrieves top 3 matching fixes, sorted by `severity` (critical first) then `verified` (most verified first)
4
3. Applies the fix by inserting/modifying code at the exact location indicated
5
4. Re-runs verification — if error resolved, confirms fix (increments `verified` count)
6
5. If error persists, tries next candidate fix
7
6. If all candidates fail in 5 attempts, logs the error for manual review (which becomes a new fix entry)
8

9
This self-improving loop means OpenGame gets better at debugging over time. Every manual fix added to the protocol benefits all future generations.
10

11
### 4. GameCoder-27B: A Game-Specialized Code LLM
12

13
GameCoder-27B is based on Qwen2.5-Coder technology and trained in a three-stage pipeline specifically for game development:
14

15
**Stage 1: Continual Pre-training (80 billion tokens)**
16
Data mix:
17
| Source | Tokens | Purpose |
18
|--------|:------:|---------|
19
| Phaser 3 source + examples | 10B | Arcade physics, scene management, animation system |
20
| PixiJS v8 internals + docs | 5B | WebGL rendering pipeline, sprite batching |
21
| Three.js r170 source | 8B | 3D math, lighting, materials |
22
| Raw Canvas 2D + WebGL tutorials | 12B | Low-level rendering patterns, shader basics |
23
| Game engine documentation | 15B | API reference, best practices, anti-patterns |
24
| Open-source game repos (GitHub) | 30B | Real-game code across all genres |
25

26
The model learns game-specific patterns that general code models miss:
27
- Why `requestAnimationFrame` with delta time beats `setInterval(fps)` for smooth rendering
28
- How sprite sheets map frame indices to display coordinates
29
- Why game loops decouple update (deterministic) from render (interpolation-friendly)
30
- How scene graphs manage hierarchical transformations
31

32
**Stage 2: Supervised Fine-Tuning (50,000 training pairs)**
33
Data composition:
34
- 25,000 pairs from OpenGame pipeline outputs with human corrections (before/after)
35
- 15,000 pairs from hand-picked open-source games with architecture annotations
36
- 10,000 pairs of broken game code → corrected version with explanation of the fix
37

38
Each training pair includes: (prompt, full game source code, architecture notes)
39

40
The model learns to write complete, coherent game files rather than code snippets. It maintains context across files — variables declared in `main.js` are available in `player.js` without import errors.
41

42
**Stage 3: Execution-Grounded Reinforcement Learning**
43
This is the secret sauce. Standard code RL uses human preference ratings (expensive, subjective). Execution-grounded RL runs generated code and scores it automatically:
44

45
**Reward components:**

Runtime reward: +1 if game loads without errors, -1 if any runtime error Functionality reward: 0-1 (Playwright bot performs basic actions — jump, move, collect) Stability reward: 0-1 (FPS stability over 60s — target 30+, penalty <15 FPS) Intention reward: 0-1 (VLM watches 10s gameplay, scores match vs prompt)

1
Combined reward function:

R = 0.3 × runtime + 0.3 × functionality + 0.2 × stability + 0.2 × intention

1
The model is optimized for code that actually *works as a game*, not just code that parses correctly. This is fundamentally different from standard code RL — a function that compiles is useless if the game isn't fun to play.
2

3
**Training cost:** ~500 GPU-hours on 8×A100-80GB GPUs. The paper reports the model is better than GPT-4o at game generation tasks despite being 5× smaller.
4

5
### 5. End-to-End Example: Platformer Generation Walkthrough
6

7
Let's trace what happens when you run this prompt:
8

9
```bash
10
python run_pipeline.py --prompt "A Mario-style 2D platformer with 3 levels, power-ups that give temporary invincibility, and a boss fight at the end"

Step 1 — Prompt Processing (2 seconds)

• Genre classification → platformer (confidence: 94%)
• Complexity estimation → high (power-ups, boss fight, 3 levels)
• Template match → “platformer-advanced” (82% match)

Step 2 — Template Loading (1 second) Loads template from templates/platformer-advanced/:

• 12 source files (main.js, Player.js, Enemy.js, PowerUp.js, Boss.js, Level.js, Camera.js, HUD.js, InputManager.js, Physics.js, AssetLoader.js, ParticleSystem.js)
• 5 asset placeholder files
• Project skeleton with verified game loop, collision system, state machine

Step 3 — Template Adaptation (30 seconds) The agent modifies the template:

• Adds invincibility mechanic: modifies PowerUp.js to include invincibility power-up type
• Adds boss fight logic: generates Boss.js with 3-phase attack pattern
• Configures 3 levels: modifies Level.js to define 3 level layouts with increasing difficulty
• The agent generates only the delta — existing stable code remains unchanged

Step 4 — Game Coder-27B Generation (2 minutes with GPU) Generates: ~1,200 lines of JavaScript across 12 files

• Each file is generated with awareness of all other files’ interfaces
• Power-up activation/deactivation wired into Player.js state machine
• Boss phase transitions tied to health thresholds (100% → 66% → 33% phases)
• Level completion triggers scene transition with animation

Step 5 — Verification & Debugging (1-3 minutes)

• Loads in headless Chromium via Playwright
• Detects 1 error: “AudioContext not allowed to start” — matches Debug Skill audio/context-suspended
• Applies fix: wraps all audio init in user gesture handler
• Re-runs: clean with 0 errors, 16 warnings (mostly unused variable warnings)
• Warnings are logged but do not block output — they become training data for future improvements

Step 6 — Output (instant) Generates:

1
output/game-20260426/
2
├── index.html           → Playable game, open in any browser
3
├── src/                 → All 12 source files, fully commented
4
├── assets/              → Placeholder sprites (replaceable)
5
└── README.md            → Controls, known issues, modification guide

Open game.html in browser. You have a working Mario-style platformer with 3 levels, invincibility power-ups, and a 3-phase boss fight. Total elapsed time from prompt to playable: ~5 minutes.

Comparison with Alternatives#

Who Should Use OpenGame?#

Real-World Examples from OpenGame Gallery#

The project page showcases several impressive generations:

Marvel Avengers: Infinity Strike Prompt: “Build an epic side-scrolling action platformer starring the Avengers. I want to select between Iron Man (lasers & flight), Thor (hammer melee & lightning), or Hulk (smash attacks) to fight through 3 distinct levels…”

• Character selection screen with 3 heroes
• Each hero has basic attack, special skill, and Ultimate move
• 3 levels: ruined City, SHIELD Helicarrier, Titan
• Final boss: Thanos with Infinity Stone powers
• Style: 90s Capcom arcade pixel art

Harry Potter: Arithmancy Academy Prompt: “Create a turn-based card battle game set in a pixel art Hogwarts. The twist: to cast spells, I must answer trivia questions correctly…”

• Turn-based card system with spell combos
• Magic Resonance combo system (consecutive correct answers boost damage)
• Gothic fantasy pixel art with magical particle effects
• Parchment-style UI

K.O.F: Celestial Showdown Prompt: “A Chinese mythology fighting game where Sun Wukong fights the Jade Emperor…”

• Side-scrolling fighting game with special moves
• Particle effects, health bars, combo tracking
• 3 playable characters with distinct movesets

Performance & Requirements#

Current Limitations#

1. 2D only — No 3D game generation. The framework targets HTML Canvas-based games.
2. Web only — Output is HTML/JS. No Unity, Unreal, or native mobile export.
3. Template-dependent quality — Platformers and arcade games work great. RPGs and strategy games are weaker due to limited templates.
4. Asset quality — Generated placeholder sprites are basic. Production-quality art requires manual replacement.
5. No multiplayer — No WebSocket support, no server-side game logic generation.
6. Model size — 27B parameters requires significant GPU memory. API alternative works but costs money.

Project Status & Roadmap#

• Current version: v0.7 (research prototype)
• License: Apache 2.0
• GitHub stars: 1,089 (as of April 26, 2026)
• Active contributors: 12 (from CUHK MMLab)
• Paper: arXiv:2604.18394

Planned features (from project README):

• Additional engine backends (Phaser, Three.js)
• WebAssembly export for better performance
• Mobile export via HTML-wrapped native (Capacitor/Cordova)
• Multiplayer template with WebSocket support
• AI-generated sprites and audio (DALL-E / Stable Diffusion integration)
• Interactive game editor (tweak generated games visually)

The Bottom Line#

OpenGame proves that the next frontier for code AI isn’t generating functions — it’s generating systems that work together. A game is just an especially demanding example of a multi-file, tightly-coupled system. If an AI agent can build a playable game, it can build a lot of other complex things too.

The Template Skill + Debug Skill architecture is the design pattern worth studying here. It solves the fundamental problem of LLM-generated multi-file projects: consistency across files. Apply the same pattern to web apps, microservices, or CLI tools, and the same benefits apply — faster generation, higher success rates, self-healing code.

For now: install it, generate a game, and see what happens when you describe your dream platformer in a sentence and watch it come to life in your browser.

Disclaimer: The author has no financial affiliation with CUHK MMLab or OpenGame. Analysis based on public repository and research paper.