{"id":19287274,"url":"https://github.com/opendilab/gobigger","last_synced_at":"2025-04-05T21:07:28.828Z","repository":{"id":39584632,"uuid":"411987045","full_name":"opendilab/GoBigger","owner":"opendilab","description":"[ICLR 2023] Come \u0026 try  Decision-Intelligence version of \"Agar\"! Gobigger could also help you with multi-agent decision intelligence study.","archived":false,"fork":false,"pushed_at":"2023-08-31T05:41:03.000Z","size":27678,"stargazers_count":463,"open_issues_count":0,"forks_count":34,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-29T20:04:42.580Z","etag":null,"topics":["environment","game","gym","league","multi-agent","python","reinforcement-learning","rl-environment"],"latest_commit_sha":null,"homepage":"https://gobigger.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opendilab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-30T08:39:03.000Z","updated_at":"2025-03-16T00:37:36.000Z","dependencies_parsed_at":"2024-06-19T02:50:01.779Z","dependency_job_id":"7c467bc0-e7c1-4870-a874-a9f70362d8a4","html_url":"https://github.com/opendilab/GoBigger","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opendilab%2FGoBigger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opendilab%2FGoBigger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opendilab%2FGoBigger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opendilab%2FGoBigger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opendilab","download_url":"https://codeload.github.com/opendilab/GoBigger/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247399877,"owners_count":20932876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["environment","game","gym","league","multi-agent","python","reinforcement-learning","rl-environment"],"created_at":"2024-11-09T22:05:41.823Z","updated_at":"2025-04-05T21:07:28.810Z","avatar_url":"https://github.com/opendilab.png","language":"Python","readme":"# Go-Bigger: Multi-Agent Decision Intelligence Environment\n\n[![PyPI](https://img.shields.io/pypi/v/gobigger)](https://pypi.org/project/gobigger/)\n[![Anaconda-Server Badge](https://anaconda.org/opendilab/gobigger/badges/version.svg)](https://anaconda.org/opendilab/gobigger)\n[![Read the Docs](https://img.shields.io/readthedocs/gobigger)](https://gobigger.readthedocs.io/en/latest/?badge=latest)\n[![Read the Docs](https://img.shields.io/readthedocs/gobigger?label=%E4%B8%AD%E6%96%87%E6%96%87%E6%A1%A3)](https://gobigger.readthedocs.io/zh_CN/latest/?badge=latest)\n[![unit_test](https://github.com/opendilab/GoBigger/actions/workflows/unit_test.yml/badge.svg?branch=main)](https://github.com/opendilab/GoBigger/actions/workflows/unit_test.yml)\n[![codecov](https://codecov.io/gh/opendilab/GoBigger/branch/main/graph/badge.svg?token=GwOV3jn0Le)](https://codecov.io/gh/opendilab/GoBigger)\n\n![banner](assets/banner.png)\n\n[GoBigger Doc](https://gobigger.readthedocs.io/en/latest/index.html) ([中文版](https://gobigger.readthedocs.io/zh_CN/latest/))\n\nWelcome to GoBigger v0.2!\n\n**More details can be found in our paper ([GoBigger: A Scalable Platform for Cooperative-Competitive Multi-Agent Interactive Simulation](https://openreview.net/forum?id=NnOZT_CR26Z)) accepted at ICLR2023.**\n\nGoBigger is an efficient and straightforward *agar-like* game engine and provides various interfaces for game AI development. The game is similar to [Agar](https://agar.io/), a massive multiplayer online action game created by Brazilian developer Matheus Valadares. In GoBigger, players control one or more circular balls on a map. The goal is to gain as much size as possible by eating Food Balls and other balls smaller than the player's balls while avoiding larger ones that can eat the player's balls. Each player starts with one ball, and players can split a ball into two when it reaches a sufficient size, allowing them to control multiple balls.\n\nWe pay more attention to the following points:\n\n* Cooperation is more rewarding than playing alone.\n* Violent competition is easy to break out in a small area.\n* A scalable environment that enables the simulation of various teams and agents in each team.\n* Rich action space and partially observable observation space.\n* More detailed configuration for different kinds of mini-games.\n\n## Outline\n\n* [Overview](#overview)\n* [Getting Start](#getting-start)\n* [Citation](#citation)\n* [Resources](#resources)\n* [Join and Contribute](#join-and-contribute)\n* [License](#license)\n\n## Overview\n\nGoBigger allows users to to interact with the multi-agent environment within the basic rules easily. Users can simply get the observation in the game and apply their operations for their agents through the given interface. GoBigger is built with simple rules and actions, though it has complicated observation spaces.\n\n\u003cdiv align=center\u003e\u003cimg width = '640' height ='224' src =\"assets/overview.gif\"/\u003e\u003c/div\u003e\n\n### Basic Rules\n\nTo understand the rules in the game, GoBigger provides a few concepts as follows:\n\n* `Match`: GoBigger will allow several agents to join in a match. There are many different units in a match, such as food balls, thorns balls, spore balls and clone balls. When this match ends, each agent should gain more size by eating other balls to get a higher rank. \n* `Agent`: Each agent control a team, including several players. Teamwork is essential for an agent to play against other agents.\n* `Player`: Each player starts with one ball. To improve the operability of the game, GoBigger provides several operations for a player ball, including `split` and `eject`.\n* `Ball`: GoBigger provides 4 kinds of balls in a match.\n    - `Food Ball`: Food balls are the neutral resources in the game. If a player ball eats a food ball, the food ball’s size will be parsed to the player ball.\n    - `Thorn Ball`: If a player ball eats a thorns ball, the thorns ball’s size will be parsed to the player ball. But at the same time, the player ball will explode and split into several pieces (10 by default).\n    - `Spore Ball`: Spore balls are ejected by the player balls. \n    - `Clone Ball`: Clone balls are the balls you can control in the game. You can change its moving direction. In addition, it can eat other balls smaller than itself by covering others’ centers. \n\nFor more details, please refer to [what-is-gobigger](https://gobigger.readthedocs.io/en/latest/tutorial/what_is_gobigger.html).\n\n### Observation Space\n\nGoBigger also provides a wealth of observable information, and the observation space can be divided into two parts. Here is a brief description of the observation space. For more details, please refer to [observation-space](https://gobigger.readthedocs.io/en/latest/tutorial/space.html#observation-space).\n\n#### Global State\n\nThe global state provides information related to the whole match, such as the map size, the total time and the last time of the match, and the leaderboard with team name and score.\n\n#### Player States\n\nThe player states should be like:\n\n```\n{\n    player_id: {\n        'rectangle': [left_top_x, left_top_y, right_bottom_x, right_bottom_y], # the vision's position in the map\n        'overlap': {\n            'food': [[position.x, position.y, radius, score], ...], \n            'thorns': [[position.x, position.y, radius, score, vel.x, vel.y], ...], \n            'spore': [[position.x, position.y, radius, score, vel.x, vel.y, owner], ...], \n            'clone': [[[position.x, position.y, radius, score, vel.x, vel.y, direction.x, direction.y, \n                        player_id, team_id], ...],\n        }, # all balls' info in vision\n        'team_name': team_name, # the team which this player belongs to \n        'score': player_score, # the score of the player\n        'can_eject': bool, # if the player can do the `eject` action\n        'can_split': bool, # if the player can do the `split` action\n    },\n    ...\n}\n```\n\nHere GoBigger provides the player with all the balls' information in his vision. \n\n### Action Space\n\nIn fact, a ball can only move, eject and split in a match. Thus the action space simply includes:\n\n* Moving direction for the player balls.\n* Split: Players can split a ball into two when it reaches a sufficient size.\n* Eject: Player balls can eject spore in your moving direction.\n\nMore details in [action-space](https://gobigger.readthedocs.io/en/latest/tutorial/space.html#action-space).\n\n## Getting Start\n\n### Setup\n\nWe test GoBigger within the following system:\n\n* Centos 7.6\n* Windows 10\n* MacOS Catalina 10.15\n\nAnd we recommend that your python version is 3.6. \n\n### Installation\n\nYou can simply install GoBigger from PyPI with the following command:\n\n```bash\npip install gobigger\n```\n\nIf you use Anaconda or Miniconda, you can install GoBigger through the following command:\n\n```bash\nconda install -c opendilab gobigger\n```\n\nYou can also install the newest version through GitHub. First, get and download the official repository with the following command line.\n\n```bash\ngit clone https://github.com/opendilab/GoBigger.git\n```\n\nThen you can install it from the source:\n\n```bash\n# install for use\n# Note: use `--user` option to install the related packages in the user own directory(e.g.: ~/.local)\npip install . --user\n     \n# install for development(if you want to modify GoBigger)\npip install -e . --user\n```\n\n### Usage\n\nAfter installation, you can launch your game environment easily according the following code:\n\n```python\nimport random\nfrom gobigger.envs import create_env\n\nenv = create_env('st_t2p2')\nobs = env.reset()\nfor i in range(1000):\n    actions = {0: [random.uniform(-1, 1), random.uniform(-1, 1), -1],\n               1: [random.uniform(-1, 1), random.uniform(-1, 1), -1],\n               2: [random.uniform(-1, 1), random.uniform(-1, 1), -1],\n               3: [random.uniform(-1, 1), random.uniform(-1, 1), -1]}\n    obs, rew, done, info = env.step(actions)\n    print('[{}] leaderboard={}'.format(i, obs[0]['leaderboard']))\n    if done:\n        print('finish game!')\n        break\nenv.close()\n```\n\nYou will see output as follows. It shows the frame number and the leaderboard per frame.\n\n```\n[0] leaderboard={0: 3000, 1: 3100.0}\n[1] leaderboard={0: 3000, 1: 3100.0}\n[2] leaderboard={0: 3000, 1: 3100.0}\n[3] leaderboard={0: 3000, 1: 3100.0}\n[4] leaderboard={0: 3000, 1: 3100.0}\n[5] leaderboard={0: 3000, 1: 3100.0}\n[6] leaderboard={0: 3000, 1: 3100.0}\n[7] leaderboard={0: 3000, 1: 3100.0}\n[8] leaderboard={0: 3000, 1: 3100.0}\n[9] leaderboard={0: 3000, 1: 3100.0}\n[10] leaderboard={0: 3000, 1: 3100.0}\n...\n```\n\nFor more details, you can refer to [gobigger_env.py](https://github.com/opendilab/GoBigger/blob/main/gobigger/envs/gobigger_env.py).\n\n\n### Real-time Interaction with the Game\n\nGoBigger allows users to play the game on their personal computers in real-time. Several modes are supported for users to explore this game.\n\n#### Play with bot \u0026 Partial vision\n\nIf you want to play real-time game on your PC, you can launch a game with the following code:\n\n```bash\npython -m gobigger.bin.play --mode st --vision-type partial\n```\n\nIn this mode, please use your mouse to control your balls to move, `Q` means to eject spore in your moving direction, `W` means to split your balls.\n\n\u003cdiv align=center\u003e\u003cimg width = '320' height ='334' src =\"assets/partial.gif\"/\u003e\u003c/div\u003e\n\n#### Play with bot \u0026 Full vision\n\nYou can launch a game with the following code:\n\n```bash\npython -m gobigger.bin.play --mode st --vision-type full\n```\n\n\u003cdiv align=center\u003e\u003cimg width = '320' height ='336' src =\"assets/full.gif\"/\u003e\u003c/div\u003e\n\n\n### High-level Operations in GoBigger\n\n#### Eject towards the center\n\u003cdiv align=center\u003e\u003cimg width = '232' height ='214' src =\"assets/mid_eject.gif\"/\u003e\u003c/div\u003e\n\n#### Teamwork\n\u003cdiv align=center\u003e\u003cimg width = '202' height ='186' src =\"assets/teamwork.gif\"/\u003e\u003c/div\u003e\n\n#### Split and merge\n\u003cdiv align=center\u003e\u003cimg width = '394' height ='236' src =\"assets/merge.gif\"/\u003e\u003c/div\u003e\n\n#### Split and eat others\n\u003cdiv align=center\u003e\u003cimg width = '278' height ='214' src =\"assets/eat_others.gif\"/\u003e\u003c/div\u003e\n\n## Citation\n\n```\n@inproceedings{zhang2023gobigger,\n    author = {Ming Zhang and Shenghan Zhang and Zhenjie Yang and Lekai Chen and Jinliang Zheng and Chao Yang and Chuming Li and Hang Zhou and Yazhe Niu and Yu Liu},\n    title = {GoBigger: A Scalable Platform for Cooperative-Competitive Multi-Agent Interactive Simulation},\n    booktitle={International Conference on Learning Representations},\n    year = {2023},\n    url={https://openreview.net/forum?id=NnOZT_CR26Z}\n}\n```\n\n\n## Resources\n\nFor more details, please refer to [GoBigger Doc](https://gobigger.readthedocs.io/en/latest/index.html) ([中文版](https://gobigger.readthedocs.io/zh_CN/latest/)).\n\n\n## Join and Contribute\n\nWelcome to OpenDI Lab GoBigger community! Scan the QR code and add us on Wechat:\n\n![QR code](assets/qr.png)\n\nOr you can contact us with [slack](https://opendilab.slack.com/join/shared_invite/zt-v9tmv4fp-nUBAQEH1_Kuyu_q4plBssQ#/shared-invite/email) or email (opendilab@pjlab.org.cn).\n\n## License\n\nGoBigger released under the Apache 2.0 license.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopendilab%2Fgobigger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopendilab%2Fgobigger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopendilab%2Fgobigger/lists"}