| Name | civrealm JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | |
| Summary | CivRealm is an interactive environment for AI agents for the open-source strategy game Freeciv with the Freeciv-web client. |
| upload_time | 2024-01-26 12:59:53 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | GLP3.0 |
| keywords |
civrealm
freeciv
ai
reinforcement-learning
openai-gym
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# *CivRealm*: A Learning and Reasoning Odyssey in *Civilization* for Decision-Making Agents
<div align="center">
[[Arxiv]](https://arxiv.org/abs/2401.10568)
[[PDF]](https://arxiv.org/pdf/2401.10568.pdf)
[[Docs]](https://bigai-ai.github.io/civrealm/)
[[LLM Agents]](https://github.com/bigai-ai/civrealm-llm-baseline)
[[Tensor Agent]](https://github.com/bigai-ai/civrealm-tensor-baseline)
[](<http://civilization.pages.mybigai.ac.cn/civrealm>)
[](https://pypi.org/project/civrealm/)
[](https://pypi.org/project/civrealm/)
[](https://pepy.tech/project/civrealm)
[](https://github.com/bigai-ai/civrealm/blob/main/LICENSE)
</div>
CivRealm is an interactive environment for the open-source strategy game [Freeciv-web](https://github.com/freeciv/freeciv-web), based on [Freeciv](https://www.freeciv.org/), a Civilization-like game. Within CivRealm, we provide interfaces for two typical types of agents: tensor-based reinforcement learning agents (see [Tensor-agent Repo](https://gitlab.mybigai.ac.cn/civilization/freeciv-tensor-baseline)) based on the [Gymnasium](https://gymnasium.farama.org/) API, and language-based agents (see [LLM-agent Repo](http://civilization.pages.mybigai.ac.cn/civrealm)) 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](http://civilization.pages.mybigai.ac.cn/civrealm).
# Contents
- [About](#about)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Testing the Installation](#testing-the-installation)
- [Single player mode (against built-in AIs)](#single-player-mode-against-built-in-ais)
- [Multiplayer mode](#multiplayer-mode)
- [Trouble Shooting](#trouble-shooting)
- [Our Paper](#check-out-our-paper)
## About
CivRealm is developed based on [freeciv-bot](https://github.com/chris1869/freeciv-bot), dependent on [freeciv-web](<https://github.com/freeciv/freeciv-web>) and [FCIV-NET](<https://github.com/fciv-net/fciv-net>).
In the future, CivRealm will be maintained by [BIGAI](https://www.bigai.ai/).
## 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:
```bash
pip install civrealm
```
To install the latest version from the source code or contribute to the project, please follow the instructions below:
```bash
git clone ssh://git@gitlab.mybigai.ac.cn:2222/civilization/civrealm.git && cd civrealm
pip install -e .
```
<!--
### Update the freeciv-web image
Start the freeciv-web docker:
```bash
cd freeciv-web
docker compose up -d
```
Activate the civrealm virtual environment, and update the freeciv-web image:
```bash
update_freeciv_web_docker
```
Restart the freeciv-web container so that the change takes effect
```bash
cd freeciv-web
docker compose down
docker compose up -d
```
-->
## 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:
```bash
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.
```bash
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`:
```bash
test_civrealm --minp=2 --username=myagent --client_port=6001
```
Then start another terminal and join the game with player `myagent1`:
```bash
test_civrealm --username=myagent1 --client_port=6001
```
<!-- ### Using a different freeciv version
As a standard, the official docker image from the [official repository](https://github.com/freeciv/freeciv-web) will be pulled. If you want to create a custom freeciv server (e.g., different rulesets, customizations, etc.) you can use `build_freeciv_server` to create a custom docker image or run a separate image in parallel. In this case, you might need to adapt src/init_server.py -->
## 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`:
```bash
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](https://unix.stackexchange.com/questions/724518/the-following-packages-have-unmet-dependencies-containerd-io).
```bash
...
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](https://stackoverflow.com/questions/72405117/selenium-geckodriver-profile-missing-your-firefox-profile-cannot-be-loaded). If this does not solve the problem, please check `geckodriver.log` for more information.
```bash
selenium.common.exceptions.WebDriverException: Message: Process unexpectedly closed with status 1
```
One potential solution on Ubuntu 22.04 is:
```bash
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](https://support.mozilla.org/en-US/kb/install-firefox-linux#w_install-firefox-from-mozilla-builds-for-advanced-users).
```bash
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](https://arxiv.org/abs/2401.10568). If you find our code or databases useful, please consider citing us:
```bibtex
@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}
}
```
Raw data
{
"_id": null,
"home_page": "",
"name": "civrealm",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "civrealm,freeciv,ai,reinforcement-learning,openai-gym",
"author": "",
"author_email": "Siyuan Qi <syqi@bigai.ai>, Shuo Chen <chenshuo@bigai.ai>, Yexin Li <liyexin@bigai.ai>, Xiangyu Kong <kongxiangyu@bigai.ai>, Pring Wong <huangping@bigai.ai>, Bangcheng Yang <yangbangcheng@bigai.ai>, Chris1869 <chris1869@github.com>, Junqi Wang <wangjunqi@bigai.ai>, Yifan Zhong <zhongyifan@bigai.ai>, Zhaowei Zhang <zhangzhaowei@bigai.ai>, Xiaoyuan Zhang <zhangxiaoyuan@bigai.ai>, Nian Liu <liunian@bigai.ai>",
"download_url": "https://files.pythonhosted.org/packages/51/c1/37ef82b6984285daf3df86ea7890e961f91a379e8b408e178a1b98e844d5/civrealm-0.1.2.tar.gz",
"platform": null,
"description": "# *CivRealm*: A Learning and Reasoning Odyssey in *Civilization* for Decision-Making Agents\n\n<div align=\"center\">\n\n[[Arxiv]](https://arxiv.org/abs/2401.10568)\n[[PDF]](https://arxiv.org/pdf/2401.10568.pdf)\n[[Docs]](https://bigai-ai.github.io/civrealm/)\n[[LLM Agents]](https://github.com/bigai-ai/civrealm-llm-baseline)\n[[Tensor Agent]](https://github.com/bigai-ai/civrealm-tensor-baseline)\n\n[](<http://civilization.pages.mybigai.ac.cn/civrealm>)\n[](https://pypi.org/project/civrealm/)\n[](https://pypi.org/project/civrealm/)\n[](https://pepy.tech/project/civrealm)\n[](https://github.com/bigai-ai/civrealm/blob/main/LICENSE)\n\n</div>\n\nCivRealm is an interactive environment for the open-source strategy game [Freeciv-web](https://github.com/freeciv/freeciv-web), based on [Freeciv](https://www.freeciv.org/), a Civilization-like game. Within CivRealm, we provide interfaces for two typical types of agents: tensor-based reinforcement learning agents (see [Tensor-agent Repo](https://gitlab.mybigai.ac.cn/civilization/freeciv-tensor-baseline)) based on the [Gymnasium](https://gymnasium.farama.org/) API, and language-based agents (see [LLM-agent Repo](http://civilization.pages.mybigai.ac.cn/civrealm)) driven by language models.\n\nWe 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](http://civilization.pages.mybigai.ac.cn/civrealm).\n\n\n\n# Contents\n\n- [About](#about)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Testing the Installation](#testing-the-installation)\n - [Single player mode (against built-in AIs)](#single-player-mode-against-built-in-ais)\n - [Multiplayer mode](#multiplayer-mode)\n- [Trouble Shooting](#trouble-shooting)\n- [Our Paper](#check-out-our-paper)\n\n## About\n\nCivRealm is developed based on [freeciv-bot](https://github.com/chris1869/freeciv-bot), dependent on [freeciv-web](<https://github.com/freeciv/freeciv-web>) and [FCIV-NET](<https://github.com/fciv-net/fciv-net>).\nIn the future, CivRealm will be maintained by [BIGAI](https://www.bigai.ai/).\n\n## Prerequisites\n\nCivRealm requires Python `\u2265 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>.\n\n## Installation\n\nYou can install the CivRealm stable version by:\n\n```bash\npip install civrealm\n```\n\nTo install the latest version from the source code or contribute to the project, please follow the instructions below:\n\n```bash\ngit clone ssh://git@gitlab.mybigai.ac.cn:2222/civilization/civrealm.git && cd civrealm\npip install -e .\n```\n\n<!-- \n### Update the freeciv-web image\n\nStart the freeciv-web docker:\n\n```bash\ncd freeciv-web\ndocker compose up -d\n```\n\nActivate the civrealm virtual environment, and update the freeciv-web image:\n\n```bash\nupdate_freeciv_web_docker\n```\n\nRestart the freeciv-web container so that the change takes effect\n\n```bash\ncd freeciv-web\ndocker compose down\ndocker compose up -d\n```\n-->\n\n## Testing the Installation\n\nBefore 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:\n\n```bash\ndocker ps\n```\n\nYou should see a docker container named `freeciv-web` running.\n\n### Single player mode (against built-in AIs)\n\nTo 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.\n\n```bash\ntest_civrealm\n```\n\n!!! success\n If the installation is successful, the output should be similar to the following:\n\n ```bash\n Reset with port: 6300\n Step: 0, Turn: 1, Reward: 0, Terminated: False, Truncated: False, action: ('unit', 104, 'move NorthEast')\n Step: 1, Turn: 1, Reward: 0, Terminated: False, Truncated: False, action: ('unit', 117, 'move North')\n Step: 2, Turn: 1, Reward: 0, Terminated: False, Truncated: False, action: ('unit', 118, 'move North')\n Step: 3, Turn: 1, Reward: 0, Terminated: False, Truncated: False, action: ('unit', 119, 'move SouthEast')\n Step: 4, Turn: 1, Reward: 0, Terminated: False, Truncated: False, action: ('unit', 120, 'move SouthEast')\n ```\n\n### Multiplayer mode\n\nTo test with multiple players, run the following command in a terminal to start the game with player `myagent`:\n\n```bash\ntest_civrealm --minp=2 --username=myagent --client_port=6001\n```\n\nThen start another terminal and join the game with player `myagent1`:\n\n```bash\ntest_civrealm --username=myagent1 --client_port=6001\n```\n\n<!-- ### Using a different freeciv version\n\nAs a standard, the official docker image from the [official repository](https://github.com/freeciv/freeciv-web) will be pulled. If you want to create a custom freeciv server (e.g., different rulesets, customizations, etc.) you can use `build_freeciv_server` to create a custom docker image or run a separate image in parallel. In this case, you might need to adapt src/init_server.py -->\n\n## Trouble Shooting\n\nThe 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.\n\n- If firefox keeps loading the page, please try to add the following line to `/etc/hosts`:\n\n ```bash\n 127.0.0.1 maxcdn.bootstrapcdn.com\n 127.0.0.1 cdn.webglstats.com\n ```\n\n- If you encounter the following error when running `sudo civ_prep_selenium.sh`, please try [this solution](https://unix.stackexchange.com/questions/724518/the-following-packages-have-unmet-dependencies-containerd-io).\n\n ```bash\n ...\n The following packages have unmet dependencies:\n containerd.io : Conflicts: containerd\n Conflicts: runc\n ...\n ```\n\n- If you see the following error when running `test_civrealm`, please see [this solution](https://stackoverflow.com/questions/72405117/selenium-geckodriver-profile-missing-your-firefox-profile-cannot-be-loaded). If this does not solve the problem, please check `geckodriver.log` for more information.\n\n ```bash\n selenium.common.exceptions.WebDriverException: Message: Process unexpectedly closed with status 1\n ```\n\n One potential solution on Ubuntu 22.04 is:\n\n ```bash\n sudo apt install firefox-geckodriver\n ln -s /snap/bin/firefox.geckodriver geckodriver\n ```\n\n- If you see the following error when setting `take_screenshot: True`, it is caused by snap version of Firefox. Please try [System Firefox installation](https://support.mozilla.org/en-US/kb/install-firefox-linux#w_install-firefox-from-mozilla-builds-for-advanced-users).\n\n ```bash\n Your Firefox profile cannot be loaded. \n It may be missing or inaccessible.\n ```\n\n- 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.\n\n## Check out our paper\n\nOur paper is available on [Arxiv](https://arxiv.org/abs/2401.10568). If you find our code or databases useful, please consider citing us:\n\n```bibtex\n@inproceedings{qi2024civrealm,\n title = {CivRealm: A Learning and Reasoning Odyssey in Civilization for Decision-Making Agents},\n 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},\n booktitle = {International Conference on Learning Representations},\n year = {2024},\n url = {https://openreview.net/forum?id=UBVNwD3hPN}\n}\n```\n",
"bugtrack_url": null,
"license": "GLP3.0",
"summary": "CivRealm is an interactive environment for AI agents for the open-source strategy game Freeciv with the Freeciv-web client.",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://bigai-ai.github.io/civrealm/",
"Homepage": "https://github.com/bigai-ai/civrealm",
"Issues": "https://github.com/bigai-ai/civrealm/issues",
"Source": "https://github.com/bigai-ai/civrealm"
},
"split_keywords": [
"civrealm",
"freeciv",
"ai",
"reinforcement-learning",
"openai-gym"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3d1519e60234770497127a7ef73db7425adbfcfce41d614f96c6fe0dc6451bb1",
"md5": "e00759eff5355050bf419b59a434c891",
"sha256": "509ce05f118c5f1bee79bdadbfd8e326b9e0312924d0e3613cdf96e15a6cce18"
},
"downloads": -1,
"filename": "civrealm-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e00759eff5355050bf419b59a434c891",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 384055,
"upload_time": "2024-01-26T12:59:46",
"upload_time_iso_8601": "2024-01-26T12:59:46.880242Z",
"url": "https://files.pythonhosted.org/packages/3d/15/19e60234770497127a7ef73db7425adbfcfce41d614f96c6fe0dc6451bb1/civrealm-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "51c137ef82b6984285daf3df86ea7890e961f91a379e8b408e178a1b98e844d5",
"md5": "6f928e14f4d63a30cca07fc131d97466",
"sha256": "4b54055472aaa2876739db9dcb37591359c67ce4db2d5b8b94471361b57031e0"
},
"downloads": -1,
"filename": "civrealm-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "6f928e14f4d63a30cca07fc131d97466",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 322098,
"upload_time": "2024-01-26T12:59:53",
"upload_time_iso_8601": "2024-01-26T12:59:53.557660Z",
"url": "https://files.pythonhosted.org/packages/51/c1/37ef82b6984285daf3df86ea7890e961f91a379e8b408e178a1b98e844d5/civrealm-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-26 12:59:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bigai-ai",
"github_project": "civrealm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "civrealm"
}
