Installation

Python Version

Civrealm requires Python version >=3.8 and tested until 3.11.

Python Environment

We suggest using Anaconda to create a clean virtual environment for installation.

Virtual Environment

If you are using Anaconda, you can create a new environment civrealm with Python 3.8 by running the following command:

conda create -n civrealm python=3.8
conda activate civrealm

Installation

You can install the CivRealm stable version by:

pip install civrealm

For CivRealm developers, clone the CivRealm repository from GitHub and enter the directory. Then install through pip with the source code in the CivRealm folder:

cd civrealm
pip install -e .

Test the Installation

Before testing the installation, please make sure that the freeciv-web service is running. You can check the status of the freeciv-web service by running:

docker ps

You should see a docker container named freeciv-web running.

Single-Player Mode (Against Built-in AIs)

To test the installation, run the following command after installation. It starts a game with one customized player game against built-in AIs with the default settings.

test_civrealm

Success

If the installation is successful, the output should be similar to the following:

Reset with port: 6300
Step: 0, Turn: 1, Reward: 0, Terminated: False, Truncated: False, action: ('unit', 104, 'move NorthEast')
Step: 1, Turn: 1, Reward: 0, Terminated: False, Truncated: False, action: ('unit', 117, 'move North')
Step: 2, Turn: 1, Reward: 0, Terminated: False, Truncated: False, action: ('unit', 118, 'move North')
Step: 3, Turn: 1, Reward: 0, Terminated: False, Truncated: False, action: ('unit', 119, 'move SouthEast')
Step: 4, Turn: 1, Reward: 0, Terminated: False, Truncated: False, action: ('unit', 120, 'move SouthEast')

Multi-Player Mode

To test with multiple players, run the following command in one terminal to start the game with player myagent:

test_civrealm --minp=2 --username=myagent --client_port=6001

Then start another terminal and join the game with player myagent1:

test_civrealm --username=myagent1 --client_port=6001

Connect to the same port

Note that to run multiple agents in the same game, you need to make them connect to the same port (specified by client_port). The available client_port range is 6001, 6300~6331.

10 seconds delay to reuse a port

Note that when a game finishes on a port, the server on that port will take some time (around 10 seconds) to restart itself. If you start a new game on that port before the server is ready, the program will encounter unexpected errors and may stop/halt.