Overview
The goal of AlgoGames is to provide a place where programmers can write algorithms ("algos") to play games. Our game engines easily interface with these algos to play matches and rank them based on their performance.
How it works
- You write an algo and upload it to our servers
- Your algo plays an unranked initial game (against itself if it is a multiplayer game)
- Our servers constantly run ranked matches to place your algo on the leaderboard
When a game is started, an algo instance is created and given the game's initial state. Next, on each tick, the engine sends game state information to the algos and waits for a move to progress the game. This process repeats until the game is over.
To prevent infinite loops and encourage efficient code, each algo has a specified amount of time to calculate and send its move. Refer to the game-specific documentation to see how this is implemented.
All matches are viewable through our replay system. Users can keep uploading improvements to their algos, but each new upload will create a new version and reset their leaderboard position.
Technical Details
Algos require some understanding of object-oriented programming. For help with this, refer to the links below:
The Algo
Algos are what users create and upload to play games. Currently, Python (3.11.9) is the only supported language and algos can be uploaded as a .py file or as a module in the form of a .zip file. If uploading an algo in a single file, a class named Algo must be defined in that file. If uploading a zip file, the root must contain a file named __init__.py which defines the Algo class.
The Algo class houses the implementation of your strategy to interface with our game engines. For convenience, a sample Algo can be found in the documentation for each game. Below are the methods that all Algo classes must implement.
Methods
Algo.__init__(self, config)
This method is called once at the beginning of the game. The argument, config, is a dictionary containing information relevant to the initial setup of the game. See the game-specific documentation for its contents. Any setup an algo may need before the game starts should be done here.
Algo.take_turn(self, state, interface)
This is the main function where strategy logic is executed. Every turn this method is called with two arguments: the game's state and interface objects. See the game-specific documentation for what take_turn is given and what it should return. In general, this function needs to return the algo's move.
Libraries Available
The Engine Interface
Each game has an interface object that allows algos to communicate to the game engine. Every interface object will have the methods and attributes described below, along with game-specific methods and attributes that can be found in the game's respective documentation.
Methods
interface.log(message)
Because game engines use the standard streams (stdin, stdout, and stderr) to communicate with algos, Python's built-in print will cause issues. Instead, use this method to write to the replay console.
interface.get_time_left()
Each game has a maximum compute duration for each turn. This function gives algos access to how much time they have left on the current turn in milliseconds. Keep in mind that this will be a slight overestimate since interface queries the game engine then relays the value back to the algo.
The Game State
Each game has a state object that houses the current state of the game. In addition to housing information, some state objects have helper methods that perform common/menial tasks relevant to it's respective game. See the game-specific documentation for details.