Skip to main content

AICA Game Library

This package contains the core game logic and interfaces for the Game AI Competition Platform of the AI Club Aachen. It is designed to be easy to use. Simply instantiate the Agent class and begin!

Installation

You can install the package via pip:

pip install aica-gamelib

Creating an Agent

To create a game AI agent, you need to create a class that inherits from gamelib.GAME.agent.Agent. GAME is replaced by the relevant game such as tictactoe. You must implement two methods:

  1. initialize(self, agent_init_data): Setup your agent (e.g., store your player ID).
  2. get_move(self, game_state): Analyze the game state and return a Move object.

Game Concepts

GameState

The GameState object passed to get_move is defined in gamelib.GAME.gamestate.

Move

The Move object returned by get_move is defined in gamelib.GAME.move.

Example in TicTacToe

Here is a simple example of a tictactoe agent that selects the first available cell on the board.

from typing import override

from gamelib.tictactoe import Agent, GameState, Move

class MyTicTacToeAgent(Agent):
    @override
    def initialize(self, agent_init_data: dict) -> None:
        """
        Called once at the start of the game.
        agent_init_data contains 'player_id' (0 or 1).
        """
        self.player_id = agent_init_data["player_id"]

    @override
    def get_move(self, game_state: GameState) -> Move:
        """
        Called every turn. Returns the move you want to make.
        """
        # The board is a flat list of 9 integers
        # -1: Empty, 0: Player 0, 1: Player 1
        for position in range(9):
            if game_state.board[position] == -1:
                return Move(player=self.player_id, position=position)
        
        raise ValueError("No valid moves available.")

if __name__ == "__main__":
    # The only entry point you need - works both on the platform and locally.
    MyTicTacToeAgent().start()

You can import this example agent right away with:

from gamelib.tictactoe.examples import TicTacToeAgent

Running Your Agent

Your agent talks to the game engine over standard input/output (stdin/stdout). This is handled for you by Agent.start() as long as your class subclasses gamelib.GAME.agent.Agent. The only thing your file needs is a one-line entry point:

if __name__ == "__main__":
    MyTicTacToeAgent().start()

Playing Locally (gamelib-play)

The package ships a gamelib-play command to run a match in your terminal - no backend required:

gamelib-play <game> <player0> <player1>

<game> is tictactoe etc. Each player is either human or a path to a Python file defining an Agent subclass (use file.py:ClassName to pick one).

gamelib-play tictactoe human my_agent.py   # you vs your agent (you go first)
gamelib-play tictactoe my_agent.py human   # you vs your agent (agent goes first)
gamelib-play hex agent_a.py agent_b.py     # watch two agents play (A goes first)
gamelib-play tictactoe human human         # hot-seat

Metadata

Release files for aica-gamelib 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aica-gamelib 0.3.0
File Size Uploaded Provenance Actions
aica_gamelib-0.3.0.tar.gz 76.4 kB Without provenance Details for aica_gamelib-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aica-gamelib 0.3.0
File Interpreter ABI Platform Actions
aica_gamelib-0.3.0-py3-none-any.whl Python 3 none any Details for aica_gamelib-0.3.0-py3-none-any.whl

Total release size: 108.8 kB

Release files / aica_gamelib-0.3.0.tar.gz

Download URL aica_gamelib-0.3.0.tar.gz
Size 76.4 kB
Tags Source
SHA-256 checksum
How to use checksums
57f855fcf3cd8cfa7b1a8ace804012439c7e06266d82a656b7a41523fd3fa776
BLAKE2b-256 checksum
How to use checksums
f4902bcda8154645de4c3cb83cc968fe165ca0a1547c964d321734cfbc57ab26
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / aica_gamelib-0.3.0-py3-none-any.whl

Download URL aica_gamelib-0.3.0-py3-none-any.whl
Size 32.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b00acc31e32b9af4c3c343288e06d12f80f6a51417bf01f30e7cfaf448ad0227
BLAKE2b-256 checksum
How to use checksums
d68b4385c4bf1424742dea3692e579989c3b1b5783033e5c9cdf8db24021ce51
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for aica-gamelib 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page