{"id":13457507,"url":"https://github.com/oxwhirl/smac","last_synced_at":"2025-05-15T23:03:57.191Z","repository":{"id":39632955,"uuid":"164697388","full_name":"oxwhirl/smac","owner":"oxwhirl","description":"SMAC: The StarCraft Multi-Agent Challenge","archived":false,"fork":false,"pushed_at":"2024-02-18T19:49:08.000Z","size":2644,"stargazers_count":1197,"open_issues_count":20,"forks_count":234,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-05-13T02:48:26.089Z","etag":null,"topics":["benchmark","machine-learning","multiagent-systems","reinforcement-learning","starcraft-ii"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oxwhirl.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":"2019-01-08T17:12:37.000Z","updated_at":"2025-04-30T23:31:53.000Z","dependencies_parsed_at":"2023-02-08T20:00:28.899Z","dependency_job_id":"a870152d-3844-414c-bddb-fa252f8d7561","html_url":"https://github.com/oxwhirl/smac","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxwhirl%2Fsmac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxwhirl%2Fsmac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxwhirl%2Fsmac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxwhirl%2Fsmac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxwhirl","download_url":"https://codeload.github.com/oxwhirl/smac/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436944,"owners_count":22070946,"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":["benchmark","machine-learning","multiagent-systems","reinforcement-learning","starcraft-ii"],"created_at":"2024-07-31T09:00:27.737Z","updated_at":"2025-05-15T23:03:57.145Z","avatar_url":"https://github.com/oxwhirl.png","language":"Python","funding_links":[],"categories":["Envs","Other reading material (blogs, websites, videos)","Python","Papers","Benchmarks and Evaluation","Environment"],"sub_categories":["SMAC","Opponent Modelling","ICLR 2024","NeurIPS 2022","Datasets","Others"],"readme":"\u003cp align=\"center\"\u003e\n \u003cimg width=\"95%\" src=\"docs/smac-official.png\" /\u003e\n\u003c/p\u003e\n\n\u003e __Note__\n\u003e SMACv2 is out! Check it out [here](https://github.com/oxwhirl/smacv2).\n\n\u003e __Warning__\n\u003e **Please pay attention to the version of SC2 used for your experiments.** Performance is **not** always comparable between versions. The results in the [SMAC paper](https://arxiv.org/abs/1902.04043) use `SC2.4.6.2.69232` not `SC2.4.10`.\n\n# SMAC - StarCraft Multi-Agent Challenge\n\n[SMAC](https://github.com/oxwhirl/smac) is [WhiRL](http://whirl.cs.ox.ac.uk)'s environment for research in the field of cooperative multi-agent reinforcement learning (MARL) based on [Blizzard](http://blizzard.com)'s [StarCraft II](https://en.wikipedia.org/wiki/StarCraft_II:_Wings_of_Liberty) RTS game. SMAC makes use of Blizzard's [StarCraft II Machine Learning API](https://github.com/Blizzard/s2client-proto) and [DeepMind](https://deepmind.com)'s [PySC2](https://github.com/deepmind/pysc2) to provide a convenient interface for autonomous agents to interact with StarCraft II, getting observations and performing actions. Unlike the [PySC2](https://github.com/deepmind/pysc2), SMAC concentrates on *decentralised micromanagement* scenarios, where each unit of the game is controlled by an individual RL agent.\n\nPlease refer to the accompanying [paper](https://arxiv.org/abs/1902.04043) and [blogpost](https://blog.ucldark.com/2019/02/12/smac.html) for the outline of our motivation for using SMAC as a testbed for MARL research and the initial experimental results.\n\n## About\n\nTogether with SMAC we also release [PyMARL](https://github.com/oxwhirl/pymarl) - our [PyTorch](https://github.com/pytorch/pytorch) framework for MARL research, which includes implementations of several state-of-the-art algorithms, such as [QMIX](https://arxiv.org/abs/1803.11485) and [COMA](https://arxiv.org/abs/1705.08926).\n\nData from the runs used in the paper is included [here](https://github.com/oxwhirl/smac/releases/download/v1/smac_run_data.json). **These runs are \u003cins\u003eoutdated\u003c/ins\u003e based on recent changes in StarCraft II. If you ran your experiments using the current version of SMAC, you mustn't compare your results with the ones provided here.**\n\n# Quick Start\n\n## Installing SMAC\n\nYou can install SMAC by using the following command:\n\n```shell\npip install git+https://github.com/oxwhirl/smac.git\n```\n\nAlternatively, you can clone the SMAC repository and then install `smac` with its dependencies:\n\n```shell\ngit clone https://github.com/oxwhirl/smac.git\npip install -e smac/\n```\n\n*NOTE*: If you want to extend SMAC, please install the package as follows:\n\n```shell\ngit clone https://github.com/oxwhirl/smac.git\ncd smac\npip install -e \".[dev]\"\npre-commit install\n```\n\nYou may also need to upgrade pip: `pip install --upgrade pip` for the install to work.\n\n## Installing StarCraft II\n\nSMAC is based on the full game of StarCraft II (versions \u003e= 3.16.1). To install the game, follow the commands bellow.\n\n### Linux\n\nPlease use the Blizzard's [repository](https://github.com/Blizzard/s2client-proto#downloads) to download the Linux version of StarCraft II. By default, the game is expected to be in `~/StarCraftII/` directory. This can be changed by setting the environment variable `SC2PATH`.\n\n### MacOS/Windows\n\nPlease install StarCraft II from [Battle.net](https://battle.net). The free [Starter Edition](http://battle.net/sc2/en/legacy-of-the-void/) also works. PySC2 will find the latest binary should you use the default install location. Otherwise, similar to the Linux version, you would need to set the `SC2PATH` environment variable with the correct location of the game.\n\n## SMAC maps\n\nSMAC is composed of many combat scenarios with pre-configured maps. Before SMAC can be used, these maps need to be downloaded into the `Maps` directory of StarCraft II.\n\nDownload the [SMAC Maps](https://github.com/oxwhirl/smac/releases/download/v0.1-beta1/SMAC_Maps.zip) and extract them to your `$SC2PATH/Maps` directory. If you installed SMAC via git, simply copy the `SMAC_Maps` directory from `smac/env/starcraft2/maps/` into `$SC2PATH/Maps` directory.\n\n### List the maps\n\nTo see the list of SMAC maps, together with the number of ally and enemy units and episode limit, run:\n\n```shell\npython -m smac.bin.map_list \n```\n\n### Creating new maps\n\nUsers can extend SMAC by adding new maps/scenarios. To this end, one needs to:\n\n- Design a new map/scenario using StarCraft II Editor:\n  - Please take a close look at the existing maps to understand the basics that we use (e.g. Triggers, Units, etc),\n  - We make use of special RL units which never automatically start attacking the enemy. [Here](https://docs.google.com/document/d/1BfAM_AtZWBRhUiOBcMkb_uK4DAZW3CpvO79-vnEOKxA/edit?usp=sharing) is the step-by-step guide on how to create new RL units based on existing SC2 units,\n- Add the map information in [smac_maps.py](https://github.com/oxwhirl/smac/blob/master/smac/env/starcraft2/maps/smac_maps.py),\n- The newly designed RL units have new ids which need to be handled in [starcraft2.py](https://github.com/oxwhirl/smac/blob/master/smac/env/starcraft2/starcraft2.py). Specifically, for heterogenious maps containing more than one unit types, one needs to manually set the unit ids in the `_init_ally_unit_types()` function.\n\n## Testing SMAC\n\nPlease run the following command to make sure that `smac` and its maps are properly installed. \n\n```bash\npython -m smac.examples.random_agents\n```\n\n## Saving and Watching StarCraft II Replays\n\n### Saving a replay\n\nIf you’ve using our [PyMARL](https://github.com/oxwhirl/pymarl) framework for multi-agent RL, here’s what needs to be done:\n1. **Saving models**: We run experiments on *Linux* servers with `save_model = True` (also `save_model_interval` is relevant) setting so that we have training checkpoints (parameters of neural networks) saved (click [here](https://github.com/oxwhirl/pymarl#saving-and-loading-learnt-models) for more details).\n2. **Loading models**: Learnt models can be loaded using the `checkpoint_path` parameter. If you run PyMARL on *MacOS* (or *Windows*) while also setting `save_replay=True`, this will save a .SC2Replay file for `test_nepisode` episodes on the test mode (no exploration) in the Replay directory of StarCraft II. (click [here](https://github.com/oxwhirl/pymarl#watching-starcraft-ii-replays) for more details).\n\nIf you want to save replays without using PyMARL, simply call the `save_replay()` function of SMAC's StarCraft2Env in your training/testing code. This will save a replay of all epsidoes since the launch of the StarCraft II client.\n\nThe easiest way to save and later watch a replay on Linux is to use [Wine](https://www.winehq.org/).\n\n### Watching a replay\n\nYou can watch the saved replay directly within the StarCraft II client on MacOS/Windows by *clicking on the corresponding Replay file*.\n\nYou can also watch saved replays by running:\n\n```shell\npython -m pysc2.bin.play --norender --replay \u003cpath-to-replay\u003e\n```\n\nThis works for any replay as long as the map can be found by the game. \n\nFor more information, please refer to [PySC2](https://github.com/deepmind/pysc2) documentation.\n\n# Documentation \n\nFor the detailed description of the environment, read the [SMAC documentation](docs/smac.md). \n\nThe initial results of our experiments using SMAC can be found in the [accompanying paper](https://arxiv.org/abs/1902.04043).\n\n# Citing  SMAC \n\nIf you use SMAC in your research, please cite the [SMAC paper](https://arxiv.org/abs/1902.04043).\n\n*M. Samvelyan, T. Rashid, C. Schroeder de Witt, G. Farquhar, N. Nardelli, T.G.J. Rudner, C.-M. Hung, P.H.S. Torr, J. Foerster, S. Whiteson. The StarCraft Multi-Agent Challenge, CoRR abs/1902.04043, 2019.*\n\nIn BibTeX format:\n\n```tex\n@article{samvelyan19smac,\n  title = {{The} {StarCraft} {Multi}-{Agent} {Challenge}},\n  author = {Mikayel Samvelyan and Tabish Rashid and Christian Schroeder de Witt and Gregory Farquhar and Nantas Nardelli and Tim G. J. Rudner and Chia-Man Hung and Philiph H. S. Torr and Jakob Foerster and Shimon Whiteson},\n  journal = {CoRR},\n  volume = {abs/1902.04043},\n  year = {2019},\n}\n```\n\n# Code Examples\n\nBelow is a small code example which illustrates how SMAC can be used. Here, individual agents execute random policies after receiving the observations and global state from the environment.  \n\nIf you want to try the state-of-the-art algorithms (such as [QMIX](https://arxiv.org/abs/1803.11485) and [COMA](https://arxiv.org/abs/1705.08926)) on SMAC, make use of [PyMARL](https://github.com/oxwhirl/pymarl) - our framework for MARL research.\n\n```python\nfrom smac.env import StarCraft2Env\nimport numpy as np\n\n\ndef main():\n    env = StarCraft2Env(map_name=\"8m\")\n    env_info = env.get_env_info()\n\n    n_actions = env_info[\"n_actions\"]\n    n_agents = env_info[\"n_agents\"]\n\n    n_episodes = 10\n\n    for e in range(n_episodes):\n        env.reset()\n        terminated = False\n        episode_reward = 0\n\n        while not terminated:\n            obs = env.get_obs()\n            state = env.get_state()\n            # env.render()  # Uncomment for rendering\n\n            actions = []\n            for agent_id in range(n_agents):\n                avail_actions = env.get_avail_agent_actions(agent_id)\n                avail_actions_ind = np.nonzero(avail_actions)[0]\n                action = np.random.choice(avail_actions_ind)\n                actions.append(action)\n\n            reward, terminated, _ = env.step(actions)\n            episode_reward += reward\n\n        print(\"Total reward in episode {} = {}\".format(e, episode_reward))\n\n    env.close()\n\n```\n\n## RLlib Examples\n\nYou can also run SMAC environments in [RLlib](https://rllib.io), which includes scalable algorithms such as [PPO](https://ray.readthedocs.io/en/latest/rllib-algorithms.html#proximal-policy-optimization-ppo) and [IMPALA](https://ray.readthedocs.io/en/latest/rllib-algorithms.html#importance-weighted-actor-learner-architecture-impala). Check out the example code [here](https://github.com/oxwhirl/smac/tree/master/smac/examples/rllib).\n\n## PettingZoo Example\n\nThanks to [Rodrigo de Lazcano](https://github.com/rodrigodelazcano), SMAC now supports [PettingZoo API](https://github.com/PettingZoo-Team/PettingZoo) and PyGame environment rendering. Check out the example code [here](https://github.com/oxwhirl/smac/tree/master/smac/examples/pettingzoo).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxwhirl%2Fsmac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxwhirl%2Fsmac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxwhirl%2Fsmac/lists"}