🎮 Agent Game Engine

AI-Agent-Native 2D Game Engine in TypeScript
A lightweight, sandboxed, high-performance 2D game engine designed for AI Coding Agents to write code, evaluate quality, and render games across Headless CLI, Web Browsers, Mobile, and Desktop environments.

---

✨ Core Features

• 🤖 Verb-Driven API: Simplified, declarative game methods (spawn, controls, behavior, onCollision, winWhen, loseWhen).
• 🛡️ QuickJS WASM Sandbox: Secure code execution with strict resource limits (16MB RAM, 100ms CPU timeout) and isolation from dangerous globals.
• ⚡ 22-Opcode Command Buffer Protocol: Binary ArrayBuffer rendering offload protocol between sandbox and host.
• 🚦 5-Layer Quality Gates: Automated evaluation system catching AST security violations, infinite loops, blank screens, frozen game states, and numerical exceptions (NaN/Infinity).
• 📱 Cross-Platform Runtime: Headless Node.js, HTML5 Browser <canvas>, Mobile Touch with auto-responsive scaling (Fit/Fill/Pixel-Perfect), and Web Audio auto-unlock.
• 🎨 Complete 2D Rendering Pipeline:
  • Camera2D: Lerp follow, deadzone, bounds clamping, shake, flash, fade, zoom & rotation.
  • TilemapLoader: Tiled JSON orthogonal map rendering.
  • SpriteSheet & Texture Atlases (TexturePacker & Aseprite).
  • ParticleEmitter: Burst & continuous particle effects with scale & color gradients.
  • Viewport Frustum Culling for high-performance rendering.
• 💥 Advanced Physics & Spatial Acceleration:
  • SAT (Separating Axis Theorem) convex polygon & circle collision detection.
  • QuadTree & SpatialHashGrid supporting 500+ entities @ >200 FPS.
  • Raycasting line-of-sight & rigid body physics (Mass, Friction, Restitution, Impulse).
• 🎬 Animation, Tweens & Audio:
  • AnimationController: Frame sprite animation state machine.
  • TweenEngine: 20+ Easing curves (Elastic, Bounce, Cubic, Quad, etc.).
  • AudioManager: Web Audio SFX, BGM streaming loop, volume buses & fade transitions.
• 🕹️ Input, Scenes & UI Primitives:
  • Unified Keyboard, Mouse (world coords), Touch multi-gestures, and Gamepad Action Mapping.
  • SceneManager: Lifecycle hooks and Fade/Slide transition effects.
  • UI Primitives: UIButton, UIProgressBar, UIDialog (typewriter effect), and screen-fixed HUD overlay.
• 🧰 Asset Loader & Developer Tools:
  • Async loader with progress tracking.
  • DebugOverlay: Real-time FPS, entity count, draw calls.
  • PhysicsWireframe: Hitbox wireframe visualization.
  • TimeDilation & StepFrame: Slow-mo control and frame-by-frame step debugging.
• 🔌 CLI & MCP Server: 5 CLI commands (run, validate, watch, benchmark, demo) and 10 Model Context Protocol tools for LLM agent interaction over stdio transport.

---

📦 Installation & Setup

# Clone the repository
git clone https://github.com/ImL1s/agent-game-engine.git
cd agent-game-engine

# Install dependencies
pnpm install

# Build the monorepo package (ESM + DTS)
pnpm build

# Run full test suite (1,279 tests)
pnpm test

---

🚀 Quick Start — 4 Supported Runtimes

1. Headless Node.js Runtime

import { AgentGame } from 'agent-game-engine';

// Initialize engine instance
const game = new AgentGame({ width: 800, height: 600, fps: 60 });

// Spawn player sprite with platformer controls
const player = game.spawn('player', { x: 100, y: 100, width: 32, height: 32 });
player.controls('platformer', { speed: 200, jumpForce: 400 });

// Spawn platforms & collectibles
game.spawn('platform', { x: 400, y: 500, width: 800, height: 40 });
for (let i = 0; i < 5; i++) {
  game.spawn('coin', { x: 200 + i * 80, y: 350, width: 20, height: 20 }).behavior('float');
}

// Handle collisions
game.onCollision('player', 'coin', (p, coin) => {
  coin.destroy();
  game.addScore(10);
});

// Set win / lose conditions
game.winWhen(() => game.query('coin').length === 0);
game.loseWhen(() => player.y > 600);

// Advance engine simulation step by step
game.step(1 / 60);
const state = game.getState();
console.log(`Frame: ${state.frame}, Score: ${state.score}, Entities: ${state.entities.length}`);

2. CLI Usage

# Run game script headless for 60 frames and save state screenshot
pnpm agent-game run my-game.js --frames=60 --screenshot=out.png

# Run 5 Quality Gates validation on user script
pnpm agent-game validate my-game.js

# Launch interactive watch mode with Web live preview server
pnpm agent-game watch my-game.js --port=3000

# Run 500+ entity physics benchmark
pnpm agent-game benchmark

# Run playable interactive demo
pnpm agent-game demo

3. MCP (Model Context Protocol) Server Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "agent-game-engine": {
      "command": "node",
      "args": ["/absolute/path/to/agent-game-engine/dist/mcp/index.js"]
    }
  }
}

Programmatic MCP TypeScript initialization:

import { createMCPServer } from 'agent-game-engine/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createMCPServer();
const transport = new StdioServerTransport();
await server.connect(transport);

4. Browser Canvas Runtime (index.html)

<!DOCTYPE html>
<html>
<head>
  <title>Agent Game Engine</title>
</head>
<body>
  <canvas id="game-canvas" width="800" height="600"></canvas>
  <script type="module">
    import { AgentGame, BrowserRuntime, InputManager } from './dist/browser.js';

    const canvas = document.getElementById('game-canvas');
    const game = new AgentGame({ width: 800, height: 600 });

    const player = game.spawn('player', { x: 100, y: 100 });
    player.controls('platformer', { speed: 200, jumpForce: 400 });
    game.spawn('platform', { x: 400, y: 500, width: 800, height: 40 });

    const runtime = new BrowserRuntime({
      canvas,
      game,
      targetFps: 60,
      autoStart: true
    });
  </script>
</body>
</html>

---

🔌 MCP Server Tools (for AI Agents)

Exposes 10 tools over Stdio Transport for Claude, Cursor, Gemini, and custom AI agents:

1. game_load_code: Load game JavaScript code string.
2. game_start: Initialize and start game session.
3. game_step: Advance simulation by N frames with input state.
4. game_get_state: Retrieve Zod JSON, 2D ASCII Grid, or Delta state.
5. game_get_screenshot: Capture host canvas PNG screenshot as Base64.
6. game_simulate_input: Inject keyboard/mouse/touch input.
7. game_run_quality_gates: Run all 5 quality gates on current code.
8. game_reset: Reset game to initial state.
9. game_get_console: Retrieve intercepted console logs.
10. game_list_skills: List available game engine skills.

---

🎮 Sample Games Included

1. Pong: Simple classic paddle game.
2. Platformer: Jumping, coins, platforms, and gravity.
3. Space Shooter: Ship controls, spawning enemies, shooting projectiles.
4. Tower Defense: Enemies, pathing, tower shooting, base zone protection.
5. Puzzle: Color matching grid game.
6. Tilemap RPG: Tiled JSON map, camera follow, scene transitions, NPC dialog.
7. Physics Puzzle: SAT collisions, rigid body dynamics, particle bursts, time dilation slow-mo.

---

📜 License

MIT License © 2026 ImL1s