🎮 Game Arena — AI Game Generator

English | 简体中文 | 日本語

Type one sentence. Get a playable game. Scan. Play.

Describe the game in your head — AI plans it, writes the full code, builds it, fixes its own mistakes, and hands you a QR code. Your phone is the controller screen.

📸 See it in action

Game Library (live preview + QR)	AI-generated game running on a phone

The soccer game above was 100% AI-generated from the sentence "世界杯任意球大师" — code, visuals, sound effects, all of it.

🤔 Why Game Arena?

LLMs can write code — but going from "an idea" to "something you can actually play" is still a slog: scaffolding, dependencies, build errors, broken layouts on mobile, and the inevitable half-finished output.

Game Arena closes that loop end-to-end:

• It plans before it codes — a multi-skill planning stage (interaction / gameplay / level / numerical design) produces a real design spec first
• It builds and repairs itself — source validation + vite build; on failure the LLM auto-fixes, and if that still fails, a stable fallback of the same game type is served. You always get something playable
• Zero-click sharing — every game gets a QR code; scan it on the same LAN and play on your phone instantly

✨ Features

• 🗣️ One-sentence generation — natural language in, complete React + TypeScript game out (optional reference image for visual style)
• 📡 Streaming progress — SSE pushes every step live (planning → codegen → build → preview), with cancellable generation
• 🔧 Self-repair & fallback — build failure triggers an LLM fix round; ultimate failure swaps in a stable fallback version
• 🕹️ Game library — search, sort, live-preview, share via QR, delete; all generated games in one place
• 📱 Scan-to-play — automatic QR codes, phone-optimized 375px portrait gameplay with synthesized Web Audio sound
• 🌍 i18n — Chinese & English, auto-detected from your browser, one-click switch
• 🎨 Esports-grade UI — neon arcade design with a HUD-style generation screen

🚀 Quick Start

Option A: Docker (one command)

# 1. Add your ARK API key to backend/.env
echo 'ARK_API_KEY=your_api_key_here' > backend/.env

# 2. Run everything
docker compose up --build

Open http://localhost:8080 — that's it.

Option B: Local development

Prerequisites: Node.js 20+ & pnpm · Python 3.10+ · a Volcengine ARK API key

# 1. Configure the backend
cat > backend/.env <<'EOF'
ARK_API_BASE=https://ark.cn-beijing.volces.com/api/coding/v3
ARK_API_KEY=your_api_key_here
ARK_MODEL=ark-code-latest
ARK_VISION_MODEL=kimi-k2.7-code
EOF

# 2. Backend (port 8002)
cd backend && pip install -r requirements-deploy.txt && python3 game_service.py

# 3. Frontend (port 3000, auto-proxies /api & /preview)
cd game-generator-ui && pnpm install && pnpm dev

Open http://localhost:3000, type something like "做个打地鼠游戏", and watch it come alive.

🧠 How It Works

Your sentence ──► ① Planning        ──► ② Code Generation ──► ③ Validation
 (optional        (4 design skills:     (App.tsx + index.css    (dangerous API /
  image style)     interaction,           with hard rules:       incomplete code /
                    gameplay, level,      mobile 375px, rAF       interaction entry)
                    numerical)            loop, Web Audio)
                                                          │
                          ⑥ Scan & Play ◄── ⑤ Build ◄── ④ Auto-Repair
                          (QR code,        (vite build    (LLM fixes
                           same LAN)        + preview)     failures, fallback
                                                          as safety net)

1. Planning — game-planning/*/SKILL.md files act as system prompts; the LLM produces a design spec across up to 4 dimensions
2. Code generation — the LLM outputs ===GAME_META=== / ===APP_TSX=== / ===INDEX_CSS=== sections under strict hard rules (no 100vh, rAF game loop, synthesized audio, no localStorage/eval)
3. Validation & repair — static checks + real vite build; failures feed back to the LLM for one fix round
4. Guaranteed playable — if repair still fails, a stable same-type fallback is deployed instead
5. Instant sharing — built games are served at /preview/{id}/ and rendered into a QR code

🛠️ Tech Stack

Layer	Technology
Frontend	React 18 · TypeScript · Vite · Tailwind CSS · framer-motion · lucide-react
i18n	i18next · react-i18next
Backend	FastAPI · uvicorn · httpx · pydantic
LLM	Volcengine ARK (chat/completions, code + vision models)
Deployment	Docker · Node reverse proxy

📡 API Overview

Method	Path	Description
POST	/api/games/generate-llm-stream	Stream-generate a game (SSE: step progress → done/error)
GET	/api/games/list	List built games
GET	/api/games/{game_id}/health	Query build status
DELETE	/api/games/{game_id}	Delete a game
GET	/api/games/types	List supported game types & themes
GET	/preview/{game_id}/	Play the built game

⚙️ Configuration

All via backend/.env:

Variable	Default	Description
ARK_API_KEY	—	Required. Volcengine ARK API key
ARK_API_BASE	https://ark.cn-beijing.volces.com/api/coding/v3	API endpoint
ARK_MODEL	ark-code-latest	Model for planning / codegen / repair
ARK_VISION_MODEL	kimi-k2.7-code	Vision model for reference-image style analysis
GAME_PLANNER_MAX_TOKENS	4096	Planning overview max tokens
GAME_PLANNER_SUB_SKILL_MAX_TOKENS	2048	Planning sub-skill doc max tokens
GAME_PLANNER_TIMEOUT_SECONDS	90	Planning LLM timeout
GAME_PLANNER_TEMPERATURE	0.5	Planning temperature
GAME_GENERATOR_TIMEOUT_SECONDS	240	Code generation timeout
GAME_GENERATOR_MAX_KEPT_GAMES	200	Max games kept (oldest auto-cleaned)

📁 Project Structure

├── backend/                # FastAPI service (port 8002): LLM calls, codegen, build, API
├── game-generator-ui/      # React frontend (port 3000)
│   └── src/
│       ├── components/     # SideNav / ArenaScreen / ConsolePanel / LibraryPage / ...
│       ├── hooks/          # useGameGeneration (SSE) / useGameList / useToast
│       └── i18n/           # zh & en locales
├── game-planning/          # Planning skills (system prompts for the planning stage)
├── skills/game-templates/  # Scaffold templates + runtime output dir for generated games
├── prebuilt-games/         # Prebuilt games shipped with the image
├── deploy/                 # start.sh / proxy.js (container entry)
├── docker-compose.yml
└── Dockerfile

🌍 Internationalization

Chinese & English ship out of the box — auto-detected from navigator.language, manually switchable, persisted to localStorage. To add a language: drop a new JSON into game-generator-ui/src/i18n/locales/ and register it in src/i18n/index.ts.

💬 Community

Questions, ideas, or just want to chat about AI-generated games? Scan to join — 和我交流:

QQ Group	WeChat

⭐ Support

If Game Arena sparks an idea for you, a star means a lot — it helps more people discover the project. Issues and PRs are always welcome!

📄 License

MIT