Yêu cầu#

• Python 3.10+
• GPU: CUDA 16GB+ VRAM (khuyên dùng) hoặc 32GB+ RAM (CPU)
• Conda / Miniconda
• Node.js 18+ (cho Playwright)
• Tài khoản HuggingFace (tải GameCoder-27B)

Cài đặt từng bước#

1
git clone https://github.com/leigest519/OpenGame.git
2
cd OpenGame
3

4
conda create -n opengame python=3.10 -y
5
conda activate opengame
6

7
pip install -r requirements.txt
8
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
9

10
playwright install chromium
11

12
# (Tùy chọn) Tải GameCoder-27B local
13
huggingface-cli login
14
huggingface-cli download leigest519/GameCoder-27B --local-dir ./models/GameCoder-27B

Tạo game đầu tiên#

1
python run_pipeline.py --prompt "Game platformer 2D nơi người chơi nhảy giữa các nền tảng di chuyển và thu thập ngọc trong khi tránh gai"

Quy trình 5 bước:

1
Bước 1: LẬP KẾ HOẠCH → Thiết kế game: platformer 3 màn với hệ thống ngọc
2
Bước 2: TEMPLATE    → Chọn: platformer-side-scrolling (độ khớp 85%)
3
Bước 3: SINH CODE   → Tạo 4 file: index.html, game.js, player.js, level.js
4
Bước 4: KIỂM TRA    → Chạy trong headless browser... 0 lỗi, 2 cảnh báo
5
Bước 5: XUẤT        → Game sẵn sàng tại ./output/game-20260426/index.html

Thời gian: 5-15 phút tùy độ phức tạp và phần cứng.

Cấu hình nâng cao#

1
# Dùng GPT-4o thay vì model local
2
python run_pipeline.py --prompt "..." --backend openai --model gpt-4o
3

4
# Điều khiển độ phức tạp (low/medium/high)
5
python run_pipeline.py --prompt "..." --complexity medium
6

7
# Chọn template cụ thể
8
python run_pipeline.py --prompt "..." --template platformer-basic
9

10
# Tạo hàng loạt từ file prompt
11
python run_pipeline.py --prompt-file prompts.txt --output-dir ./batch

1. Agentic Workflow Đa Bước#

OpenGame không sinh code một lần rồi hy vọng. Nó hoạt động như một agent tự trị qua 4 bước chuyên biệt:

Bước 1 — Phân tích (200-500 token) Phân rã prompt thành tài liệu thiết kế có cấu trúc:

• Cơ chế chính (nhảy, bắn, thu thập, né)
• Thực thể (người chơi, kẻ thù, item, chướng ngại vật)
• Điều kiện thắng/thua
• Điều khiển (phím mũi tên? Chuột? Cảm ứng?)

Bước 2 — Kiến trúc (500-1000 token) Thiết kế cấu trúc đa file với ranh giới trách nhiệm rõ ràng:

1
game/
2
├── index.html    → Entry point, canvas, CSS
3
├── game.js       → Game loop, state machine, scene manager
4
├── player.js     → Di chuyển, vật lý, phản hồi va chạm
5
├── level.js      → Layout level, định nghĩa platform
6
├── input.js      → Xử lý bàn phím/chuột/cảm ứng
7
└── utils.js      → Hàm tiện ích: phát hiện va chạm, random

Bước 3 — Sinh code (2000-4000 token mỗi file) Sinh từng file với đầy đủ ngữ cảnh về các file khác — ngăn lỗi “function not found”.

Bước 4 — Debug & Kiểm tra (1-5 lần lặp) Đây là nơi OpenGame khác biệt hoàn toàn:

1. Ghi tất cả file vào thư mục tạm
2. Khởi chạy Chromium headless qua Playwright
3. Chạy game 60 giây, ghi lại mọi lỗi console
4. Khớp lỗi với Debug Skill protocol
5. Áp dụng bản sửa, chạy lại, lặp đến khi sạch lỗi

2. Template Skill Library#

Thay vì sinh từ đầu mỗi lần, OpenGame duy trì thư viện ~50 template game đã kiểm chứng:

Mỗi template gồm:

• Cấu trúc file đã kiểm chứng
• Game loop pattern hoạt động
• Asset loading skeleton
• Collision detection boilerplate
• Input handling đa nền tảng
• State machine (menu / playing / paused / game-over)

Thuật toán chọn template:

1. Embed prompt bằng sentence transformer
2. Tính cosine similarity với tất cả template descriptions
3. Nếu best match > 0.7 → template adaptation
4. Nếu < 0.3 → sinh từ đầu
5. Còn lại → đề xuất top 3 template cho người dùng

3. Debug Skill Protocol#

Debug Skill là cơ sở tri thức sống gồm ~200 bản sửa lỗi đã kiểm chứng:

