opengame-agentic-game-creation

# OpenGame: Agentic Web Game Creation > Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. OpenGame is an open-source TypeScript framework that generates fully playable web games end-to-end from a single natural language prompt. It combines **Game Skill** (Template Skill + Debug Skill), an optional specialized **GameCoder-27B** LLM, and **OpenGame-Bench** for automated evaluation across Build Health, Visual Usability, and Intent Alignment. --- ## What OpenGame Does - Takes a high-level game design prompt and produces a runnable browser game (HTML/JS/CSS) - **Template Skill**: Maintains a growing library of project skeletons to scaffold stable architectures - **Debug Skill**: Keeps a living protocol of verified fixes to repair cross-file integration errors systematically - **OpenGame-Bench**: Evaluates generated games via headless browser execution + VLM judging across 150 diverse prompts - Supports any OpenAI-compatible LLM backend (GPT-4o, Claude, GameCoder-27B, etc.) --- ## Prerequisites - **Node.js >= 20.0.0** - An OpenAI-compatible API key (or self-hosted GameCoder-27B endpoint) --- ## Installation ```bash # Clone the repository git clone https://github.com/leigest519/OpenGame.git cd OpenGame # Install dependencies npm install # Copy and configure environment variables cp .env.example .env ``` ### `.env` Configuration ```bash # Required: LLM API credentials OPENAI_API_KEY=$OPENAI_API_KEY OPENAI_BASE_URL=https://api.openai.com/v1 # or your custom endpoint MODEL_NAME=gpt-4o # or gamecoder-27b, claude-3-5-sonnet, etc. # Optional: OpenGame-Bench VLM judging VLM_API_KEY=$VLM_API_KEY VLM_BASE_URL=https://api.openai.com/v1 VLM_MODEL_NAME=gpt-4o # Optional: Output directory for generated games OUTPUT_DIR=./output # Optional: Max debug iterations MAX_DEBUG_ITERATIONS=5 ``` --- ## Key CLI Commands ```bash # Generate a game from a prompt npm run generate -- --prompt "Build a top-down shooter where a spaceship avoids asteroids" # Generate with a specific model npm run generate -- \ --prompt "Create a tower defense game with 3 enemy types" \ --model gpt-4o \ --output ./my-games # Run OpenGame-Bench evaluation on a set of prompts npm run bench -- --prompts ./bench/prompts.json --output ./bench-results # Evaluate a single already-generated game directory npm run evaluate -- --game-dir ./output/my-game # Run the local dev server for a generated game npm run serve -- --game-dir ./output/my-game # List available template skeletons npm run templates -- --list # Add a new template skeleton from an existing game directory npm run templates -- --add ./output/my-game --name platformer-base ``` --- ## Programmatic API ### Basic Game Generation ```typescript import { OpenGameAgent } from './src/agent'; import { GameSkill } from './src/skills/gameSkill'; import { TemplateSkill } from './src/skills/templateSkill'; import { DebugSkill } from './src/skills/debugSkill'; async function generateGame(prompt: string) { // Initialize skills const templateSkill = new TemplateSkill({ libraryPath: './templates', }); const debugSkill = new DebugSkill({ protocolPath: './debug-protocol.json', maxIterations: 5, }); const gameSkill = new GameSkill({ templateSkill, debugSkill }); // Create and run the agent const agent = new OpenGameAgent({ apiKey: process.env.OPENAI_API_KEY!, baseURL: process.env.OPENAI_BASE_URL ?? 'https://api.openai.com/v1', model: process.env.MODEL_NAME ?? 'gpt-4o', gameSkill, outputDir: './output', }); const result = await agent.generate({ prompt }); console.log('Game generated at:', result.outputPath); console.log('Build status:', result.buildHealth); return result; } generateGame( 'Make a Pac-Man style maze game with 3 levels, power-ups, and ghost AI' ).catch(console.error); ``` ### Using Template Skill Directly ```typescript import { TemplateSkill } from './src/skills/templateSkill'; const templateSkill = new TemplateSkill({ libraryPath: './templates' }); // Find the best matching template for a game type const template = await templateSkill.match({ prompt: 'side-scrolling platformer with double jump', gameType: 'platformer', }); console.log('Matched template:', template.name); console.log('Skeleton files:', template.files); // Scaffold a new project from a template const scaffolded = await templateSkill.scaffold({ template, outputDir: './output/my-platformer', context: { gameName: 'MyPlatformer', playerSpeed: 300 }, }); // Save a successful game as a new template for future use await templateSkill.save({ sourceDir: './output/successful-game', name: 'tower-defense-base', tags: ['tower-defense', 'wave-based', 'grid'], }); ``` ### Using Debug Skill for Iterative Repair ```typescript import { DebugSkill } from './src/skills/debugSkill'; import { BuildRunner } from './src/build/runner'; const debugSkill = new DebugSkill({ protocolPath: './debug-protocol.json', maxIterations: 5, }); const buildRunner = new BuildRunner({ gameDir: './output/my-game' }); // Run the debug loop const debugResult = await debugSkill.repair({ gameDir: './output/my-game', buildRunner, onIteration: (iter, error, fix) => { console.log(`Iteration ${iter}: fixing "${error.message}" with "${fix.description}"`); }, }); if (debugResult.success) { console.log('Game repaired after', debugResult.iterations, 'iterations'); // Protocol is automatically updated with the new verified fix } else { console.log('Could not repair after max iterations:', debugResult.lastError); } ``` ### OpenGame-Bench Evaluation ```typescript import { OpenGameBench } from './src/bench/evaluator'; const bench = new OpenGameBench({ vlmApiKey: process.env.VLM_API_KEY!, vlmBaseURL: process.env.VLM_BASE_URL ?? 'https://api.openai.com/v1', vlmModel: process.env.VLM_MODEL_NAME ?? 'gpt-4o', headlessBrowser: true, }); // Evaluate a single game const scores = await bench.evaluate({ gameDir: './output/my-game', originalPrompt: 'Make a Pac-Man style maze game with 3 levels', }); console.log('Build Health: ', scores.buildHealth); // 0–100 console.log('Visual Usability: ', scores.visualUsability); // 0–100 console.log('Intent Alignment: ', scores.intentAlignment); // 0–100 console.log('Overall: ', scores.overall); // Batch evaluation across multiple prompts import promptsData from './bench/prompts.json'; const batchResults = await bench.evaluateBatch({ prompts: promptsData, agent, // OpenGameAgent instance outputDir: './bench-results', concurrency: 4, }); console.log('Mean Build Health: ', batchResults.mean.buildHealth); console.log('Mean Intent Alignment: ', batchResults.mean.intentAlignment); ``` --- ## Project Structure ``` OpenGame/ ├── src/ │ ├── agent/ # Core OpenGameAgent orchestration │ ├── skills/ │ │ ├── gameSkill.ts # Combines Template + Debug skills │ │ ├── templateSkill.ts# Template library management & matching │ │ └── debugSkill.ts # Debug protocol & iterative repair │ ├── build/ │ │ └── runner.ts # Headless build execution & error capture │ ├── bench/ │ │ └── evaluator.ts # OpenGame-Bench scoring pipeline │ └── llm/ │ └── client.ts # OpenAI-compatible LLM client ├── templates/ # Template skeleton library (grows over time) ├── bench/ │ └── prompts.json # 150 benchmark game prompts ├── output/ # Generated games land here ├── debug-protocol.json # Living verified-fix protocol ├── .env.example └── package.json ``` --- ## Common Patterns ### Full Pipeline: Prompt → Playable Game ```typescript import { OpenGameAgent } from './src/agent'; import { GameSkill } from './src/skills/gameSkill'; import { TemplateSkill } from './src/skills/templateSkill'; import { DebugSkill } from './src/skills/debugSkill'; import { OpenGameBench } from './src/bench/evaluator'; async function fullPipeline(prompt: string) { const agent = new OpenGameAgent({ apiKey: process.env.OPENAI_API_KEY!, baseURL: process.env.OPENAI_BASE_URL!, model: process.env.MODEL_NAME ?? 'gpt-4o', gameSkill: new GameSkill({ templateSkill: new TemplateSkill({ libraryPath: './templates' }), debugSkill: new DebugSkill({ protocolPath: './debug-protocol.json', maxIterations: 5, }), }), outputDir: './output', }); // Step 1: Generate const result = await agent.generate({ prompt }); console.log('Generated:', result.outputPath); // Step 2: Evaluate const bench = new OpenGameBench({ vlmApiKey: process.env.VLM_API_KEY!, vlmModel: 'gpt-4o', headlessBrowser: true, }); const scores = await bench.evaluate({ gameDir: result.outputPath, originalPrompt: prompt, }); console.log('Scores:', scores); // Step 3: If good quality, promote to template library if (scores.overall >= 80) { const templateSkill = new TemplateSkill({ libraryPath: './templates' }); await templateSkill.save({ sourceDir: result.outputPath, name: `auto-${Date.now()}`, tags: ['auto-promoted'], }); console.log('Promoted to template library!'); } return { result, scores }; } ``` ### Custom LLM Endpoint (e.g., GameCoder-27B self-hosted) ```typescript const agent = new OpenGameAgent({ apiKey: process.env.GAMECODER_API_KEY!, baseURL: process.env.GAMECODER_BASE_URL!, // e.g. http://localhost:8000/v1 model: 'gamecoder-27b', gameSkill, outputDir: './output', }); ``` ### Loading Prompts from File and Batch Generating ```typescript import fs from 'fs/promises'; async function batchGenerate(promptsFile: string) { const prompts: string[] = JSON.parse(await fs.readFile(promptsFile, 'utf8')); for (const [i, prompt] of prompts.entries()) { console.log(`Generating ${i + 1}/${prompts.length}: ${prompt.slice(0, 60)}...`); try { const result = await agent.generate({ prompt }); console.log(' ✅ Output:', result.outputPath); } catch (err) { console.error(' ❌ Failed:', err); } } } batchGenerate('./bench/prompts.json'); ``` --- ## Troubleshooting ### Build fails immediately with no output - Ensure `NODE_VERSION >= 20.0.0`: `node --version` - Verify your API key and base URL are set correctly in `.env` - Check that `OUTPUT_DIR` exists and is writable ### LLM returns incomplete or truncated code - Increase the model's max token limit in your API settings or agent config - Switch to a larger/more capable model: `MODEL_NAME=gpt-4o` or `gamecoder-27b` - The Debug Skill will attempt iterative repair; raise `MAX_DEBUG_ITERATIONS` if needed ### Debug loop exhausted without success - Inspect `debug-protocol.json` — it may need a manual verified fix entry for a novel error pattern - Check `./output/<game>/build.log` for the raw build errors - Reduce game complexity in the prompt and regenerate ### OpenGame-Bench headless browser errors - Ensure Chromium/Chrome is installed: `npx playwright install chromium` - For CI environments, set `DISPLAY=:99` or use a virtual framebuffer ### Template matching returns wrong skeleton - Add a better-matched template: `npm run templates -- --add ./output/good-example --name my-game-type` - Templates are matched by semantic similarity to the prompt; more diverse templates improve accuracy ### Rate limits or API quota errors - Add retry logic or use `concurrency: 1` in batch evaluation - For self-hosted GameCoder-27B, verify the vLLM/TGI server is healthy: `curl $GAMECODER_BASE_URL/health` --- ## Benchmark: OpenGame-Bench OpenGame-Bench evaluates 150 diverse game prompts across three axes: | Metric | Description | |---|---| | **Build Health** | Does the game compile and run without errors in a headless browser? | | **Visual Usability** | Are UI elements visible, legible, and interactable? (VLM-judged) | | **Intent Alignment** | Does the generated game match the original prompt's design intent? (VLM-judged) | ```bash # Run full benchmark (150 prompts) npm run bench -- \ --prompts ./bench/prompts.json \ --output ./bench-results \ --concurrency 4 # Results are saved to ./bench-results/summary.json ```