{"id":13424547,"url":"https://github.com/google-deepmind/pysc2","last_synced_at":"2025-05-14T00:10:54.789Z","repository":{"id":37335698,"uuid":"98336690","full_name":"google-deepmind/pysc2","owner":"google-deepmind","description":"StarCraft II Learning Environment","archived":false,"fork":false,"pushed_at":"2024-07-23T16:54:42.000Z","size":4571,"stargazers_count":8025,"open_issues_count":58,"forks_count":1157,"subscribers_count":349,"default_branch":"master","last_synced_at":"2024-10-29T15:02:22.196Z","etag":null,"topics":["blizzard-api","deepmind","machine-learning","reinforcement-learning","starcraft-ii","starcraft-ii-replays"],"latest_commit_sha":null,"homepage":"","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/google-deepmind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2017-07-25T18:16:57.000Z","updated_at":"2024-10-28T15:39:40.000Z","dependencies_parsed_at":"2023-09-07T20:34:55.114Z","dependency_job_id":"b6fc2cb7-2316-497c-82a9-ff4ab3ed78db","html_url":"https://github.com/google-deepmind/pysc2","commit_stats":{"total_commits":581,"total_committers":38,"mean_commits":"15.289473684210526","dds":"0.34595524956970736","last_synced_commit":"0df53d38c153972f1e368572ba65b1442a0fd41f"},"previous_names":["google-deepmind/pysc2","deepmind/pysc2"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fpysc2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fpysc2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fpysc2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fpysc2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google-deepmind","download_url":"https://codeload.github.com/google-deepmind/pysc2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247953862,"owners_count":21024102,"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":["blizzard-api","deepmind","machine-learning","reinforcement-learning","starcraft-ii","starcraft-ii-replays"],"created_at":"2024-07-31T00:00:56.029Z","updated_at":"2025-04-09T01:22:30.326Z","avatar_url":"https://github.com/google-deepmind.png","language":"Python","funding_links":[],"categories":["Frameworks","Python","APIs"],"sub_categories":["Python APIs"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=-fKUyT14G-8\"\n     target=\"_blank\"\u003e\n    \u003cimg src=\"http://img.youtube.com/vi/-fKUyT14G-8/0.jpg\"\n         alt=\"DeepMind open source PySC2 toolset for Starcraft II\"\n         width=\"240\" height=\"180\" border=\"10\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=6L448yg0Sm0\"\n     target=\"_blank\"\u003e\n    \u003cimg src=\"http://img.youtube.com/vi/6L448yg0Sm0/0.jpg\"\n         alt=\"StarCraft II 'mini games' for AI research\"\n         width=\"240\" height=\"180\" border=\"10\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=WEOzide5XFc\"\n     target=\"_blank\"\u003e\n    \u003cimg src=\"http://img.youtube.com/vi/WEOzide5XFc/0.jpg\"\n         alt=\"Trained and untrained agents play StarCraft II 'mini-game'\"\n         width=\"240\" height=\"180\" border=\"10\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n# PySC2 - StarCraft II Learning Environment\n\n[PySC2](https://github.com/deepmind/pysc2) is [DeepMind](http://deepmind.com)'s\nPython component of the StarCraft II Learning Environment (SC2LE). It exposes\n[Blizzard Entertainment](http://blizzard.com)'s [StarCraft II Machine Learning\nAPI](https://github.com/Blizzard/s2client-proto) as a Python RL Environment.\nThis is a collaboration between DeepMind and Blizzard to develop StarCraft II\ninto a rich environment for RL research. PySC2 provides an interface for RL\nagents to interact with StarCraft 2, getting observations and sending actions.\n\n\nWe have published an accompanying\n[blogpost](https://deepmind.com/blog/deepmind-and-blizzard-open-starcraft-ii-ai-research-environment/)\nand [paper](https://arxiv.org/abs/1708.04782), which outlines our\nmotivation for using StarCraft II for DeepRL research, and some initial research\nresults using the environment.\n\n## About\n\nDisclaimer: This is not an official Google product.\n\nIf you use the StarCraft II Machine Learning API and/or PySC2 in your research,\nplease cite the [StarCraft II Paper](https://arxiv.org/abs/1708.04782)\n\nYou can reach us at [pysc2@deepmind.com](mailto:pysc2@deepmind.com).\n\n\n# Quick Start Guide\n\n## Get PySC2\n\n### PyPI\n\nThe easiest way to get PySC2 is to use pip:\n\n```shell\n$ pip install pysc2\n```\n\nThat will install the `pysc2` package along with all the required dependencies.\n[virtualenv](https://pypi.python.org/pypi/virtualenv) can help manage your\ndependencies. You may also need to upgrade pip: `pip install --upgrade pip`\nfor the `pysc2` install to work. If you're running on an older system you may\nneed to install `libsdl` libraries for the `pygame` dependency.\n\nPip will install a few of the  binaries to your bin directory. `pysc2_play` can\nbe used as a shortcut to `python -m pysc2.bin.play`.\n\n### From Source\n\nAlternatively you can install latest PySC2 codebase from git master branch:\n\n```shell\n$ pip install --upgrade https://github.com/deepmind/pysc2/archive/master.zip\n```\n\nor from a local clone of the git repo:\n\n```shell\n$ git clone https://github.com/deepmind/pysc2.git\n$ pip install --upgrade pysc2/\n```\n\n## Get StarCraft II\n\nPySC2 depends on the full StarCraft II game and only works with versions that\ninclude the API, which is 3.16.1 and above.\n\n### Linux\n\nFollow Blizzard's [documentation](https://github.com/Blizzard/s2client-proto#downloads) to\nget the linux version. By default, PySC2 expects the game to live in\n`~/StarCraftII/`. You can override this path by setting the `SC2PATH`\nenvironment variable or creating your own run_config.\n\n### Windows/MacOS\n\nInstall of the game as normal from [Battle.net](https://battle.net). Even the\n[Starter Edition](http://battle.net/sc2/en/legacy-of-the-void/) will work.\nIf you used the default install location PySC2 should find the latest binary.\nIf you changed the install location, you might need to set the `SC2PATH`\nenvironment variable with the correct location.\n\nPySC2 should work on MacOS and Windows systems running Python 3.8+,\nbut has only been thoroughly tested on Linux. We welcome suggestions and patches\nfor better compatibility with other systems.\n\n## Get the maps\n\nPySC2 has many maps pre-configured, but they need to be downloaded into the SC2\n`Maps` directory before they can be played.\n\nDownload the [ladder maps](https://github.com/Blizzard/s2client-proto#downloads)\nand the [mini games](https://github.com/deepmind/pysc2/releases/download/v1.2/mini_games.zip)\nand extract them to your `StarCraftII/Maps/` directory.\n\n## Run an agent\n\nYou can run an agent to test the environment. The UI shows you the actions of\nthe agent and is helpful for debugging and visualization purposes.\n\n```shell\n$ python -m pysc2.bin.agent --map Simple64\n```\n\nIt runs a random agent by default, but you can specify others if you'd like,\nincluding your own.\n\n```shell\n$ python -m pysc2.bin.agent --map CollectMineralShards --agent pysc2.agents.scripted_agent.CollectMineralShards\n```\n\nYou can also run two agents against each other.\n\n```shell\n$ python -m pysc2.bin.agent --map Simple64 --agent2 pysc2.agents.random_agent.RandomAgent\n```\n\nTo specify the agent's race, the opponent's difficulty, and more, you can pass\nadditional flags. Run with `--help` to see what you can change.\n\n## Play the game as a human\n\nThere is a human agent interface which is mainly used for debugging, but it can\nalso be used to play the game. The UI is fairly simple and incomplete, but it's\nenough to understand the basics of the game. Also, it runs on Linux.\n\n```shell\n$ python -m pysc2.bin.play --map Simple64\n```\n\nIn the UI, hit `?` for a list of the hotkeys. The most basic ones are: `F4` to\nquit, `F5` to restart, `F8` to save a replay, and `Pgup`/`Pgdn` to control the\nspeed of the game. Otherwise use the mouse for selection and keyboard for\ncommands listed on the left.\n\nThe left side is a basic rendering. The right side is the feature layers that\nthe agent receives, with some coloring to make it more useful to us. You can\nenable or disable RGB or feature layer rendering and their resolutions with\ncommand-line flags.\n\n## Watch a replay\n\nRunning an agent and playing as a human save a replay by default. You can watch\nthat replay by running:\n\n```shell\n$ python -m pysc2.bin.play --replay \u003cpath-to-replay\u003e\n```\n\nThis works for any replay as long as the map can be found by the game.\n\nThe same controls work as for playing the game, so `F4` to exit, `pgup`/`pgdn`\nto control the speed, etc.\n\nYou can save a video of the replay with the `--video` flag.\n\n## List the maps\n\n[Maps](docs/maps.md) need to be configured before they're known to the\nenvironment. You can see the list of known maps by running:\n\n```shell\n$ python -m pysc2.bin.map_list\n```\n\n## Run the tests\n\nIf you want to submit a pull request, please make sure the tests pass on both\npython 2 and 3.\n\n```shell\n$ python -m pysc2.bin.run_tests\n```\n\n# Environment Details\n\nFor a full description of the specifics of how the environment is configured,\nthe observations and action spaces work read the\n[environment documentation](docs/environment.md).\n\nNote that an alternative to this environment is now available which provides\nan enriched action and observation format using the C++ wrappers developed\nfor AlphaStar. See [the converter documentation](docs/converters.md) for more\ninformation.\n\n# Mini-game maps\n\nThe mini-game map files referenced in the paper are stored under `pysc2/maps/`\nbut must be installed in `$SC2PATH/Maps`. Make sure to follow the download\ninstructions above.\n\nMaps are configured in the Python files in `pysc2/maps/`. The configs can set\nplayer and time limits, whether to use the game outcome or curriculum score, and\na handful of other things. For more information about the maps, and how to\nconfigure your own, read the [maps documentation](docs/maps.md).\n\n# Replays\n\nA replay lets you review what happened during a game. You can see the actions\nand observations that each player made as they played.\n\nBlizzard is releasing a large number of anonymized 1v1 replays played on the\nladder. You can find instructions for how to get the\n[replay files](https://github.com/Blizzard/s2client-proto#downloads) on their\nsite. You can also review your own replays.\n\nReplays can be played back to get the observations and actions made during that\ngame. The observations are rendered at the resolution you request, so may differ\nfrom what the human actually saw. Similarly the actions specify a point, which\ncould reflect a different pixel on the human's screen, so may not have an exact\nmatch in our observations, though they should be fairly similar.\n\nReplays are version dependent, so a 3.16 replay will fail in a 3.16.1 or 3.17\nbinary.\n\nYou can visualize the replays with the full game, or with `pysc2.bin.play`.\nAlternatively you can run `pysc2.bin.replay_actions` to process many replays\nin parallel.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fpysc2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle-deepmind%2Fpysc2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fpysc2/lists"}