# 🎮 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

```bash
# 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
```javascript
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
```bash
# 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`:
```json
{
  "mcpServers": {
    "agent-game-engine": {
      "command": "node",
      "args": ["/absolute/path/to/agent-game-engine/dist/mcp/index.js"]
    }
  }
}
```
Programmatic MCP TypeScript initialization:
```typescript
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`)
```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.

---

## Support

If this project saved you some time, you can [buy me a coffee](https://buymeacoffee.com/iml1s).

## 📜 License

MIT License © 2026 ImL1s