ai-game-framework 1.0.0

AI Game Framework is a unified infrastructure designed to support the development and optimization of AI agents across various games.

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.

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.0.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 pytest:

PYTHONPATH=src:. pytest

---

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.

MIT License

Copyright (c) 2026 Mário Antunes

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.