Skip to main content

CivRealm is an interactive environment for AI agents for the open-source strategy game Freeciv with the Freeciv-web client.

Project description

CivRealm: A Learning and Reasoning Odyssey in Civilization for Decision-Making Agents

CivRealm is an interactive environment for the open-source strategy game Freeciv-web, based on Freeciv, a Civilization-like game. Within CivRealm, we provide interfaces for two typical types of agents: tensor-based reinforcement learning agents (see Tensor-agent Repo) based on the Gymnasium API, and language-based agents (see LLM-agent Repo) driven by language models.

We also provide a set of tools for training and evaluating agents, as well as a set of baselines for both types of agents. We hope that CivRealm can serve as a testbed for the development and evaluation of agents that can learn and reason in complex environments. Detailed usage of the CivRealm API can be found in the Documentation.

Punic War

Contents

About

CivRealm is developed based on freeciv-bot, dependent on freeciv-web and FCIV-NET. In the future, CivRealm will be maintained by BIGAI.

Prerequisites

CivRealm requires Python ≥ 3.8 and docker. We have tested on Ubuntu 22.04, Mac OS X, and Windows. To test CivRealm on http://localhost, please follow the docker installation instructions on https://gitlab.mybigai.ac.cn/civilization/freeciv-web.git.

Installation

You can install the CivRealm stable version by:

pip install civrealm

To install the latest version from the source code or contribute to the project, please follow the instructions below:

git clone ssh://git@gitlab.mybigai.ac.cn:2222/civilization/civrealm.git && cd civrealm
pip install -e .

Testing 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. This will start a single player game against the built-in AIs with the default settings.

test_civrealm

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

```bash
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')
```

Multiplayer mode

To test with multiple players, run the following command in a 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

Trouble Shooting

The following are some common issues that you may encounter when running the code. If you encounter any other issues, please feel free to open an issue.

  • If firefox keeps loading the page, please try to add the following line to /etc/hosts:

    127.0.0.1 maxcdn.bootstrapcdn.com
    127.0.0.1 cdn.webglstats.com
    
  • If you encounter the following error when running sudo civ_prep_selenium.sh, please try this solution.

    ...
    The following packages have unmet dependencies:
    containerd.io : Conflicts: containerd
                    Conflicts: runc
    ...
    
  • If you see the following error when running test_civrealm, please see this solution. If this does not solve the problem, please check geckodriver.log for more information.

    selenium.common.exceptions.WebDriverException: Message: Process unexpectedly closed with status 1
    

    One potential solution on Ubuntu 22.04 is:

    sudo apt install firefox-geckodriver
    ln -s /snap/bin/firefox.geckodriver geckodriver
    
  • If you see the following error when setting take_screenshot: True, it is caused by snap version of Firefox. Please try System Firefox installation.

    Your Firefox profile cannot be loaded. 
    It may be missing or inaccessible.
    
  • If the screenshot is not centered on the location of your first unit, it is because you are using multiple displays. Please ensure the Firefox browser for screenshot pops up on your primary display.

Check out our paper

Our paper is available on Arxiv. If you find our code or databases useful, please consider citing us:

@inproceedings{qi2024civrealm,
  title     = {CivRealm: A Learning and Reasoning Odyssey in Civilization for Decision-Making Agents},
  author    = {Siyuan Qi and Shuo Chen and Yexin Li and Xiangyu Kong and Junqi Wang and Bangcheng Yang and Pring Wong and Yifan Zhong and Xiaoyuan Zhang and Zhaowei Zhang and Nian Liu and Wei Wang and Yaodong Yang and Song-Chun Zhu},
  booktitle = {International Conference on Learning Representations},
  year      = {2024},
  url       = {https://openreview.net/forum?id=UBVNwD3hPN}
}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

civrealm-0.1.2.tar.gz (322.1 kB view details)

Uploaded Source

Built Distribution

civrealm-0.1.2-py3-none-any.whl (384.1 kB view details)

Uploaded Python 3

File details

Details for the file civrealm-0.1.2.tar.gz.

File metadata

  • Download URL: civrealm-0.1.2.tar.gz
  • Upload date:
  • Size: 322.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.8.18

File hashes

Hashes for civrealm-0.1.2.tar.gz
Algorithm Hash digest
SHA256 4b54055472aaa2876739db9dcb37591359c67ce4db2d5b8b94471361b57031e0
MD5 6f928e14f4d63a30cca07fc131d97466
BLAKE2b-256 51c137ef82b6984285daf3df86ea7890e961f91a379e8b408e178a1b98e844d5

See more details on using hashes here.

File details

Details for the file civrealm-0.1.2-py3-none-any.whl.

File metadata

  • Download URL: civrealm-0.1.2-py3-none-any.whl
  • Upload date:
  • Size: 384.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.8.18

File hashes

Hashes for civrealm-0.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 509ce05f118c5f1bee79bdadbfd8e326b9e0312924d0e3613cdf96e15a6cce18
MD5 e00759eff5355050bf419b59a434c891
BLAKE2b-256 3d1519e60234770497127a7ef73db7425adbfcfce41d614f96c6fe0dc6451bb1

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page