KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #react #mcp #rust

aoc-auto-game

★ 26 Open GitHub ↗

An API for programmatically starting Age of Empires II: The Conquerors matches with specified settings.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# aoc-auto-game
An API for programmatically starting Age of Empires II: The Conquerors matches with specified settings. This is meant for offline usage only.

## Features
* Direct C++ API (library exports)
* msgpack-rpc based API that is callable from many languages, including Python, Java and C++
* Change any game setting available in the in-game lobby programmatically
* Run games faster than real-time (hours long matches can be played in minutes)
* Allow a single-player match to run even after minimizing the game
* Launch games with desired settings
* Determine when a match ends
* Determine the winning players
* Restart or exit from a match
* Run multiple matches simultaneously

## Usage
1. Grab the release or compile the DLL yourself with the dependencies listed at the bottom of this page
2. Load the DLL into age2_x1 process
3. Connect with a msgpack-RPC client on address 127.0.0.1:64720
4. Issue commands to the game to automate starting games

To specify a custom port for the RPC server, start age2_x1 with `-autogameport 64721` argument for example or any other port of your choosing. To run multiple instances of the game at the same time, start every age2_x1 process with the `-multipleinstances` argument.

Right now the best way to run games in the background is to use the SetRunUnfocused(True) to allow the game to continue running after it has been unfocused, and SetUseInGameResolution(False) to prevent the game from capturing the mouse while changing the resolution from the lobby to the in-game one. Optionally, the SetRunFullSpeed(True) can be used to run games at the maximum speed possible.

Check the example_scripts folder for how to do some of this.

## Python example
Using the ```msgpack-rpc-python``` package.

This assumes that you have already loaded the DLL into the game. For an example on how to do this check the launch_aoc.py script in the example_scripts folder.

This starts a game on an all-visible random map. We'll have custom AIs "Barbarian" and "AT_Empire" facing off against each other in player slots 1 and 2 respectively.
```
import msgpackrpc
import time

autogame = msgpackrpc.Client(msgpackrpc.Address("127.0.0.1", 64720))
autogame.call('ResetGameSettings')                    # usually reset the settings to make sure everything is valid
autogame.call('SetGameRevealMap', 2)                  # set map to "All Visible"
autogame.call('SetGameMapType', 24)                   # choose a random map

autogame.call('SetPlayerComputer', 1, "Barbarian")    # put the Barbarian AI into player slot 1
autogame.call('SetPlayerComputer', 2, "AT_Empire")    # and AT_Empire into slot 2

autogame.call('SetRunFullSpeed', True)                # run the game logic as fast as possible (experimental)
autogame.call('SetRunUnfocused', True)                # allow the game to run while minimized
autogame.call('StartGame')                            # start the match

while autogame.call('GetGameInProgress'):             # wait until the game has finished
  print("Game is running...")
  time.sleep(1.0)

winner = autogame.call('GetWinningPlayer')
print("Game finished, winner: " + str(winner))
autogame.call('QuitGame')                             # go back to the main menu
```
## Java example
Using the ```msgpack-rpc``` from Maven. We're starting an all-visible default map with 2 default AIs playing against each other.
```
import org.msgpack.rpc.Client;

public class Main
{
    public static void main(String[] args) throws Exception
    {
        Client autogame = new Client("127.0.0.1", 64720);
        autogame.callApply("ResetGameSettings", new Object[]{});
        autogame.callApply("SetGameRevealMap", new Object[]{2});

autogame.callApply("SetPlayerComputer", new Object[]{1, ""});
        autogame.callApply("SetPlayerComputer", new Object[]{2, ""});

autogame.callApply("StartGame", new Object[]{});

while (autogame.callApply("GetGameInProgress", new Object[]{}).asBooleanValue().getBoolean())
        {
            System.out.println("Game is running...");
            Thread.sleep(1000);
        }

int winner = autogame.callApply("GetWinningPlayer", new Object[]{}).asIntegerValue().getInt();
        System.out.println("Game finished, winner: " + winner);
    }
}
```

## Notes

* If including a human player, it is recommended to put them into player slot 1.
* When including many players, it is preferred to use the player slots consecutively and avoid holes.
* The default settings is a standard 1v1 matchup between a human player in slot 1 and a default AI player in slot 2, on Arabia.

## Known issues
* Calling "QuitGame" or other functions that change the game state from post match stats screen results in looping background music (although there's no reason to do any of that from there anyway).
* Starting a "Defend the Wonder" match doesn't always work.

## Dependencies
* Microsoft Detours - https://github.com/Microsoft/Detours
* rpclib (with a minor change) - https://github.com/FLWL/rpclib

## Credits
* abductedPlatypus for the game speedup offset

aoc-auto-game

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README