ai-game-framework

AI Game Framework (aigf)

An elegant, high-performance, asynchronous Python library designed to streamline the development, testing, and optimization of AI agents in both real-time and discrete-time games. Detailed documentation is hosted on GitHub Pages.

Inspired by modern web micro-frameworks like FastAPI and Flask, aigf allows developers to build games using clean functional decorators or object-oriented classes. It bundles a fully integrated lightweight HTTP/WebSocket server that automatically serves custom visualizers along with packaged styling (nord.css) and client-side logic (framework.js).

---

Features

1. Lightweight & High Performance: Utilizes websockets and async/await event loops to easily handle large volumes of concurrent agents (perfect for neuroevolution or RL optimization).
2. Flexible API Models:
   • Decorated Hooks (AIGameServer): FastAPI/Flask style callbacks for connection, action, tick, and state-retrieval events.
   • Class Inheritance (GameInterface): Rigid Object-Oriented structure for strict architectural isolation.
3. Zero-Dependency Web Server: Houses an integrated static asset server, letting developers serve a rich HTML/JS/CSS frontend directly from Python.
4. Pre-packaged UI Ecosystem: Standardized layout sheets (nord.css) and event handlers (framework.js) are packaged inside the wheel distribution and served natively.
5. No Docker Required: Run natively on host machines inside virtual environments.

---

Installation

Add it directly to your game project's requirements.txt:

ai-game-framework >= 1.1.0

Or install it directly from source/PyPI:

pip install .

---

How it Works: Webpage Integration

The framework handles HTTP requests through a specialized static file server routing mechanism. When a web browser connects to the server (e.g. http://localhost:8765/):

1. HTML Serving: The server checks the game's viewer/ or frontend/ directory for an index.html file and serves it as the root webpage.
2. Asset Bundling: The custom HTML imports /aigf/framework.js or /aigf/nord.css.
3. Automatic Routing: The framework's internal path resolver interceptor (find_static_file) catches requests starting with /aigf/ or /framework/ and automatically serves the embedded assets bundled inside the pip package wheel. No Nginx, complex volume binds, or system-wide assets are required!

// Inside your viewer/index.html
import { GameClient } from "/aigf/framework.js";

// Instantiates a client connecting automatically to ws://localhost:8765/ws
const client = new GameClient(8765);

client.onUpdate((state) => {
  // Renders the real-time game state coordinates on canvas
  console.log("Visualizer Update:", state);
});

---

Quick Start: Decorated Game Server

Creating a game server is exceptionally quick. Register game loops and player interactions with function annotations:

from aigf.interface import AIGameServer, GameState

# 1. Initialize a real-time server operating at 30 FPS
app = AIGameServer(is_real_time=True, fps=30)
players = {}

# 2. Player handshake connector
@app.on_connect
async def connect(player_id: int):
    players[player_id] = {"x": 400.0, "y": 300.0, "score": 0}
    if len(players) >= 2:
        app.state = GameState.RUNNING

# 3. Real-time game tick
@app.on_tick
async def tick(dt: float):
    for p in players.values():
        p["x"] += 10.0 * dt  # Move players slightly right

# 4. Action receiver hook
@app.on_action
async def action(player_id: int, act: dict):
    if act.get("cmd") == "jump":
        players[player_id]["y"] -= 50.0

# 5. Visualizer state builder
@app.on_get_state
def get_state() -> dict:
    return {"players": list(players.values())}

# 6. Launch the server
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8765)

---

Interactive Examples

The package includes two fully functioning, high-quality sample games demonstrating the API:

1. Dino Jump (Real-Time Game)

Located in examples/dino_jump/. Mimics Chrome's offline dinosaur game.

• Start Server: python3 examples/dino_jump/main.py
• Play in Browser: Open http://localhost:8765/ (press Space to jump).
• Play in Terminal: Run python3 examples/dino_jump/manual_agent.py.

2. Hangman (Discrete/Turn-Based Game)

Located in examples/hangman/. A turn-based word-discovery game with zero ticks.

• Start Server: python3 examples/hangman/main.py
• Play in Browser: Open http://localhost:8765/ (click or type letters).
• Play in Terminal: Run python3 examples/hangman/manual_agent.py.

---

Running Unit Tests

Validate code changes using unittest:

python3 -m unittest discover -s tests

---

Generating Documentation

The codebase utilizes Google-style docstrings. Build documentation into standard HTML using pdoc:

pip install pdoc
PYTHONPATH=src pdoc --math -d google -o docs_out aigf

---

Authors

• Mário Antunes - mariolpantunes

License

This project is licensed under the MIT License - see the LICENSE file for details.