Metadata-Version: 2.4
Name: ai-game-framework
Version: 1.0.0
Summary: AI Game Framework is a unified infrastructure designed to support the development and optimization of AI agents across various games.
Home-page: https://github.com/mariolpantunes/ai-game-framework
Author: Mário Antunes
Author-email: mario.antunes@ua.pt
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets>=16.0
Dynamic: license-file

# <img src="assets/logo.svg" alt="AI Game Framework logo" width="128" height="128" align="middle"> AI Game Framework (aigf)

[![PyPI - Version](https://img.shields.io/badge/pypi-v1.0.0-blue)](https://pypi.org/project/ai-game-framework)
[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://pypi.org/project/ai-game-framework)
[![GitHub License](https://img.shields.io/github/license/mariolpantunes/ai-game-framework)](LICENSE)
[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/mariolpantunes/ai-game-framework/main.yml)](https://github.com/mariolpantunes/ai-game-framework/actions)

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`:

```text
ai-game-framework >= 1.0.0
```

Or install it directly from source/PyPI:

```bash
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!

```javascript
// 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:

```python
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:
```bash
PYTHONPATH=src:. pytest
```

---

## Generating Documentation
The codebase utilizes Google-style docstrings. Build documentation into standard HTML using `pdoc`:
```bash
pip install pdoc
PYTHONPATH=src pdoc --math -d google -o docs_out aigf
```

---

## Authors

* **Mário Antunes** - [mariolpantunes](https://github.com/mariolpantunes)

## License

This project is licensed under the MIT License - see the [LICENSE](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.