1
debug-protocol/
2
├── canvas/
3
│   ├── context-lost.md     → Tạo lại context, rebind events
4
│   ├── retina-blur.md      → Canvas.width = window.width * devicePixelRatio
5
│   └── flicker.md          → Double-buffering qua offscreen canvas
6
├── physics/
7
│   ├── aabb-tunneling.md   → Swept AABB + CCD cho vật thể nhanh
8
│   ├── one-way-platforms.md → Chỉ va chạm khi player.y + height < platform.y
9
│   └── object-clipping.md  → Clamp position SAU KHI collision resolution
10
├── audio/
11
│   ├── context-suspended.md → resume() khi người dùng click đầu tiên
12
│   └── playback-delay.md   → Pre-decode audio buffers
13
├── performance/
14
│   ├── memory-leak.md      → Cancel RAFs trên scene destroy
15
│   └── sprite-bloat.md     → Object pooling, tối đa 100 sprite đồng thời
16
└── game-logic/
17
    ├── scene-transition.md → Clean destroy + init cycle
18
    └── game-over-stuck.md  → Game-over screen phải có restart handler

Mỗi fix có:

• symptom-pattern: Regex khớp với console error
• severity: Critical / Major / Minor
• verification status: Verified (tested 5+ projects) / Experimental
• Fix script: Câu lệnh sửa code

Khi pipeline phát hiện lỗi runtime:

1. Khớp error text với symptom-pattern (~50ms cho 200 patterns)
2. Lấy top 3 fix, sắp xếp theo severity → verified count
3. Áp dụng fix, chạy lại verification
4. Nếu sạch lỗi → tăng verified count
5. Nếu còn lỗi → thử fix tiếp theo
6. Nếu 5 lần thất bại → log lỗi để review thủ công

Đây là vòng lặp tự cải thiện — mỗi fix thủ công được thêm vào protocol sẽ giúp ích cho tất cả các lần sinh game sau.

4. GameCoder-27B: Code LLM Chuyên Game#

GameCoder-27B (dựa trên Qwen2.5-Coder) trải qua 3 giai đoạn huấn luyện:

Giai đoạn 1: Tiền huấn luyện liên tục (80 tỷ token)

Model học các pattern game-specific mà code model thông thường bỏ lỡ:

• Tại sao requestAnimationFrame với delta time tốt hơn setInterval(fps)
• Sprite sheets ánh xạ frame indices ra tọa độ hiển thị thế nào
• Game loop tách update (deterministic) khỏi render (interpolation) ra sao

Giai đoạn 2: Supervised Fine-Tuning (50,000 cặp dữ liệu)

• 25,000 cặp từ pipeline OpenGame với sửa lỗi thủ công
• 15,000 cặp từ game mã nguồn mở có chú thích kiến trúc
• 10,000 cặp code game hỏng → code đã sửa + giải thích

Giai đoạn 3: Execution-Grounded RL (học tăng cường dựa trên thực thi) Đây là bí quyết. Thay vì dùng human preference (đắt, chủ quan), RL này chạy code trong headless browser và tự động chấm điểm:

1
Runtime reward:      +1 nếu game load không lỗi, -1 nếu có runtime error
2
Functionality reward: 0-1 (Playwright bot thực hiện hành động cơ bản)
3
Stability reward:     0-1 (FPS ổn định trong 60 giây)
4
Intention reward:     0-1 (VLM xem 10s gameplay, chấm độ khớp với prompt)

Hàm reward tổng hợp:

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

Model được tối ưu cho code thực sự chạy được như một game, không chỉ code compile không lỗi.

5. OpenGame-Bench: Cách Game Được Chấm Điểm#

Benchmark chạy game trong headless Chromium và đánh giá 3 chiều:

Build Health (0-100) — Game chạy đúng không?

• Page load thành công (+30 điểm)
• Lỗi JavaScript (-10 mỗi lỗi critical, -2 warning, tối đa -30)
• Asset loading đầy đủ (-5 mỗi asset thiếu)
• FPS ổn định (target 60 FPS, penalty nếu < 30)
• Memory leak (heap tăng liên tục >50MB: -15 điểm)
• Canvas rendering đúng (kiểm tra pixel)

Visual Usability (0-100) — Game trông ổn không?

• UI element hiển thị rõ ràng (VLM đánh giá)
• Style nhất quán giữa các màn hình
• Responsive layout ở 3 kích thước màn hình
• Text dễ đọc ở nhiều cỡ
• Controls rõ ràng — người chơi mới hiểu phải làm gì

Intent Alignment (0-100) — Game có đúng với prompt không?

• Core mechanic hiện diện (platformer có platforms? +20)
• Mục tiêu rõ ràng (VLM đánh giá sau 5 giây)
• Theme nhất quán (game vũ trụ dùng màu sắc vũ trụ)
• Tương tác đúng (phím mũi tên di chuyển? space nhảy?)

Kết quả mẫu:

OpenGame vs. Cursor / GitHub Copilot#

OpenGame vs. Unity / Godot / GameMaker#

OpenGame vs. GPT-4o / Claude (raw prompting)#

Phù hợp:#

• Game jam participants — ý tưởng → prototype trong 5-15 phút
• Indie devs — validate core mechanics trước khi build full
• Giáo viên — dạy game dev bằng ví dụ có thật + code đi kèm
• AI researchers — nghiên cứu agentic code generation
• Người đam mê — làm game mơ ước không cần học engine
• UX designers — tạo prototype tương tác cho user testing

Ít phù hợp:#

• AAA game studios — OpenGame chỉ làm 2D web game
• Performance-critical games — code sinh ra đúng nhưng chưa tối ưu
• Multiplayer phức tạp — chưa hỗ trợ server-side logic