[
{
"path": ".gitignore",
"content": "*.pyc\n*_pb2.py\n"
},
{
"path": "CONTRIBUTING.md",
"content": "Want to contribute? Great! First, read this page (including the small print at\nthe end).\n\n### Before you contribute\n\nBefore we can use your code, you must sign the\n[Google Individual Contributor License Agreement]\n(https://cla.developers.google.com/about/google-individual)\n(CLA), which you can do online. The CLA is necessary mainly because you own the\ncopyright to your changes, even after your contribution becomes part of our\ncodebase, so we need your permission to use and distribute your code. We also\nneed to be sure of various other things—for instance that you'll tell us if you\nknow that your code infringes on other people's patents. You don't have to sign\nthe CLA until after you've submitted your code for review and a member has\napproved it, but you must do it before we can put your code into our codebase.\nBefore you start working on a larger contribution, you should get in touch with\nus first through the issue tracker with your idea so that we can help out and\npossibly guide you. Coordinating up front makes it much easier to avoid\nfrustration later on.\n\n### Code reviews\n\nAll submissions, including submissions by project members, require review. We\nuse Github pull requests for this purpose.\n\n### The small print\n\nContributions made by corporations are covered by a different agreement than\nthe one above, the\n[Software Grant and Corporate Contributor License Agreement]\n(https://cla.developers.google.com/about/google-corporate).\n"
},
{
"path": "LICENSE",
"content": "\n Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright 2017 Google Inc.\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n"
},
{
"path": "README.md",
"content": "\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 \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"
},
{
"path": "WORKSPACE",
"content": "workspace(name = \"pysc2\")\n\nload(\"@bazel_tools//tools/build_defs/repo:http.bzl\", \"http_archive\")\n\nload(\"//bazel:create_external_repos.bzl\", \"pysc2_create_external_repos\")\npysc2_create_external_repos(pysc2_repo_name = \"pysc2\")\n\nload(\"//bazel:setup_external_repos.bzl\", \"pysc2_setup_external_repos\")\npysc2_setup_external_repos()\n\nbind(\n name = \"python_headers\",\n actual = \"@local_config_python//:python_headers\",\n)\n\nhttp_archive(\n name = \"bazel_skylib\",\n strip_prefix = \"bazel-skylib-main\",\n urls = [\"https://github.com/bazelbuild/bazel-skylib/archive/main.zip\"],\n)\n\nhttp_archive(\n name = \"rules_python\",\n url = \"https://github.com/bazelbuild/rules_python/releases/download/0.4.0/rules_python-0.4.0.tar.gz\",\n sha256 = \"954aa89b491be4a083304a2cb838019c8b8c3720a7abb9c4cb81ac7a24230cea\",\n)\n\nload(\"@rules_python//python:pip.bzl\", \"pip_install\")\n\nhttp_archive(\n name = \"rules_cc\",\n urls = [\"https://github.com/bazelbuild/rules_cc/archive/68cb652a71e7e7e2858c50593e5a9e3b94e5b9a9.zip\"],\n strip_prefix = \"rules_cc-68cb652a71e7e7e2858c50593e5a9e3b94e5b9a9\",\n sha256 = \"1e19e9a3bc3d4ee91d7fcad00653485ee6c798efbbf9588d40b34cbfbded143d\",\n)\nload(\"@rules_cc//cc:repositories.bzl\", \"rules_cc_dependencies\")\nrules_cc_dependencies()\n\n# Create a central external repo, @my_deps, that contains Bazel targets for all the\n# third-party packages specified in the requirements.txt file.\npip_install(\n name = \"my_deps\",\n requirements = \"@//bazel:requirements.txt\",\n)\n\nhttp_archive(\n name = \"rules_proto\",\n sha256 = \"66bfdf8782796239d3875d37e7de19b1d94301e8972b3cbd2446b332429b4df1\",\n strip_prefix = \"rules_proto-4.0.0\",\n urls = [\n \"https://mirror.bazel.build/github.com/bazelbuild/rules_proto/archive/refs/tags/4.0.0.tar.gz\",\n \"https://github.com/bazelbuild/rules_proto/archive/refs/tags/4.0.0.tar.gz\",\n ],\n)\nload(\"@rules_proto//proto:repositories.bzl\", \"rules_proto_dependencies\", \"rules_proto_toolchains\")\nrules_proto_dependencies()\nrules_proto_toolchains()\n\n# C++ dependencies.\nhttp_archive(\n name = \"com_google_googletest\",\n sha256 = \"ff7a82736e158c077e76188232eac77913a15dac0b22508c390ab3f88e6d6d86\",\n strip_prefix = \"googletest-b6cd405286ed8635ece71c72f118e659f4ade3fb\",\n urls = [\n \"https://storage.googleapis.com/mirror.tensorflow.org/github.com/google/googletest/archive/b6cd405286ed8635ece71c72f118e659f4ade3fb.zip\",\n \"https://github.com/google/googletest/archive/b6cd405286ed8635ece71c72f118e659f4ade3fb.zip\",\n ],\n)\n\nhttp_archive(\n name = \"com_google_absl\",\n sha256 = \"35f22ef5cb286f09954b7cc4c85b5a3f6221c9d4df6b8c4a1e9d399555b366ee\", # SHARED_ABSL_SHA\n strip_prefix = \"abseil-cpp-997aaf3a28308eba1b9156aa35ab7bca9688e9f6\",\n urls = [\n \"https://storage.googleapis.com/mirror.tensorflow.org/github.com/abseil/abseil-cpp/archive/997aaf3a28308eba1b9156aa35ab7bca9688e9f6.tar.gz\",\n \"https://github.com/abseil/abseil-cpp/archive/997aaf3a28308eba1b9156aa35ab7bca9688e9f6.tar.gz\",\n ],\n)\n"
},
{
"path": "bazel/BUILD",
"content": "licenses([\"notice\"])\n\nexports_files(\n [\n \"BUILD.dm_env\",\n \"BUILD.dm_env_rpc\",\n \"BUILD.s2protocol\",\n \"protobuf.patch\",\n \"requirements.txt\",\n \"s2clientprotocol.patch\",\n ],\n visibility = [\"//visibility:public\"],\n)\n"
},
{
"path": "bazel/BUILD.dm_env",
"content": "load(\"@my_deps//:requirements.bzl\", \"requirement\")\n\nlicenses([\"notice\"])\n\npy_library(\n name = \"dm_env\",\n srcs = [\n \"dm_env/__init__.py\",\n \"dm_env/_environment.py\",\n \"dm_env/_metadata.py\",\n ],\n visibility = [\"//visibility:public\"],\n deps = [\n \"@dm_env_archive//:specs\",\n ],\n)\n\npy_library(\n name = \"specs\",\n srcs = [\n \"dm_env/specs.py\",\n ],\n visibility = [\"//visibility:public\"],\n)\n\npy_library(\n name = \"test_utils\",\n srcs = [\n \"dm_env/_abstract_test_mixin.py\",\n \"dm_env/test_utils.py\",\n ],\n deps = [\n requirement(\"dm-tree\"),\n ],\n visibility = [\"//visibility:public\"],\n)\n"
},
{
"path": "bazel/BUILD.dm_env_rpc",
"content": "load(\"@com_github_grpc_grpc//bazel:python_rules.bzl\", \"py_proto_library\")\n\nlicenses([\"notice\"])\n\nproto_library(\n name = \"dm_env_rpc_proto\",\n srcs = [\"dm_env_rpc/v1/dm_env_rpc.proto\"],\n visibility = [\"//visibility:public\"],\n deps = [\n \"@com_google_googleapis//google/rpc:status_proto\",\n \"@com_google_protobuf//:any_proto\",\n ],\n)\n\ncc_proto_library(\n name = \"dm_env_rpc_cc_proto\",\n visibility = [\"//visibility:public\"],\n deps = [\":dm_env_rpc_proto\"],\n)\n\npy_proto_library(\n name = \"dm_env_rpc_pb2\",\n deps = [\"@dm_env_rpc_archive//:dm_env_rpc_proto\"],\n)\n\npy_proto_library(\n name = \"status_pb2\",\n deps = [\"@com_google_googleapis//google/rpc:status_proto\"],\n)\n\npy_library(\n name = \"dm_env_rpc\",\n srcs = glob([\"dm_env_rpc/**/*.py\"]),\n visibility = [\"//visibility:public\"],\n deps = [\n \":dm_env_rpc_pb2\",\n \":status_pb2\",\n ],\n)\n"
},
{
"path": "bazel/BUILD.s2protocol",
"content": "licenses([\"notice\"])\n\npy_library(\n name = \"s2protocol\",\n srcs = [\n \"s2protocol/__init__.py\",\n \"s2protocol/attributes.py\",\n \"s2protocol/build.py\",\n \"s2protocol/compat.py\",\n \"s2protocol/decoders.py\",\n \"s2protocol/encoders.py\",\n \"s2protocol/namespaces.py\",\n ],\n visibility = [\"//visibility:public\"],\n)\n\npy_library(\n name = \"versions\",\n srcs = glob([\"s2protocol/versions/*.py\"]) + [\"s2protocol/__init__.py\"],\n visibility = [\"//visibility:public\"],\n deps = [\":s2protocol\"],\n)\n"
},
{
"path": "bazel/create_external_repos.bzl",
"content": "# Copyright 2021 DeepMind Technologies Ltd. All rights reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Creates external repos needed by PySC2 and by its consumers.\"\"\"\n\nload(\"@bazel_tools//tools/build_defs/repo:http.bzl\", \"http_archive\")\n\ndef pysc2_create_external_repos(pysc2_repo_name):\n \"\"\"Creates external repos needed by PySC2 and by its consumers.\n\n Args:\n pysc2_repo_name: The name of the PySC2 repo, as instantiated in\n the local WORKSPACE. When executing this function from the pysc2\n WORKSPACE, this name is \"pysc2\". But external consumers shouldn't\n use that name as it leads to Python import problems due to the\n pysc2/pysc2 subdirectory. Hence a name such as \"pysc2_archive\"\n is recommended.\n\n Example:\n http_archive(\n name = \"pysc2_archive\",\n # ...\n )\n\n load(\"@pysc2_archive//bazel:create_external_repos.bzl\",\n \"pysc2_create_external_repos\")\n pysc2_create_external_repos(pysc2_repo_name = \"pysc2_archive\")\n \"\"\"\n\n if not native.existing_rule(\"absl_py\"):\n # It is important that this isn't named simply 'absl' as the project has a\n # subdirectory named that, and Python module lookup fails if we have absl/absl.\n http_archive(\n name = \"absl_py\",\n strip_prefix = \"abseil-py-main\",\n urls = [\"https://github.com/abseil/abseil-py/archive/main.zip\"],\n )\n\n # Required by glog.\n if not native.existing_rule(\"com_github_gflags_gflags\"):\n http_archive(\n name = \"com_github_gflags_gflags\",\n sha256 = \"34af2f15cf7367513b352bdcd2493ab14ce43692d2dcd9dfc499492966c64dcf\",\n strip_prefix = \"gflags-2.2.2\",\n urls = [\n \"https://github.com/gflags/gflags/archive/v2.2.2.tar.gz\",\n ],\n )\n\n if not native.existing_rule(\"glog\"):\n http_archive(\n name = \"glog\",\n sha256 = \"6281aa4eeecb9e932d7091f99872e7b26fa6aacece49c15ce5b14af2b7ec050f\",\n urls = [\n \"https://github.com/google/glog/archive/96a2f23dca4cc7180821ca5f32e526314395d26a.zip\",\n ],\n strip_prefix = \"glog-96a2f23dca4cc7180821ca5f32e526314395d26a\",\n )\n\n if not native.existing_rule(\"com_google_protobuf\"):\n http_archive(\n name = \"com_google_protobuf\",\n patches = [\"@\" + pysc2_repo_name + \"//bazel:protobuf.patch\"],\n urls = [\"https://github.com/protocolbuffers/protobuf/archive/refs/tags/v3.19.1.zip\"],\n strip_prefix = \"protobuf-3.19.1\",\n )\n\n if not native.existing_rule(\"com_google_googleapis\"):\n http_archive(\n name = \"com_google_googleapis\",\n sha256 = \"1f742f6cafe616fe73302db010e0b7ee6579cb1ce06010427b7d0995cbd80ce4\",\n strip_prefix = \"googleapis-6a813acf535e4746fa4a135ce23547bb6425c26d\",\n urls = [\n \"https://github.com/googleapis/googleapis/archive/6a813acf535e4746fa4a135ce23547bb6425c26d.tar.gz\",\n ],\n )\n\n if not native.existing_rule(\"pybind11_bazel\"):\n http_archive(\n name = \"pybind11_bazel\",\n strip_prefix = \"pybind11_bazel-master\",\n urls = [\"https://github.com/pybind/pybind11_bazel/archive/refs/heads/master.zip\"],\n )\n\n if not native.existing_rule(\"pybind11\"):\n http_archive(\n name = \"pybind11\",\n build_file = \"@pybind11_bazel//:pybind11.BUILD\",\n strip_prefix = \"pybind11-2.8.1\",\n urls = [\"https://github.com/pybind/pybind11/archive/v2.8.1.tar.gz\"],\n )\n\n if not native.existing_rule(\"s2client_proto\"):\n http_archive(\n name = \"s2client_proto\",\n urls = [\"https://github.com/Blizzard/s2client-proto/archive/refs/heads/master.zip\"],\n strip_prefix = \"s2client-proto-master\",\n patches = [\"@\" + pysc2_repo_name + \"//bazel:s2clientprotocol.patch\"],\n )\n\n if not native.existing_rule(\"s2protocol_archive\"):\n http_archive(\n name = \"s2protocol_archive\",\n urls = [\"https://github.com/Blizzard/s2protocol/archive/refs/heads/master.zip\"],\n strip_prefix = \"s2protocol-master\",\n build_file = \"@\" + pysc2_repo_name + \"//bazel:BUILD.s2protocol\",\n )\n\n if not native.existing_rule(\"dm_env_archive\"):\n # We can't use the wheels for dm_env because that pulls in\n # proto code which leads to incompatibilities with our our protos.\n http_archive(\n name = \"dm_env_archive\",\n urls = [\"https://github.com/deepmind/dm_env/archive/refs/heads/master.zip\"],\n strip_prefix = \"dm_env-master\",\n build_file = \"@\" + pysc2_repo_name + \"//bazel:BUILD.dm_env\",\n )\n\n if not native.existing_rule(\"dm_env_rpc_archive\"):\n # We can't use the wheels for dm_env_rpc because that pulls in\n # proto code which leads to incompatibilities with our our protos.\n http_archive(\n name = \"dm_env_rpc_archive\",\n urls = [\"https://github.com/deepmind/dm_env_rpc/archive/refs/heads/master.zip\"],\n strip_prefix = \"dm_env_rpc-master\",\n build_file = \"@\" + pysc2_repo_name + \"//bazel:BUILD.dm_env_rpc\",\n )\n\n if not native.existing_rule(\"com_github_grpc_grpc\"):\n http_archive(\n name = \"com_github_grpc_grpc\",\n strip_prefix = \"grpc-master\",\n urls = [\"https://github.com/grpc/grpc/archive/refs/heads/master.zip\"],\n )\n"
},
{
"path": "bazel/protobuf.patch",
"content": "--- BUILD\n+++ BUILD\n@@ -889,6 +889,8 @@\n \"//conditions:default\": [],\n \":use_fast_cpp_protos\": [\"//external:python_headers\"],\n }),\n+\n+ visibility = [\"//visibility:public\"],\n )\n \n config_setting(\n"
},
{
"path": "bazel/requirements.txt",
"content": "deepdiff\ndm-tree\nmock\nmpyq\nnumpy>=1.10.0\nportpicker>=1.2.0\npsutil\npygame\nrequests\ns2protocol\nsk-video\ntyping-extensions\nwebsocket-client\n"
},
{
"path": "bazel/s2clientprotocol.patch",
"content": "+++ s2clientprotocol/BUILD\t2021-11-18 12:14:07.885666323 +0000\n@@ -0,0 +1,255 @@\n+load(\"@com_github_grpc_grpc//bazel:python_rules.bzl\", \"py_proto_library\")\n+\n+package(default_visibility = [\"//visibility:public\"])\n+\n+proto_library(\n+ name = \"common_proto\",\n+ srcs = [\"common.proto\"],\n+)\n+\n+cc_proto_library(\n+ name = \"common_cc_proto\",\n+ deps = [\":common_proto\"],\n+)\n+\n+py_proto_library(\n+ name = \"common_pb2\",\n+ deps = [\":common_proto\"],\n+)\n+\n+py_library(\n+ name = \"common_py_pb2\",\n+ deps = [\":common_pb2\"],\n+)\n+\n+proto_library(\n+ name = \"data_proto\",\n+ srcs = [\"data.proto\"],\n+ deps = [\":common_proto\"],\n+)\n+\n+cc_proto_library(\n+ name = \"data_cc_proto\",\n+ deps = [\":data_proto\"],\n+)\n+\n+py_proto_library(\n+ name = \"data_pb2\",\n+ deps = [\":data_proto\"],\n+)\n+\n+py_library(\n+ name = \"data_py_pb2\",\n+ deps = [\n+ \":common_pb2\",\n+ \":data_pb2\",\n+ ],\n+)\n+\n+proto_library(\n+ name = \"debug_proto\",\n+ srcs = [\"debug.proto\"],\n+ deps = [\":common_proto\"],\n+)\n+\n+cc_proto_library(\n+ name = \"debug_cc_proto\",\n+ deps = [\":debug_proto\"],\n+)\n+\n+py_proto_library(\n+ name = \"debug_pb2\",\n+ deps = [\":debug_proto\"],\n+)\n+\n+py_library(\n+ name = \"debug_py_pb2\",\n+ deps = [\n+ \":common_pb2\",\n+ \":debug_pb2\",\n+ ],\n+)\n+\n+proto_library(\n+ name = \"error_proto\",\n+ srcs = [\"error.proto\"],\n+)\n+\n+cc_proto_library(\n+ name = \"error_cc_proto\",\n+ deps = [\":error_proto\"],\n+)\n+\n+py_proto_library(\n+ name = \"error_pb2\",\n+ deps = [\":error_proto\"],\n+)\n+\n+py_library(\n+ name = \"error_py_pb2\",\n+ deps = [\n+ \":error_pb2\",\n+ ],\n+)\n+\n+proto_library(\n+ name = \"query_proto\",\n+ srcs = [\"query.proto\"],\n+ deps = [\n+ \":common_proto\",\n+ \":error_proto\",\n+ ],\n+)\n+\n+cc_proto_library(\n+ name = \"query_cc_proto\",\n+ deps = [\":query_proto\"],\n+)\n+\n+py_proto_library(\n+ name = \"query_pb2\",\n+ deps = [\":query_proto\"],\n+)\n+\n+py_library(\n+ name = \"query_py_pb2\",\n+ deps = [\n+ \":common_pb2\",\n+ \":error_pb2\",\n+ \":query_pb2\",\n+ ],\n+)\n+\n+proto_library(\n+ name = \"raw_proto\",\n+ srcs = [\"raw.proto\"],\n+ deps = [\":common_proto\"],\n+)\n+\n+cc_proto_library(\n+ name = \"raw_cc_proto\",\n+ deps = [\":raw_proto\"],\n+)\n+\n+py_proto_library(\n+ name = \"raw_pb2\",\n+ deps = [\":raw_proto\"],\n+)\n+\n+py_library(\n+ name = \"raw_py_pb2\",\n+ deps = [\n+ \":common_pb2\",\n+ \":raw_pb2\",\n+ ],\n+)\n+\n+proto_library(\n+ name = \"sc2api_proto\",\n+ srcs = [\"sc2api.proto\"],\n+ deps = [\n+ \":common_proto\",\n+ \":data_proto\",\n+ \":debug_proto\",\n+ \":error_proto\",\n+ \":query_proto\",\n+ \":raw_proto\",\n+ \":score_proto\",\n+ \":spatial_proto\",\n+ \":ui_proto\",\n+ ],\n+)\n+\n+cc_proto_library(\n+ name = \"sc2api_cc_proto\",\n+ deps = [\":sc2api_proto\"],\n+)\n+\n+py_proto_library(\n+ name = \"sc2api_pb2\",\n+ deps = [\":sc2api_proto\"],\n+)\n+\n+py_library(\n+ name = \"sc2api_py_pb2\",\n+ deps = [\n+ \":common_pb2\",\n+ \":data_pb2\",\n+ \":debug_pb2\",\n+ \":error_pb2\",\n+ \":query_pb2\",\n+ \":raw_pb2\",\n+ \":sc2api_pb2\",\n+ \":score_pb2\",\n+ \":spatial_pb2\",\n+ \":ui_pb2\",\n+ ],\n+)\n+\n+proto_library(\n+ name = \"score_proto\",\n+ srcs = [\"score.proto\"],\n+)\n+\n+cc_proto_library(\n+ name = \"score_cc_proto\",\n+ deps = [\":score_proto\"],\n+)\n+\n+py_proto_library(\n+ name = \"score_pb2\",\n+ deps = [\":score_proto\"],\n+)\n+\n+py_library(\n+ name = \"score_py_pb2\",\n+ deps = [\n+ \":score_pb2\",\n+ ],\n+)\n+\n+proto_library(\n+ name = \"spatial_proto\",\n+ srcs = [\"spatial.proto\"],\n+ deps = [\":common_proto\"],\n+)\n+\n+cc_proto_library(\n+ name = \"spatial_cc_proto\",\n+ deps = [\":spatial_proto\"],\n+)\n+\n+py_proto_library(\n+ name = \"spatial_pb2\",\n+ deps = [\":spatial_proto\"],\n+)\n+\n+py_library(\n+ name = \"spatial_py_pb2\",\n+ deps = [\n+ \":common_pb2\",\n+ \":spatial_pb2\",\n+ ],\n+)\n+\n+proto_library(\n+ name = \"ui_proto\",\n+ srcs = [\"ui.proto\"],\n+)\n+\n+cc_proto_library(\n+ name = \"ui_cc_proto\",\n+ deps = [\":ui_proto\"],\n+)\n+\n+py_proto_library(\n+ name = \"ui_pb2\",\n+ deps = [\":ui_proto\"],\n+)\n+\n+py_library(\n+ name = \"ui_py_pb2\",\n+ deps = [\n+ \":ui_pb2\",\n+ ],\n+)\n\n+++ WORKSPACE\t2021-11-18 12:14:07.885666323 +0000\n@@ -0,0 +1,21 @@\n+workspace(name = \"s2client-proto\")\n+\n+load(\"@bazel_tools//tools/build_defs/repo:git.bzl\", \"git_repository\")\n+\n+# The protobuf library, for protoc.\n+git_repository(\n+ name = \"com_google_protobuf\",\n+ remote = \"https://github.com/protocolbuffers/protobuf\",\n+ branch = \"master\",\n+)\n+load(\"@com_google_protobuf//:protobuf_deps.bzl\", \"protobuf_deps\")\n+protobuf_deps()\n+\n+# GRPC, for the py_proto_library rule.\n+git_repository(\n+ name = \"com_github_grpc_grpc\",\n+ remote = \"https://github.com/grpc/grpc.git\",\n+ branch = \"master\",\n+)\n+load(\"@com_github_grpc_grpc//bazel:grpc_deps.bzl\", \"grpc_deps\")\n+grpc_deps()\n"
},
{
"path": "bazel/setup_external_repos.bzl",
"content": "# Copyright 2021 DeepMind Technologies Ltd. All rights reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Sets up external repos needed by PySC2 and by its consumers.\"\"\"\n\nload(\"@com_google_googleapis//:repository_rules.bzl\", \"switched_rules_by_language\")\nload(\"@com_github_grpc_grpc//bazel:grpc_deps.bzl\", \"grpc_deps\")\nload(\"@com_google_protobuf//:protobuf_deps.bzl\", \"protobuf_deps\")\nload(\"@pybind11_bazel//:python_configure.bzl\", \"python_configure\")\n\ndef pysc2_setup_external_repos():\n \"\"\"Sets up external repos needed by PySC2 and by its consumers.\n\n Ideally these would happen as part of pysc2_deps, but load statements are\n only permitted at the top level currently, necessitating this workaround.\n \"\"\"\n protobuf_deps()\n switched_rules_by_language(\n name = \"com_google_googleapis_imports\",\n cc = True,\n python = True,\n )\n python_configure(name = \"local_config_python\")\n grpc_deps()\n"
},
{
"path": "docs/bazel.md",
"content": "# Building with Bazel\n\nPrior to the inclusion of C++ code it was sufficient to install the\n[pip](https://pypi.org/project/pip/) dependencies of PySC2 and to execute the\nPython code directly using the Python interpreter. This is still possible if\ninstalling from a [wheel](https://pypi.org/project/wheel/) with a pre-built\ndistribution matching the platform on which you are running, else when not\nreferencing any of the C++ code. Where that is not the case, or where you would\nlike to make changes to the C++ code, a build system becomes necessary. We\nsupport the use of [Bazel](https://bazel.build/), Google's open-source build\ntool, for this purpose.\n\n## Supported platforms\n\nWe support building with Bazel on Ubuntu Linux with C++ 17. In future we may\nsupport other platforms, should there be demand.\n\n## Example\n\nFirst of all,\n[get Bazel](https://docs.bazel.build/versions/main/install-ubuntu.html). Next,\nyou may need the Python development environment.\n\n```shell\n$ sudo apt update\n$ sudo apt install python3 python3-dev python3-venv\n```\n\nBuild all PySC2 targets (from the workspace root).\n\n```shell\n$ bazel build --cxxopt='-std=c++17' ...\n```\n\nRun some tests.\n\n```shell\n$ bazel test --cxxopt='-std=c++17' pysc2/lib/...\n```\n\nBeyond that, everything should be the same as running Python directly as\ndescribed in the readme, only rather than using the Python interpreter you use\nBazel to run. For instance...\n\n```shell\n$ python -m pysc2.bin.agent --map Simple64\n```\n\nbecomes...\n\n```shell\n$ bazel run --cxxopt='-std=c++17' pysc2/bin:agent -- --map Simple64\n```\n\nYou may wish to use a [.bazelrc file](https://docs.bazel.build/versions/main/guide.html#bazelrc-the-bazel-configuration-file) to avoid the need to repeatedly specify command-line options, for instance `--cxxopt='-std=c++17'`.\n"
},
{
"path": "docs/converters.md",
"content": "# Environment converters\n\n## Overview\n\nThe SC2 API uses protos to communicate actions to and observations from the\nenvironment. `sc2_env.py` contains code to marshall between these protos and a\nmore neural network friendly dictionary of numpy arrays, with accompanying\nenvironment specs. During development of AlphaStar this code was translated to\nC++, and new features added. This code is now available in PySC2. See\n`converter.cc`, `converter.py`, `converted_env.py`, `replay_converter.py`, for\ninstance.\n\nConverters are instantiated per-agent, per-episode. They are configurable via\nthe `ConverterSettings` proto; see `converter.proto`. Though they can be used\ndirectly, it is more typical to use them as part of an environment wrapper\n(`converted_env.py`), or via the replay conversion code (`replay_converter.py`).\n\nNote that converters don't have to be used from Python. The C++ code is wrapped\nusing [pybind11](https://github.com/pybind/pybind11), but may also be used\ndirectly.\n\nNote also that, because converters are implemented in C++, changes to them\nrequire compilation. See [this page](bazel.md) for further information.\n\n## Supported platforms\n\nUse of converters requires either [building with Bazel](bazel.md) or use of an\nappropriate pre-built wheel. Only Linux is supported at present.\n\n## Raw mode\n\nIf raw settings are provided as part of the converter settings the converter\nwill operate in raw mode. This mode is so called because it provides raw access\nto numerical data, with only limited spatial data for the minimap. Actions are\nspecified directly for units using their tags. There is support for limiting the\ndata which the agent receives to the view implied by the current camera\nposition, similar to how humans perceive the game.\n\n### Action spec\n\nname | shape | dtype | min | max | enabled?\n--------------- | -------------------------------- | ----- | --- | ------------------------------------------- | --------\nfunction | () | int32 | 0 | `num_action_types` | always\ndelay | () | int32 | 1 | 127 | always\nqueued | () | int32 | 0 | 1 | always\nrepeat | () | int32 | 0 | 2 | `raw.enable_action_repeat`\ntarget_unit_tag | () | int32 | 0 | `raw.max_unit_count` - 1 | always\nunit_tags | (`raw.max_unit_selection_size`,) | int32 | 0 | `raw.max_unit_count` | always\nworld | () | int32 | 0 | `raw.resolution.x` * `raw.resolution.y` - 1 | always\n\n### Observation spec\n\nname | shape | dtype | min | max | enabled?\n------------------------------ | ------------------------------------------- | ----- | --------- | ------------------------------------------- | --------\naction/function | () | int32 | 0 | `num_action_types` | `supervised`\naction/delay | () | int32 | 1 | 127 | `supervised`\naction/queued | () | int32 | 0 | 1 | `supervised`\naction/repeat | () | int32 | 0 | 2 | `supervised` and `raw.enable_action_repeat`\naction/target_unit_tag | () | int32 | 1 | `raw.max_unit_count` - 1 | `supervised`\naction/unit_tags | (`raw.max_unit_selection_size`,) | int32 | 0 | `raw.max_unit_count` | `supervised`\naction/world | () | int32 | 0 | `raw.resolution.x` * `raw.resolution.y` - 1 | `supervised`\naway_race_observed | () | int32 | - | - | always\naway_race_requested | () | int32 | - | - | always\ncamera | (`raw.resolution.x`, `raw.resolution.y`) | int32 | 0 | 1 | `raw.camera`\ncamera_position | (2,) | int32 | - | - | `raw.use_camera_position`\ncamera_size | (2,) | int32 | - | - | `raw.use_camera_position`\ngame_loop | () | int32 | - | - | always\nhome_race_requested | () | int32 | - | - | always\nminimap_alerts | (`minimap.x`, `minimap.y`) | uint8 | 0 | 1 | 'alerts' in `minimap features`\nminimap_buildable | (`minimap.x`, `minimap.y`) | uint8 | 0 | 1 | 'buildable' in `minimap features`\nminimap_creep | (`minimap.x`, `minimap.y`) | uint8 | 0 | 1 | 'creep' in `minimap features`\nminimap_height_map | (`minimap.x`, `minimap.y`) | uint8 | 0 | 255 | 'height_map' in `minimap features`\nminimap_pathable | (`minimap.x`, `minimap.y`) | uint8 | 0 | 1 | 'pathable' in `minimap features`\nminimap_player_relative | (`minimap.x`, `minimap.y`) | uint8 | 0 | 4 | 'player_relative' in `minimap features`\nminimap_visibility_map | (`minimap.x`, `minimap.y`) | uint8 | 0 | 3 | 'visibility_map' in `minimap features`\nmmr | () | int32 | - | - | always\nopponent_player | (10,) | int32 | - | - | `add_opponent_features`\nopponent_unit_counts_bow | (`num_unit_types`,) | int32 | - | - | `add_opponent_features`\nopponent_upgrades_fixed_length | (`max_num_upgrades`,) | int32 | 0 | `num_upgrade_types + 1` | `add_opponent_features`\nplayer | (11,) | int32 | - | - | always\nraw_units | (`max_unit_count`, `num_unit_features` + 2) | int32 | 0 | varies | always\nunit_counts_bow | (`num_unit_types`,) | int32 | - | - | always\nupgrades_fixed_length | (`max_num_upgrades`,) | int32 | minimum=0 | maximum=`num_upgrade_types` + 1 | always\n\n## Visual mode\n\nIf visual settings are provided as part of the converter settings the converter\nwill operate in visual mode. In this mode the majority of the data provided to\nthe agent is represented spatially, with planes reflecting the attributes of\nunits on the screen and minimap. Actions in this mode are more similar to how a\nhuman would interact, point-and-click.\n\n### Action spec\n\n| name | shape | dtype | min | max | enabled? |\n| ----------------- | ----- | ----- | --- | ------------------- | -------- |\n| function | () | int32 | 0 | `num_action_types` | always |\n| build_queue_id | () | int32 | 0 | 9 | always |\n| control_group_act | () | int32 | 0 | 4 | always |\n| control_group_id | () | int32 | 0 | 9 | always |\n| delay | () | int32 | 1 | 127 | always |\n| minimap | () | int32 | 0 | `minimap.x` * | always |\n: : : : : `minimap.y` - 1 : :\n| queued | () | int32 | 0 | 1 | always |\n| screen | () | int32 | 0 | `visual.screen.x` * | always |\n: : : : : `visual.screen.y` - : :\n: : : : : 1 : :\n| screen2 | () | int32 | 0 | `visual.screen.x` * | always |\n: : : : : `visual.screen.y` - : :\n: : : : : 1 : :\n| select_add | () | int32 | 0 | 1 | always |\n| select_point_act | () | int32 | 0 | 3 | always |\n| select_unit_act | () | int32 | 0 | 3 | always |\n| select_unit_id | () | int32 | 0 | 499 | always |\n| select_worker | () | int32 | 0 | 3 | always |\n| unload_id | () | int32 | 0 | 499 | always |\n\n### Observation spec\n\nname | shape | dtype | min | max | enabled?\n------------------------------ | -------------------------------------- | ----- | --- | ----------------------------------------- | --------\naction/build_queue_id | () | int32 | 0 | 9 | `supervised`\naction/control_group_act | () | int32 | 0 | 4 | `supervised`\naction/control_group_id | () | int32 | 0 | 9 | `supervised`\naction/delay | () | int32 | 1 | 127 | `supervised`\naction/function | () | int32 | 0 | `num_action_types` | `supervised`\naction/minimap | () | int32 | 0 | `minimap.x` * `minimap.y` - 1 | `supervised`\naction/queued | () | int32 | 0 | 1 | `supervised`\naction/screen | () | int32 | 0 | `visual.screen.x` * `visual.screen.y` - 1 | `supervised`\naction/screen2 | () | int32 | 0 | `visual.screen.x` * `visual.screen.y` - 1 | `supervised`\naction/select_add | () | int32 | 0 | 1 | `supervised`\naction/select_point_act | () | int32 | 0 | 3 | `supervised`\naction/select_unit_act | () | int32 | 0 | 3 | `supervised`\naction/select_unit_id | () | int32 | 0 | 499 | `supervised`\naction/select_worker | () | int32 | 0 | 3 | `supervised`\naction/unload_id | () | int32 | 0 | 499 | `supervised`\navailable_actions | (`num_action_types`,) | int32 | - | - | always\naway_race_observed | () | int32 | - | - | always\naway_race_requested | () | int32 | - | - | always\ngame_loop | () | int32 | | - | -\nhome_race_requested | () | int32 | - | - | always\nminimap_alerts | (`minimap.x`, `minimap.y`) | uint8 | 0 | 1 | 'alerts' in `minimap_features`\nminimap_buildable | (`minimap.x`, `minimap.y`) | uint8 | 0 | 1 | 'buildable' in `minimap_features`\nminimap_camera | (`minimap.x`, `minimap.y`) | uint8 | 0 | 1 | 'camera' in `minimap_features`\nminimap_creep | (`minimap.x`, `minimap.y`) | uint8 | 0 | 1 | 'creep' in `minimap_features`\nminimap_height_map | (`minimap.x`, `minimap.y`) | uint8 | 0 | 255 | 'height_map' in `minimap_features`\nminimap_pathable | (`minimap.x`, `minimap.y`) | uint8 | 0 | 1 | 'pathable' in `minimap_features`\nminimap_player_relative | (`minimap.x`, `minimap.y`) | uint8 | 0 | 4 | 'player_relative' in `minimap_features`\nminimap_selected | (`minimap.x`, `minimap.y`) | uint8 | 0 | 1 | 'selected' in `minimap_features`\nminimap_visibility_map | (`minimap.x`, `minimap.y`) | uint8 | 0 | 3 | 'visibility_amp' in `minimap_features`\nmmr | () | int32 | - | - | always\nopponent_player | (10,) | int32 | - | - | `add_opponent_features`\nopponent_unit_counts_bow | (217,) | int32 | - | - | `add_opponent_features`\nopponent_upgrades_fixed_length | (`max_num_upgrades`,) | int32 | 0 | `num_upgrade_types` - 1 | `add_opponent_features`\nplayer | (11,) | int32 | - | - | always\nscreen_active | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 1 | 'active' in `visual.screen_features`\nscreen_blip | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 1 | 'blip' in `visual.screen_features`\nscreen_buff_duration | (`visual.screen.x`, `visual.screen.y` | uint8 | 0 | 255 | 'buff_duration' in `visual.screen_features`\nscreen_buffs | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 47 | 'buffs' in `visual.screen_features`\nscreen_build_progress | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 255 | 'build_progress' in `visual.screen_features`\nscreen_buildable | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 1 | 'buildable' in `visual.screen_features`\nscreen_cloaked | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 1 | 'cloaked' in `visual.screen_features`\nscreen_creep | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 1 | 'creep' in `visual.screen_features`\nscreen_effects | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 15 | 'effects' in `visual.screen_features`\nscreen_hallucinations | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 1 | 'hallucinations' in `visual.screen_features`\nscreen_height_map | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 255 | 'height_map' in `visual.screen_features`\nscreen_pathable | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 1 | 'pathable' in `visual.screen_features`\nscreen_player_relative | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 4 | 'player_relative' in `visual.screen_features`\nscreen_power | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 1 | 'power' in `visual.screen_features`\nscreen_selected | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 1 | 'selected' in `visual.screen_features`\nscreen_unit_density_aa | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 255 | 'unit_density_aa' in `visual.screen_features`\nscreen_unit_energy_ratio | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 255 | 'unit_energy_ratio' in `visual.screen_features`\nscreen_unit_hit_points_ratio | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 255 | 'unit_hit_points_ratio' in `visual.screen_features`\nscreen_unit_shields_ratio | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 255 | 'unit_shields_ratio' in `visual.screen_features`\nscreen_unit_type | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | `num_unit_types` | 'unit_type' in `visual.screen_features`\nscreen_visibility_map | (`visual.screen.x`, `visual.screen.y`) | uint8 | 0 | 3 | 'visibility_map' in `visual.screen_features`\nunit_counts_bow | (`num_unit_types`,) | int32 | - | - | always\nupgrades_fixed_length | (`max_num_upgrades`,) | int32 | 0 | `num_upgrade_types`-1 | always\n"
},
{
"path": "docs/environment.md",
"content": "## Environment Table of Contents\n\n- [Starcraft II](#starcraft-ii)\n - [What is StarCraft II](#what-is-starcraft-ii)\n - [Versions](#versions)\n - [Game and Action Speed](#game-and-action-speed)\n - [Game speed](#game-speed)\n - [APM Calculation](#apm-calculation)\n - [APM and fairness](#apm-and-fairness)\n - [Determinism and Randomness](#determinism-and-randomness)\n- [Actions and Observations](#actions-and-observations)\n - [Observation](#observation)\n - [Spatial/Visual](#spatialvisual)\n - [RGB Pixels](#rgb-pixels)\n - [Feature layers](#feature-layers)\n - [Minimap](#minimap)\n - [Screen](#screen)\n - [Structured](#structured)\n - [General player information](#general-player-information)\n - [Control groups](#control-groups)\n - [Single Select](#single-select)\n - [Multi Select](#multi-select)\n - [Cargo](#cargo)\n - [BuildQueue](#build-queue)\n - [AvailableActions](#available-actions)\n - [LastActions](#last-actions)\n - [ActionsResult](#action-result)\n - [Alerts](#alerts)\n - [Actions](#actions)\n - [List of actions](#list-of-actions)\n - [Action categories](#action-categories)\n - [General vs Specific actions](#general-vs-specific-actions)\n - [Example usage](#example-usage)\n- [RL Environment](#rl-environment)\n - [Environment wrappers](#environment-wrappers)\n- [Agents](#agents)\n\n\n\n## StarCraft II\n\n### What is StarCraft II\n\n[StarCraft II](https://en.wikipedia.org/wiki/StarCraft_II:_Legacy_of_the_Void)\nis a [Real Time Strategy\n(RTS)](https://en.wikipedia.org/wiki/Real-time_strategy) game written by\n[Blizzard](http://blizzard.com/). It's the successor to [StarCraft\nBroodwar](https://en.wikipedia.org/wiki/StarCraft:_Brood_War), which is one of\nthe most successful RTS games. StarCraft II is played by millions of people, and\nhas a [professional league](https://wcs.starcraft2.com/en-us/).\n\nThe [goal in StarCraft](http://us.battle.net/sc2/en/game/guide/whats-sc2) is to\nbuild a base, manage an economy, build an army, and destroy your enemies. You\ncontrol your base and army from a third person perspective, then multi-task and\nmicro-manage your units for maximum effect. StarCraft has 3 distinct races:\n[Terran](https://www.youtube.com/watch?v=Fmu8PsUDDtQ),\n[Protoss](https://www.youtube.com/watch?v=m0g0MpllFCs) and\n[Zerg](https://www.youtube.com/watch?v=Lq74R7wWAnQ), which have different units\nand strategies.\n\nThe game has a single player campaign, though most people play multiplayer on\n[Battle.net](http://battle.net/sc2/en/). There are built-in bots, but they are\nfairly weak and predictable, and the stronger ones cheat.\n\nThere are many resources online for learning about Starcraft, including\n[Battle.net](http://battle.net/sc2/en/),\n[Liquipedia](http://liquipedia.net/starcraft2/StarCraft) and\n[Wikia](http://starcraft.wikia.com/). For map making check out\n[SC2Mapster](https://sc2mapster.gamepedia.com/SC2Mapster_Wiki).\n\n### Versions\n\nBlizzard regularly updates StarCraft II. These updates are roughly monthly, can\nintroduce new features, and often have minor gameplay and balance changes to\nmake the races more even. Replays are tied to the specific version they were\ngenerated with.\n\n### Game and Action Speed\n\nBeing a real-time strategy game means the game runs in real-time. In reality\nthough, the simulation updates 16-22 times per second, depending on your [game\nspeed](http://wiki.teamliquid.net/starcraft2/Game_Speed), and all the\nintermediate rendered frames are just interpolated.\n\n#### Game speed\n\nActing through an API allows you to control the clock. Instead of running at\n16-22 steps per second, you can step as fast or as slow as you want, when you\nwant. This allows you to run much faster than real-time if the agent is capable,\nor much slower if the agent needs to pause to spend some time learning. This\nalso means there is never any lag. The max speed depends on the step_mul/render\nfrequency, and the scene complexity/unit count. 10x real-time is not uncommon\nand can be much higher for simple maps.\n\n#### APM Calculation\n\nThe game calculates and reports APM in a non-obvious way. It isn't obvious how\nto count the action of moving the camera with edge scrolling, or how many\nactions is building a building. Here are the rules of how it's actually counted\nby the game.\n\nThere are actually two types reported by the game:\n\n* Actions Per Minute (APM): counts every action.\n* Effective Actions Per Minute (EPM): filters out actions that have no effect\n (eg: redundant selections).\n\nDifferent actions count as different number of actions:\n\n* Commands with target = 2 (eg: move, attack, build building)\n* Commands with no target = 1 (eg: stop, train unit, unload cargo)\n* Smart = 1 (right click)\n* Selection and control groups = 1\n* Everything else = 0 (eg: camera movement)\n\nThe in game replay UI exposes this with two different time intervals: average\n(average over the entire game so far), and current (average over the last 5\nseconds). The API only exposes the average APM.\n\n#### APM and fairness\n\nHumans can't do one action per frame. They range from 30-500 actions per minute\n(APM), with 30 being a beginner, 60-100 being average, and professionals\nbeing >200 (over 3 per second!). This is trivial compared to what a fast bot is\ncapable of though. With the [BWAPI](http://bwapi.github.io/) they control units\nindividually and routinely go over 5000 APM accomplishing things that are\nclearly impossible for humans and considered\n[unfair](https://youtu.be/IKVFZ28ybQs?t=45s) or even\n[broken](https://youtu.be/0EYH-csTttw?t=28s). Even without controlling the units\nindividually it would be unfair to be able to act much faster with high\nprecision.\n\nTo at least resemble playing fairly it is a good idea to artificially limit the\nAPM. The easy way is to limit how often the agent gets observations and can make\nan action, and limit it to one action per observation. For example you can do\nthis by only taking every `N`th observation, where `N` is up for debate. A value\nof 20 is roughly equal to 50 apm while 5 is roughly 200 apm, so that's a\nreasonable range to play with. A more sophisticated way is to give the agent\nevery observation but limit the number of actions that actually have an effect,\nforcing it to mainly make no-ops which wouldn't count as actions.\n\nIt's probably better to consider all actions as equivalent, including camera\nmovement, since allowing very fast camera movement could allow agents to cheat.\n\n### Determinism and Randomness\n\nStarcraft II is mostly deterministic, but it does have some randomness mainly\nfor cosmetic reasons. The two main random elements are weapon speed and update\norder.\n\nWeapon randomness is essentially how fast a unit can get its next shot off after\nfiring and is between -1 to +2 game steps for almost all units. The idea\nbeing that a group of marines may all start firing together, but the minor\nrandom +/- for the next shot will make the group look less robotic and prevent\nthem from firing in sync forever. This also means a fair matchup (eg 1v1 marine)\nwill result in a random outcome.\n\nThe update order is random and determines the order of events in a given game\nloop. For example, if you have two High Templar that cast feedback on each other\non the same game loop, it will be random which one performs the damage first and\nwins.\n\nUnit auto-targeting is deterministic, but complicated. It is based on weapon\nscan distance, threat and assistance. Units will consider any enemies with\nweapon a higher threat than those without, and enemies that can return fire will\nbe a higher priority than those that can’t return fire. Units that can't return\nfire (eg a missile turret vs a marine) but that are attacking an allied unit (eg\na medivac) will trigger a call for help and increase the priority. A healer\nraises its priority when it is healing. If two targets have the same priority\nthe nearest one will be chosen.\n\nThese sources of randomness can be removed/mitigated by setting a random seed.\nReplays work by saving the game setup including the random seed, as well as the\nlist of actions by all players, and then playing forward the simulation.\n\n## Actions and Observations\n\nStarcraft II has a very rich action and observation space. The game outputs\nboth spatial/visual and structured elements. The structured elements are given\nbecause there is a lot of text and numbers which agents aren't expected to learn\nto read, especially at low resolution. It's also because it's hard to reverse\nreplays back to exactly the same visuals that the human saw.\n\n__Important Note:__\n\nSpatial observations are in y-major screen coordinate space as `(y, x)`. Actions\nthat require points on the screen or the minimap, however, expect the\ncoordinates as `(x, y)`. The origin `(0, 0)` is at the top-left corner in both\ncases.\n\nSee the [scripted agents](../pysc2/agents/scripted_agent.py) for an example of\npassing a screen coordinate to an action:\n\n```python\n # Spatial observations have the y-coordinate first:\n y, x = (obs.observation[\"feature_screen\"][_PLAYER_RELATIVE] == _PLAYER_NEUTRAL).nonzero()\n\n # Actions expect x-coordinate first:\n target = [int(x.mean()), int(y.mean())]\n action = actions.FunctionCall.Move_screen(\"now\", target)\n```\n\n### Observation\n\n#### Spatial/Visual\n\n##### RGB Pixels\n\nRGB pixels are available for both the main screen area as well as for the\nminimap at a resolution of your choice. This uses the same perspective camera as\na human would see, but doesn't include all the extra chrome around the screen\nlike the command card, selection box, build queue, etc. They are exposed as\n`rgb_screen` and `rgb_minimap`.\n\n##### Feature layers\n\nThe game also exposes feature layers. They represent roughly the same\ninformation as RGB pixels except that the information is decomposed and\nstructured. There are ~25 feature layers broken down between the screen and\nminimap and exposed as `feature_screen` and `feature_minimap`.\n\nThe full list is defined in `pysc2.lib.features`.\n\n###### Minimap\n\nThe minimap is a low resolution view of the entire map. It gives an overview of\neverything going on, but with less detail than the screen.\n\nYou can specify the resolution of the minimap. Maps range from\n32-2562, with common human maps in the 100-2562 range.\nHumans playing at 1080p get a resolution of ~2502 in the bottom left\ncorner of their screen.\n\nThese are the minimap feature layers:\n\n* **height_map**: Shows the terrain levels.\n* **visibility**: Which part of the map are hidden, have been seen or are\n currently visible.\n* **creep**: Which parts have zerg creep.\n* **camera**: Which part of the map are visible in the screen layers.\n* **player_id**: Who owns the units, with absolute ids.\n* **player_relative**: Which units are friendly vs hostile. Takes values in\n [0, 4], denoting [background, self, ally, neutral, enemy] units\n respectively.\n* **selected**: Which units are selected.\n\n###### Screen\n\nThe screen is a higher resolution view of part of the map.\n\nIt is rendered from a top down orthogonal camera, as opposed to a perspective\ncamera that a human would get in a real game. This makes certain visuals harder\n(eg you can't see elevation by size), but it also makes other things easier (eg\nunits don't change size as they or the camera moves). This also means that the\nvisible area is a rectangular part of the map, as opposed to the more\ntrapezoidal shape in the real game. This means there are bits of the map that an\nagent can see that humans can't, and vice versa, but it is roughly similar.\n\nA small unit (eg marine or zergling) is ~0.75 game units across. The camera is\n24 game units wide. If you specify a screen resolution of 322, that\nmeans a unit will be 1 pixel wide, meaning you have very low accuracy of its\nlocation. If you have a large group of them you may not be able to tell how many\nof them you have. A resolution of at least 642 is recommended to be\nplayable.\n\nThese are the screen feature layers:\n\n* **height_map**: Shows the terrain levels.\n* **visibility**: Which part of the map are hidden, have been seen or are\n currently visible.\n* **creep**: Which parts have zerg creep.\n* **power**: Which parts have protoss power, only shows your power.\n* **player_id**: Who owns the units, with absolute ids.\n* **player_relative**: Which units are friendly vs hostile. Takes values in\n [0, 4], denoting [background, self, ally, neutral, enemy] units\n respectively.\n* **unit_type**: A unit type id, which can be looked up in pysc2/lib/units.py.\n* **selected**: Which units are selected.\n* **hit_points**: How many hit points the unit has.\n* **energy**: How much energy the unit has.\n* **shields**: How much shields the unit has. Only for protoss units.\n* **unit_density**: How many units are in this pixel.\n* **unit_density_aa**: An anti-aliased version of unit_density with a maximum\n of 16 per unit per pixel. This gives you sub-pixel unit location and size.\n For example if a unit is exactly 1 pixel diameter, `unit_density` will show\n it in exactly 1 pixel regardless of where in that pixel it is actually\n centered. `unit_density_aa` will instead tell you how much of each pixel is\n covered by the unit. A unit that is smaller than a pixel and centered in the\n pixel will give a value less than the max. A unit with diameter 1 centered\n near the corner of a pixel will give roughly a quarter of its value to each\n of the 4 pixels it covers. If multiple units cover a pixel their proportion\n of the pixel covered will be summed, up to a max of 256.\n\n#### Structured\n\nThe game offers a fair amount of structured data which agents aren't expected\nto read from pixels. Instead these are given as tensors with direct semantic\nmeaning.\n\n##### General player information\n\nA `(11)` tensor showing general information.\n\n* player_id\n* minerals\n* vespene\n* food used (otherwise known as supply)\n* food cap\n* food used by army\n* food used by workers\n* idle worker count\n* army count\n* warp gate count (for protoss)\n* larva count (for zerg)\n\n##### Control groups\n\nA `(10, 2)` tensor showing the (unit leader type and count) for each of the 10\ncontrol groups. The indices in this tensor are referenced by the `control-group`\naction.\n\n[Control groups](http://learningsc2.com/tag/control-groups/) are a way to\nremember a selection set so that you can recall them easily later.\n\n##### Single Select\n\nA `(7)` tensor showing information about a selected unit.\n\n* unit type\n* player_relative\n* health\n* shields\n* energy\n* transport slot taken if it's in a transport\n* build progress as a percentage if it's still being built\n\n##### Multi Select\n\nA `(n, 7)` tensor with the same as [single select](#single-select) but for all\n`n` selected units. The indices in this tensor are referenced by the\n`select_unit` action.\n\n##### Cargo\n\nA `(n, 7)` tensor similar to [single select](#single-select), but for all the\nunits in a transport. The indices in this tensor are referenced by the `unload`\naction.\n\n##### Build Queue\n\nA `(n, 7)` tensor similar to [single select](#single-select), but for all the\nunits being built by a production building. The indices in this tensor are\nreferenced by the `build_queue` action.\n\n##### Available Actions\n\nA `(n)` tensor listing all the action ids that are available at the time of this\nobservation.\n\n##### Last Actions\n\nA `(n)` tensor listing all the action ids that were made successfully since the\nlast observation. An action that was attempted but failed is not included here.\n\n##### Action Result\n\nA `(n)` tensor (usually size 1) giving the result of the action. The values are\nlisted in\n[error.proto](https://github.com/Blizzard/s2client-proto/blob/master/s2clientprotocol/error.proto)\n\n##### Alerts\n\nA `(n)` tensor (usually empty, occasionally size 1, max 2) for when you're being attacked in a major way.\n\n### Actions\n\nThe SC2 action space is very big. There are hundreds of possible actions, many\nof which take a point in either screen or minimap space, and many of which take\nan additional modifier. If you were to flatten the action space into a single\ndimension, it'd have millions or even billions of possible actions, most of\nwhich aren't valid, and many of which are highly correlated. Therefore, a flat\ndiscrete action space is not very appropriate.\n\nInstead, we created function actions that are rich enough to give\ncomposability, without the complexity of an arbitrary hierarchy. This is based\non the mental model of a C-style function call which can take some arguments of\nspecific types. The full set of valid types and functions are defined in\n`ValidActions` in `pysc2.lib.actions`, and then each observation specifies which\nof the available function is valid this frame. Each action is a single\n`FunctionCall` in `pysc2.lib.actions` with all its arguments filled.\n\nThe full set of types and functions are defined in `pysc2.lib.actions`. The set\nof functions is hard coded and limited to just the actions that humans have\ntaken, as seen by a large number of replays. Hard coding the functions means\nthat actions created in custom maps won't be usable until they are added to\n`pysc2.lib.actions`.\n\nThe semantic meaning of these actions can mainly be found by searching:\n[liquipedia.net/starcraft2](http://liquipedia.net/starcraft2/) or\n[starcraft.wikia](http://starcraft.wikia.com/).\n\n#### List of actions\n\nTo see which actions exist run:\n\n```shell\n$ python -m pysc2.bin.valid_actions\n```\n\noptionally with `--hide_specific`, `--screen_resolution` or\n`--minimap_resolution` if you care about the exact values. This prints something\nsimilar to:\n\n```\n 0/no_op ()\n 1/move_camera (1/minimap [64, 64])\n 2/select_point (6/select_point_act [4]; 0/screen [84, 84])\n 3/select_rect (7/select_add [2]; 0/screen [84, 84]; 2/screen2 [84, 84])\n 4/select_control_group (4/control_group_act [5]; 5/control_group_id [10])\n 5/select_unit (8/select_unit_act [4]; 9/select_unit_id [500])\n 6/select_idle_worker (10/select_worker [4])\n 7/select_army (7/select_add [2])\n 8/select_warp_gates (7/select_add [2])\n 9/select_larva ()\n 10/unload (12/unload_id [500])\n 11/build_queue (11/build_queue_id [10])\n 12/Attack_screen (3/queued [2]; 0/screen [84, 84])\n 13/Attack_minimap (3/queued [2]; 1/minimap [64, 64])\n 14/Attack_Attack_screen (3/queued [2]; 0/screen [84, 84])\n 19/Scan_Move_screen (3/queued [2]; 0/screen [84, 84])\n 23/Behavior_CloakOff_quick (3/queued [2])\n 26/Behavior_CloakOn_quick (3/queued [2])\n 42/Build_Barracks_screen (3/queued [2]; 0/screen [84, 84])\n 44/Build_CommandCenter_screen (3/queued [2]; 0/screen [84, 84])\n 220/Effect_Repair_screen (3/queued [2]; 0/screen [84, 84])\n 221/Effect_Repair_autocast ()\n 264/Harvest_Gather_screen (3/queued [2]; 0/screen [84, 84])\n 303/Morph_Lair_quick (3/queued [2])\n 317/Morph_SiegeMode_quick (3/queued [2])\n 322/Morph_Unsiege_quick (3/queued [2])\n 331/Move_screen (3/queued [2]; 0/screen [84, 84])\n 333/Patrol_screen (3/queued [2]; 0/screen [84, 84])\n 405/Research_Stimpack_quick (3/queued [2])\n 451/Smart_screen (3/queued [2]; 0/screen [84, 84])\n 452/Smart_minimap (3/queued [2]; 1/minimap [64, 64])\n 453/Stop_quick (3/queued [2])\n 477/Train_Marine_quick (3/queued [2])\n *** 100s more lines ***\n```\n\nThis should be read as: `/(/\n[, *]; *)`.\n\nSome examples:\n\n* `1/move_camera (1/minimap [64, 64])` is the `move_camera` function (id `1`),\n which takes one argument named `minimap` (id `1`) which requires two ints\n each in the range `[0, 64)` which represent the coordinates on the minimap.\n* `331/Move_screen (3/queued [2]; 0/screen [84, 84])` is the `Move_screen`\n function (id `331`) which takes two arguments: `queued` (id `3`) which is a\n bool and signifies whether this action should happen now or after previous\n actions, and `screen` (id `0`) which takes two ints each in the range `[0,\n 84)` which represent a pixel on the screen.\n\nThe function names should be unique, stable and meaningful. The function and\ntype ids are the index into the list of `functions` and `types`.\n\nThe `types` are a predefined list of argument types that can be used in a\nfunction call. The exact definitions are in `pysc2.lib.actions.TYPES`\n\n#### Action categories\n\nA `Morph` action transform a unit to a different unit, at least according to the\nunit_type in the observation. For example `Morph_Lair_quick` morphs a hatchery\nto a lair; `Morph_SiegeMode_quick` and `Morph_Unsiege_quick` morphs a siege tank\nbetween tank and siege mode. An `Effect` is a single effect, rarely cancelable.\nA `Behavior` can be turned on and off but doesn't change the unit type.\n\n#### General vs Specific actions\n\nStarCraft II speaks in terms of abilities. Sometimes a single concept that can\nbe done by many units is implemented as a single ability (eg Move, Halt,\nPatrol), and sometimes as many abilities (eg Attack, Burrow, Cancel, Lift/Land).\n`Burrow` is a simple example where each zerg unit that can burrow has its own\nability (`BurrowDown_Drone`, `BurrowDown_Zergling`, etc). Exposing those\nindividually would make the action space even more complicated, and make it hard\nto burrow a whole army at once given a [limited APM](#apm-and-fairness), so we\nadded a concept of general abilities that merge all of the specific abilities\nthat would happen together or using the same key in the game UI. If you give the\nspecific ability (eg `BurrowDown_Zergling`) it'll only affect the specific units\nthat support that ability (eg Zerglings), while if you give the corresponding\ngeneral ability (`BurrowDown`) it'll affect all units that support it.\n\nAttack is a non-obvious case of this. There is `Attack`, which is the general\nability that corresponds to what the UI does, but under the hood that actually\nexecutes `Attack_Attack` for offensive units, `Scan_Move` for support units like\nmedivacs that can't attack but should come along as if they can,\n`Attack_AttackBuilding` for defensive buildings (eg missile turret) and\n`Attack_Redirect` for bunkers to tell their loaded units to attack.\n\nFor now only the general actions are exposed through the environment api so only\nthe general actions should be returned in the available actions observation.\n\nIn `pysc2.lib.actions.FUNCTIONS` specific functions have an additional parameter\nthat references the general parameter.\n\n#### Example usage\n\nTake a look at the [random agent](../pysc2/agents/random_agent.py) for an\nexample of how to consume `ValidActions` and fill `FunctionCall`s.\n\nThe following snippet shows how to print a human-readable list of available\nactions:\n\n```python\n from pysc2.lib import actions\n\n for action in obs.observation.available_actions:\n print(actions.FUNCTIONS[action])\n```\n\n## RL Environment\n\nThe main SC2 environment is at `pysc2.env.sc2_env`, with the action and\nobservation space defined in `pysc2.lib.features`.\n\nThe most important argument is `map_name`, which is how to find the map.\nFind the names by using `pysc2.bin.map_list` or by looking in `pysc2/maps/*.py`.\n\n`players` lets your specify the number and type of players. At the moment only\none or two players are supported. Give it a list of `sc2_env.Agent` or\n`sc2_env.Bot` objects, specifying the race and difficulty. Specifying two agents\nwill start up two instances of SC2 which communicate between themselves, and\nconsume double the memory and cpu as playing single player.\n\n`agent_interface_format` lets you specify the observation and action interface\nto be used by each agent. `feature_dimensions` and `rgb_dimensions` let you\nspecify the resolution of the spatial observations. Higher resolution obviously\ngives higher location precision, at the cost of larger observations as well as a\nlarger action space, and slower rendering time.\n\nIf you ask for both feature and rgb observations you'll need to specify the\naction space that you want to use. This lets you act in one while learning from\nthe other.\n\n`step_mul` let's you skip observations and actions. For example a `step_mul` of\n16 means that the environment gets stepped forward 16 times in between the\nactions of the agent (16 steps = 1 second of game time). It is equivalent to\nignoring certain observations and not sending actions on those frames, except it\nalso speeds up the environment since it doesn't need to render the skipped\nframes.\n\n`save_replay_episodes` and `replay_dir` specify how often to save replays and\nwhere to save them.\n\nUse the `run_loop.py` to have your agent interact with the environment.\n\n### Environment wrappers\n\nThere is one pre-made environment wrapper:\n\n* `available_actions_printer`: Prints each available action as it is seen.\n\n## Agents\n\nThere are a couple basic agents.\n\n* `random_agent`: Just plays randomly, shows how to make valid moves.\n* `scripted_agent`: These are scripted for a single mini game.\n"
},
{
"path": "docs/maps.md",
"content": "# StarCraft II Maps\n\n## Map config\n\nSC2Map files are what is used by the SC2 game, but they can be used differently,\nand those differences are defined in our map configs. The config gives\ninformation like how long the episodes last, how many players it can play, and\nhow to score it.\n\nTo create your own map config, just subclass the base Map class and override\nsome of the settings. The most important is to define the directory and filename\nfor the SC2Map. Any Map subclass will be automatically picked up as long as it's\nimported somewhere.\n\n## DeepMind Mini-Games\n\nThe [mini-games](mini_games.md) are designed to be single-player, fixed length\nand exercise different aspects of the game. They expose a score/reward which\nlets the agent know how well it is doing. The score should differentiate poor\nagents (eg random) from good agents.\n\n## Ladder\n\n[Ladder maps](http://wiki.teamliquid.net/starcraft2/Maps/Ladder_Maps/Legacy_of_the_Void)\nare the maps played by human players on Battle.net. There are just a handful\nactive at a time. Every few months a new season starts bringing a new set of\nmaps.\n\nSome of the maps have suffixes LE or TE. LE means Ladder Edition. These are\ncommunity maps that were edited by Blizzard for bugs and made ready for the\nladder pool. TE means Tournament Edition. These maps were used in tournaments.\n\nThey are all multiplayer maps with fairly long time limits.\n\n## Melee\n\nThese are maps made specifically for machine learning. They resemble\nladder maps in format, but may be smaller sizes and aren't necessarily balanced\nfor high level play.\n\nThe **Flat** maps have no special features on the terrain, encouraging easy\nattacking. The number specifies the map size.\n\nThe **Simple** maps are more normal with expansions, ramps, and lanes of attack,\nbut are smaller than normal ladder maps. The number specifies the map size.\n"
},
{
"path": "docs/mini_games.md",
"content": "# DeepMind Mini Games\n\n## MoveToBeacon\n\n#### Description\n\nA map with 1 Marine and 1 Beacon. Rewards are earned by moving the marine to the\nbeacon. Whenever the Marine earns a reward for reaching the Beacon, the Beacon\nis teleported to a random location (at least 5 units away from Marine).\n\n#### Initial State\n\n* 1 Marine at random location (unselected)\n* 1 Beacon at random location (at least 4 units away from Marine)\n\n#### Rewards\n\n* Marine reaches Beacon: +1\n\n#### End Condition\n\n* Time elapsed\n\n#### Time Limit\n\n* 120 seconds\n\n#### Additional Notes\n\n* Fog of War disabled\n* No camera movement required (single-screen)\n\n## CollectMineralShards\n\n#### Description\n\nA map with 2 Marines and an endless supply of Mineral Shards. Rewards are earned\nby moving the Marines to collect the Mineral Shards, with optimal collection\nrequiring both Marine units to be split up and moved independently. Whenever all\n20 Mineral Shards have been collected, a new set of 20 Mineral Shards are\nspawned at random locations (at least 2 units away from all Marines).\n\n#### Initial State\n\n* 2 Marines at random locations (unselected)\n* 20 Mineral Shards at random locations (at least 2 units away from all\n Marines)\n\n#### Rewards\n\n* Marine collects Mineral Shard: +1\n\n#### End Condition\n\n* Time elapsed\n\n#### Time Limit\n\n* 120 seconds\n\n#### Additional Notes\n\n* Fog of War disabled\n* No camera movement required (single-screen)\n* This is the only map in the set to require the Liberty (Campaign) mod, which\n is needed for the Mineral Shard unit.\n\n## FindAndDefeatZerglings\n\n#### Description\n\nA map with 3 Marines and an endless supply of stationary Zerglings. Rewards are\nearned by using the Marines to defeat Zerglings, with the optimal strategy\nrequiring a combination of efficient exploration and combat. Whenever all 25\nZerglings have been defeated, a new set of 25 Zerglings are spawned at random\nlocations (at least 9 units away from all Marines and at least 5 units away from\nall other Zerglings).\n\n#### Initial State\n\n* 3 Marines at map center (preselected)\n* 2 Zerglings spawned at random locations inside player's vision range\n (between 7.5 and 9.5 units away from map center and at least 5 units away\n from all other Zerglings)\n* 23 Zerglings spawned at random locations outside player's vision range (at\n least 10.5 units away from map center and at least 5 units away from all\n other Zerglings)\n\n#### Rewards\n\n* Zergling defeated: +1\n* Marine defeated: -1\n\n#### End Conditions\n\n* Time elapsed\n* All Marines defeated\n\n#### Time Limit\n\n* 180 seconds\n\n#### Additional Notes\n\n* Fog of War enabled\n* Camera movement required (map is larger than single-screen)\n\n## DefeatRoaches\n\n#### Description\n\nA map with 9 Marines and a group of 4 Roaches on opposite sides. Rewards are\nearned by using the Marines to defeat Roaches, with optimal combat strategy\nrequiring the Marines to perform focus fire on the Roaches. Whenever all 4\nRoaches have been defeated, a new group of 4 Roaches is spawned and the player\nis awarded 5 additional Marines at full health, with all other surviving Marines\nretaining their existing health (no restore). Whenever new units are spawned,\nall unit positions are reset to opposite sides of the map.\n\n#### Initial State\n\n* 9 Marines in a vertical line at a random side of the map (preselected)\n* 4 Roaches in a vertical line at the opposite side of the map from the\n Marines\n\n#### Rewards\n\n* Roach defeated: +10\n* Marine defeated: -1\n\n#### End Conditions\n\n* Time elapsed\n* All Marines defeated\n\n#### Time Limit\n\n* 120 seconds\n\n#### Additional Notes\n\n* Fog of War disabled\n* No camera movement required (single-screen)\n* This map and DefeatZerglingsAndBanelings are currently the only maps in the\n set that can include an automatic, mid-episode state change for\n player-controlled units. The Marine units are automatically moved back to a\n neutral position (at a random side of the map opposite the Roaches) when new\n units are spawned, which occurs whenever the current set of Roaches is\n defeated. This is done in order to guarantee that new units do not spawn\n within combat range of one another.\n\n## DefeatZerglingsAndBanelings\n\n#### Description\n\nA map with 9 Marines on the opposite side from a group of 6 Zerglings and 4\nBanelings. Rewards are earned by using the Marines to defeat Zerglings and\nBanelings. Whenever all Zerglings and Banelings have been defeated, a new group\nof 6 Zerglings and 4 Banelings is spawned and the player is awarded 4 additional\nMarines at full health, with all other surviving Marines retaining their\nexisting health (no restore). Whenever new units are spawned, all unit positions\nare reset to opposite sides of the map.\n\n#### Initial State\n\n* 9 Marines in a vertical line at a random side of the map (preselected)\n* 6 Zerglings and 4 Banelings in a group at the opposite side of the map from\n the Marines\n\n#### Rewards\n\n* Zergling defeated: +5\n* Baneling defeated: +5\n* Marine defeated: -1\n\n#### End Conditions\n\n* Time elapsed\n* All Marines defeated\n\n#### Time Limit\n\n* 120 seconds\n\n#### Additional Notes\n\n* Fog of War disabled\n* No camera movement required (single-screen)\n* This map and DefeatRoaches are currently the only maps in the set that can\n include an automatic, mid-episode state change for player-controlled units.\n The Marine units are automatically moved back to a neutral position (at a\n random side of the map opposite the Roaches) when new units are spawned,\n which occurs whenever the current set of Zerglings and Banelings is\n defeated. This is done in order to guarantee that new units do not spawn\n within combat range of one another.\n\n## CollectMineralsAndGas\n\n#### Description\n\nA map with 12 SCVs, 1 Command Center, 16 Mineral Fields and 4 Vespene Geysers.\nRewards are based on the total amount of Minerals and Vespene Gas collected.\nSpending Minerals and Vespene Gas to train new units does not decrease your\nreward tally. Optimal collection will require expanding your capacity to gather\nMinerals and Vespene Gas by constructing additional SCVs and an additional\nCommand Center.\n\n#### Initial State\n\n* 12 SCVs beside the Command Center (unselected)\n* 1 Command Center at a fixed location\n* 16 Mineral Fields at fixed locations\n* 4 Vespene Geysers at fixed locations\n* Player Resources: 50 Minerals, 0 Vespene, 12/15 Supply\n\n#### Rewards\n\nReward total is equal to the total amount of Minerals and Vespene Gas collected\n\n#### End Condition\n\nTime elapsed\n\n#### Time Limit\n\n300 seconds\n\n## BuildMarines\n\n#### Description\n\nA map with 12 SCVs, 1 Command Center, and 8 Mineral Fields. Rewards are earned\nby building Marines. This is accomplished by using SCVs to collect minerals,\nwhich are used to build Supply Depots and Barracks, which can then build\nMarines.\n\n#### Initial State\n\n* 12 SCVs beside the Command Center (unselected)\n* 1 Command Center at a fixed location\n* 8 Mineral Fields at fixed locations\n* Player Resources: 50 Minerals, 0 Vespene, 12/15 Supply\n\n#### Rewards\n\nReward total is equal to the total number of Marines built\n\n#### End Condition\n\nTime elapsed\n\n#### Time Limit\n\n900 seconds\n\n#### Additional Notes\n\n* Fog of War disabled\n* No camera movement required (single-screen)\n* This is the only map in the set that explicitly limits the available actions\n of the units to disallow actions which are not pertinent to the goal of the\n map. Actions that are not required for building Marines have been removed.\n"
},
{
"path": "pysc2/BUILD",
"content": "load(\"@bazel_skylib//:bzl_library.bzl\", \"bzl_library\")\n\nlicenses([\"notice\"])\n\nexports_files([\"LICENSE\"])\n\nbzl_library(\n name = \"build_defs\",\n srcs = [\"build_defs.bzl\"],\n)\n"
},
{
"path": "pysc2/__init__.py",
"content": "# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"PySC2 module: https://github.com/deepmind/pysc2 .\"\"\"\n\nimport os\n\n\ndef load_tests(loader, standard_tests, unused_pattern):\n \"\"\"Our tests end in `_test.py`, so need to override the test discovery.\"\"\"\n this_dir = os.path.dirname(__file__)\n package_tests = loader.discover(start_dir=this_dir, pattern=\"*_test.py\")\n standard_tests.addTests(package_tests)\n return standard_tests\n"
},
{
"path": "pysc2/agents/BUILD",
"content": "load(\"@my_deps//:requirements.bzl\", \"requirement\")\nload(\"//pysc2:build_defs.bzl\", \"pytype_library\", \"pytype_strict_library\")\n\npackage(default_visibility = [\"//visibility:public\"])\n\nlicenses([\"notice\"])\n\npy_library(\n name = \"agents\",\n srcs_version = \"PY3\",\n deps = [\n \":base_agent\",\n \":random_agent\",\n \":scripted_agent\",\n ],\n)\n\npytype_library(\n name = \"base_agent\",\n srcs = [\"base_agent.py\"],\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/lib:actions\",\n ],\n)\n\npytype_strict_library(\n name = \"no_op_agent\",\n srcs = [\"no_op_agent.py\"],\n deps = [\n \":base_agent\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_library(\n name = \"scripted_agent\",\n srcs = [\"scripted_agent.py\"],\n srcs_version = \"PY3\",\n deps = [\n \":base_agent\",\n requirement(\"numpy\"),\n \"//pysc2/lib:actions\",\n \"//pysc2/lib:features\",\n ],\n)\n\npytype_library(\n name = \"random_agent\",\n srcs = [\"random_agent.py\"],\n srcs_version = \"PY3\",\n deps = [\n \":base_agent\",\n requirement(\"numpy\"),\n \"//pysc2/lib:actions\",\n ],\n)\n"
},
{
"path": "pysc2/agents/__init__.py",
"content": "# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n"
},
{
"path": "pysc2/agents/base_agent.py",
"content": "# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"A base agent to write custom scripted agents.\"\"\"\n\nfrom pysc2.lib import actions\n\n\nclass BaseAgent(object):\n \"\"\"A base agent to write custom scripted agents.\n\n It can also act as a passive agent that does nothing but no-ops.\n \"\"\"\n\n def __init__(self):\n self.reward = 0\n self.episodes = 0\n self.steps = 0\n self.obs_spec = None\n self.action_spec = None\n\n def setup(self, obs_spec, action_spec):\n self.obs_spec = obs_spec\n self.action_spec = action_spec\n\n def reset(self):\n self.episodes += 1\n\n def step(self, obs):\n self.steps += 1\n self.reward += obs.reward\n return actions.FunctionCall(actions.FUNCTIONS.no_op.id, [])\n"
},
{
"path": "pysc2/agents/no_op_agent.py",
"content": "# Copyright 2021 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"A no-op agent for starcraft.\"\"\"\n\nfrom pysc2.agents import base_agent\n\nfrom s2clientprotocol import sc2api_pb2 as sc_pb\n\n\nclass NoOpAgent(base_agent.BaseAgent):\n \"\"\"A no-op agent for starcraft.\"\"\"\n\n def step(self, obs):\n super(NoOpAgent, self).step(obs)\n return sc_pb.Action()\n"
},
{
"path": "pysc2/agents/random_agent.py",
"content": "# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"A random agent for starcraft.\"\"\"\n\nimport numpy\n\nfrom pysc2.agents import base_agent\nfrom pysc2.lib import actions\n\n\nclass RandomAgent(base_agent.BaseAgent):\n \"\"\"A random agent for starcraft.\"\"\"\n\n def step(self, obs):\n super(RandomAgent, self).step(obs)\n function_id = numpy.random.choice(obs.observation.available_actions)\n args = [[numpy.random.randint(0, size) for size in arg.sizes]\n for arg in self.action_spec.functions[function_id].args]\n return actions.FunctionCall(function_id, args)\n"
},
{
"path": "pysc2/agents/scripted_agent.py",
"content": "# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Scripted agents.\"\"\"\n\nimport numpy\n\nfrom pysc2.agents import base_agent\nfrom pysc2.lib import actions\nfrom pysc2.lib import features\n\n_PLAYER_SELF = features.PlayerRelative.SELF\n_PLAYER_NEUTRAL = features.PlayerRelative.NEUTRAL # beacon/minerals\n_PLAYER_ENEMY = features.PlayerRelative.ENEMY\n\nFUNCTIONS = actions.FUNCTIONS\nRAW_FUNCTIONS = actions.RAW_FUNCTIONS\n\n\ndef _xy_locs(mask):\n \"\"\"Mask should be a set of bools from comparison with a feature layer.\"\"\"\n y, x = mask.nonzero()\n return list(zip(x, y))\n\n\nclass MoveToBeacon(base_agent.BaseAgent):\n \"\"\"An agent specifically for solving the MoveToBeacon map.\"\"\"\n\n def step(self, obs):\n super(MoveToBeacon, self).step(obs)\n if FUNCTIONS.Move_screen.id in obs.observation.available_actions:\n player_relative = obs.observation.feature_screen.player_relative\n beacon = _xy_locs(player_relative == _PLAYER_NEUTRAL)\n if not beacon:\n return FUNCTIONS.no_op()\n beacon_center = numpy.mean(beacon, axis=0).round()\n return FUNCTIONS.Move_screen(\"now\", beacon_center)\n else:\n return FUNCTIONS.select_army(\"select\")\n\n\nclass CollectMineralShards(base_agent.BaseAgent):\n \"\"\"An agent specifically for solving the CollectMineralShards map.\"\"\"\n\n def step(self, obs):\n super(CollectMineralShards, self).step(obs)\n if FUNCTIONS.Move_screen.id in obs.observation.available_actions:\n player_relative = obs.observation.feature_screen.player_relative\n minerals = _xy_locs(player_relative == _PLAYER_NEUTRAL)\n if not minerals:\n return FUNCTIONS.no_op()\n marines = _xy_locs(player_relative == _PLAYER_SELF)\n marine_xy = numpy.mean(marines, axis=0).round() # Average location.\n distances = numpy.linalg.norm(numpy.array(minerals) - marine_xy, axis=1)\n closest_mineral_xy = minerals[numpy.argmin(distances)]\n return FUNCTIONS.Move_screen(\"now\", closest_mineral_xy)\n else:\n return FUNCTIONS.select_army(\"select\")\n\n\nclass CollectMineralShardsFeatureUnits(base_agent.BaseAgent):\n \"\"\"An agent for solving the CollectMineralShards map with feature units.\n\n Controls the two marines independently:\n - select marine\n - move to nearest mineral shard that wasn't the previous target\n - swap marine and repeat\n \"\"\"\n\n def setup(self, obs_spec, action_spec):\n super(CollectMineralShardsFeatureUnits, self).setup(obs_spec, action_spec)\n if \"feature_units\" not in obs_spec:\n raise Exception(\"This agent requires the feature_units observation.\")\n\n def reset(self):\n super(CollectMineralShardsFeatureUnits, self).reset()\n self._marine_selected = False\n self._previous_mineral_xy = [-1, -1]\n\n def step(self, obs):\n super(CollectMineralShardsFeatureUnits, self).step(obs)\n marines = [unit for unit in obs.observation.feature_units\n if unit.alliance == _PLAYER_SELF]\n if not marines:\n return FUNCTIONS.no_op()\n marine_unit = next((m for m in marines\n if m.is_selected == self._marine_selected), marines[0])\n marine_xy = [marine_unit.x, marine_unit.y]\n\n if not marine_unit.is_selected:\n # Nothing selected or the wrong marine is selected.\n self._marine_selected = True\n return FUNCTIONS.select_point(\"select\", marine_xy)\n\n if FUNCTIONS.Move_screen.id in obs.observation.available_actions:\n # Find and move to the nearest mineral.\n minerals = [[unit.x, unit.y] for unit in obs.observation.feature_units\n if unit.alliance == _PLAYER_NEUTRAL]\n\n if self._previous_mineral_xy in minerals:\n # Don't go for the same mineral shard as other marine.\n minerals.remove(self._previous_mineral_xy)\n\n if minerals:\n # Find the closest.\n distances = numpy.linalg.norm(\n numpy.array(minerals) - numpy.array(marine_xy), axis=1)\n closest_mineral_xy = minerals[numpy.argmin(distances)]\n\n # Swap to the other marine.\n self._marine_selected = False\n self._previous_mineral_xy = closest_mineral_xy\n return FUNCTIONS.Move_screen(\"now\", closest_mineral_xy)\n\n return FUNCTIONS.no_op()\n\n\nclass CollectMineralShardsRaw(base_agent.BaseAgent):\n \"\"\"An agent for solving CollectMineralShards with raw units and actions.\n\n Controls the two marines independently:\n - move to nearest mineral shard that wasn't the previous target\n - swap marine and repeat\n \"\"\"\n\n def setup(self, obs_spec, action_spec):\n super(CollectMineralShardsRaw, self).setup(obs_spec, action_spec)\n if \"raw_units\" not in obs_spec:\n raise Exception(\"This agent requires the raw_units observation.\")\n\n def reset(self):\n super(CollectMineralShardsRaw, self).reset()\n self._last_marine = None\n self._previous_mineral_xy = [-1, -1]\n\n def step(self, obs):\n super(CollectMineralShardsRaw, self).step(obs)\n marines = [unit for unit in obs.observation.raw_units\n if unit.alliance == _PLAYER_SELF]\n if not marines:\n return RAW_FUNCTIONS.no_op()\n marine_unit = next((m for m in marines if m.tag != self._last_marine))\n marine_xy = [marine_unit.x, marine_unit.y]\n\n minerals = [[unit.x, unit.y] for unit in obs.observation.raw_units\n if unit.alliance == _PLAYER_NEUTRAL]\n\n if self._previous_mineral_xy in minerals:\n # Don't go for the same mineral shard as other marine.\n minerals.remove(self._previous_mineral_xy)\n\n if minerals:\n # Find the closest.\n distances = numpy.linalg.norm(\n numpy.array(minerals) - numpy.array(marine_xy), axis=1)\n closest_mineral_xy = minerals[numpy.argmin(distances)]\n\n self._last_marine = marine_unit.tag\n self._previous_mineral_xy = closest_mineral_xy\n return RAW_FUNCTIONS.Move_pt(\"now\", marine_unit.tag, closest_mineral_xy)\n\n return RAW_FUNCTIONS.no_op()\n\n\nclass DefeatRoaches(base_agent.BaseAgent):\n \"\"\"An agent specifically for solving the DefeatRoaches map.\"\"\"\n\n def step(self, obs):\n super(DefeatRoaches, self).step(obs)\n if FUNCTIONS.Attack_screen.id in obs.observation.available_actions:\n player_relative = obs.observation.feature_screen.player_relative\n roaches = _xy_locs(player_relative == _PLAYER_ENEMY)\n if not roaches:\n return FUNCTIONS.no_op()\n\n # Find the roach with max y coord.\n target = roaches[numpy.argmax(numpy.array(roaches)[:, 1])]\n return FUNCTIONS.Attack_screen(\"now\", target)\n\n if FUNCTIONS.select_army.id in obs.observation.available_actions:\n return FUNCTIONS.select_army(\"select\")\n\n return FUNCTIONS.no_op()\n\n\nclass DefeatRoachesRaw(base_agent.BaseAgent):\n \"\"\"An agent specifically for solving DefeatRoaches using raw actions.\"\"\"\n\n def setup(self, obs_spec, action_spec):\n super(DefeatRoachesRaw, self).setup(obs_spec, action_spec)\n if \"raw_units\" not in obs_spec:\n raise Exception(\"This agent requires the raw_units observation.\")\n\n def step(self, obs):\n super(DefeatRoachesRaw, self).step(obs)\n marines = [unit.tag for unit in obs.observation.raw_units\n if unit.alliance == _PLAYER_SELF]\n roaches = [unit for unit in obs.observation.raw_units\n if unit.alliance == _PLAYER_ENEMY]\n\n if marines and roaches:\n # Find the roach with max y coord.\n target = sorted(roaches, key=lambda r: r.y)[0].tag\n return RAW_FUNCTIONS.Attack_unit(\"now\", marines, target)\n\n return FUNCTIONS.no_op()\n"
},
{
"path": "pysc2/bin/BUILD",
"content": "load(\"@my_deps//:requirements.bzl\", \"requirement\")\nload(\"//pysc2:build_defs.bzl\", \"pytype_binary\", \"pytype_strict_binary\")\n\npackage(default_visibility = [\"//visibility:public\"])\n\nlicenses([\"notice\"])\n\npytype_binary(\n name = \"replay_actions\",\n srcs = [\"replay_actions.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/lib:features\",\n \"//pysc2/lib:gfile\",\n \"//pysc2/lib:point\",\n \"//pysc2/lib:protocol\",\n \"//pysc2/lib:remote_controller\",\n \"//pysc2/lib:replay\",\n \"//pysc2/lib:static_data\",\n \"//pysc2/maps\", # build_cleaner: keep\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_binary(\n name = \"gen_actions\",\n srcs = [\"gen_actions.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/lib:static_data\",\n \"//pysc2/maps\",\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_binary(\n name = \"gen_data\",\n srcs = [\"gen_data.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/lib:static_data\",\n \"//pysc2/maps\",\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_binary(\n name = \"check_apm\",\n srcs = [\"check_apm.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/lib:actions\",\n \"//pysc2/lib:features\",\n \"//pysc2/lib:point\",\n \"//pysc2/lib:units\",\n \"//pysc2/maps\",\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_binary(\n name = \"benchmark_observe\",\n srcs = [\"benchmark_observe.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/lib:replay\",\n \"//pysc2/lib:stopwatch\",\n \"//pysc2/maps\",\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_binary(\n name = \"benchmark_replay\",\n srcs = [\"benchmark_replay.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/lib:actions\",\n \"//pysc2/lib:features\",\n \"//pysc2/lib:point_flag\",\n \"//pysc2/lib:replay\",\n \"//pysc2/lib:stopwatch\",\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_binary(\n name = \"mem_leak_check\",\n srcs = [\"mem_leak_check.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n requirement(\"psutil\"), # build_cleaner: keep\n \"//pysc2/lib:protocol\",\n \"//pysc2/maps\",\n \"//pysc2/run_configs\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_binary(\n name = \"gen_versions\",\n srcs = [\"gen_versions.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"@absl_py//absl:app\",\n requirement(\"requests\"),\n ],\n)\n\npytype_binary(\n name = \"map_list\",\n srcs = [\"map_list.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/maps\",\n \"@absl_py//absl:app\",\n ],\n)\n\npytype_binary(\n name = \"play\",\n srcs = [\"play.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/env:sc2_env\",\n \"//pysc2/lib:point_flag\",\n \"//pysc2/lib:renderer_human\",\n \"//pysc2/lib:replay\",\n \"//pysc2/lib:stopwatch\",\n \"//pysc2/maps\",\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_binary(\n name = \"play_vs_agent\",\n srcs = [\"play_vs_agent.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n \"@absl_py//absl/logging\",\n requirement(\"portpicker\"),\n \"//pysc2/agents\", # build_cleaner: keep\n \"//pysc2/env:lan_sc2_env\",\n \"//pysc2/env:run_loop\",\n \"//pysc2/env:sc2_env\",\n \"//pysc2/lib:point_flag\",\n \"//pysc2/lib:renderer_human\",\n \"//pysc2/maps\",\n \"//pysc2/run_configs\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_binary(\n name = \"agent_remote\",\n srcs = [\"agent_remote.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/agents\", # build_cleaner: keep\n \"//pysc2/env:remote_sc2_env\",\n \"//pysc2/env:run_loop\",\n \"//pysc2/env:sc2_env\",\n \"//pysc2/lib:point_flag\",\n \"//pysc2/lib:portspicker\",\n \"//pysc2/lib:renderer_human\",\n \"//pysc2/maps\",\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n \"@absl_py//absl/logging\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_binary(\n name = \"replay_info\",\n srcs = [\"replay_info.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/lib:gfile\",\n \"//pysc2/lib:remote_controller\",\n \"//pysc2/lib:replay\",\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n \"@s2client_proto//s2clientprotocol:common_py_pb2\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_binary(\n name = \"agent\",\n srcs = [\"agent.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/agents\", # build_cleaner: keep\n \"//pysc2/env:available_actions_printer\",\n \"//pysc2/env:run_loop\",\n \"//pysc2/env:sc2_env\",\n \"//pysc2/lib:point_flag\",\n \"//pysc2/lib:stopwatch\",\n \"//pysc2/maps\",\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n ],\n)\n\npytype_binary(\n name = \"valid_actions\",\n srcs = [\"valid_actions.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/lib:actions\",\n \"//pysc2/lib:features\",\n \"//pysc2/lib:point_flag\",\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n ],\n)\n\npytype_binary(\n name = \"compare_binaries\",\n srcs = [\"compare_binaries.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/lib:image_differencer\",\n \"//pysc2/lib:proto_diff\",\n \"//pysc2/lib:remote_controller\",\n \"//pysc2/lib:replay\",\n \"//pysc2/lib:stopwatch\",\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_strict_binary(\n name = \"battle_net_maps\",\n srcs = [\"battle_net_maps.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n ],\n)\n\npytype_strict_binary(\n name = \"reencode_replays\",\n srcs = [\"reencode_replays.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"//pysc2/lib:replay\",\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n \"@s2client_proto//s2clientprotocol:sc2api_py_pb2\",\n ],\n)\n\npytype_strict_binary(\n name = \"update_battle_net_cache\",\n srcs = [\"update_battle_net_cache.py\"],\n python_version = \"PY3\",\n srcs_version = \"PY3\",\n deps = [\n \"@absl_py//absl:app\",\n \"@absl_py//absl/flags\",\n requirement(\"mpyq\"),\n \"//pysc2/run_configs\",\n \"@s2protocol_archive//:versions\",\n ],\n)\n\npytype_strict_binary(\n name = \"replay_version\",\n srcs = [\"replay_version.py\"],\n deps = [\n \"//pysc2/lib:replay\",\n \"//pysc2/run_configs\",\n \"@absl_py//absl:app\",\n ],\n)\n"
},
{
"path": "pysc2/bin/__init__.py",
"content": "# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n"
},
{
"path": "pysc2/bin/agent.py",
"content": "#!/usr/bin/python\n# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Run an agent.\"\"\"\n\nimport importlib\nimport threading\n\nfrom absl import app\nfrom absl import flags\n\nfrom pysc2 import maps\nfrom pysc2.env import available_actions_printer\nfrom pysc2.env import run_loop\nfrom pysc2.env import sc2_env\nfrom pysc2.lib import point_flag\nfrom pysc2.lib import stopwatch\n\n\nFLAGS = flags.FLAGS\nflags.DEFINE_bool(\"render\", True, \"Whether to render with pygame.\")\npoint_flag.DEFINE_point(\"feature_screen_size\", \"84\",\n \"Resolution for screen feature layers.\")\npoint_flag.DEFINE_point(\"feature_minimap_size\", \"64\",\n \"Resolution for minimap feature layers.\")\npoint_flag.DEFINE_point(\"rgb_screen_size\", None,\n \"Resolution for rendered screen.\")\npoint_flag.DEFINE_point(\"rgb_minimap_size\", None,\n \"Resolution for rendered minimap.\")\nflags.DEFINE_enum(\"action_space\", None, sc2_env.ActionSpace._member_names_, # pylint: disable=protected-access\n \"Which action space to use. Needed if you take both feature \"\n \"and rgb observations.\")\nflags.DEFINE_bool(\"use_feature_units\", False,\n \"Whether to include feature units.\")\nflags.DEFINE_bool(\"use_raw_units\", False,\n \"Whether to include raw units.\")\nflags.DEFINE_bool(\"disable_fog\", False, \"Whether to disable Fog of War.\")\n\nflags.DEFINE_integer(\"max_agent_steps\", 0, \"Total agent steps.\")\nflags.DEFINE_integer(\"game_steps_per_episode\", None, \"Game steps per episode.\")\nflags.DEFINE_integer(\"max_episodes\", 0, \"Total episodes.\")\nflags.DEFINE_integer(\"step_mul\", 8, \"Game steps per agent step.\")\n\nflags.DEFINE_string(\"agent\", \"pysc2.agents.random_agent.RandomAgent\",\n \"Which agent to run, as a python path to an Agent class.\")\nflags.DEFINE_string(\"agent_name\", None,\n \"Name of the agent in replays. Defaults to the class name.\")\nflags.DEFINE_enum(\"agent_race\", \"random\", sc2_env.Race._member_names_, # pylint: disable=protected-access\n \"Agent 1's race.\")\n\nflags.DEFINE_string(\"agent2\", \"Bot\", \"Second agent, either Bot or agent class.\")\nflags.DEFINE_string(\"agent2_name\", None,\n \"Name of the agent in replays. Defaults to the class name.\")\nflags.DEFINE_enum(\"agent2_race\", \"random\", sc2_env.Race._member_names_, # pylint: disable=protected-access\n \"Agent 2's race.\")\nflags.DEFINE_enum(\"difficulty\", \"very_easy\", sc2_env.Difficulty._member_names_, # pylint: disable=protected-access\n \"If agent2 is a built-in Bot, it's strength.\")\nflags.DEFINE_enum(\"bot_build\", \"random\", sc2_env.BotBuild._member_names_, # pylint: disable=protected-access\n \"Bot's build strategy.\")\n\nflags.DEFINE_bool(\"profile\", False, \"Whether to turn on code profiling.\")\nflags.DEFINE_bool(\"trace\", False, \"Whether to trace the code execution.\")\nflags.DEFINE_integer(\"parallel\", 1, \"How many instances to run in parallel.\")\n\nflags.DEFINE_bool(\"save_replay\", True, \"Whether to save a replay at the end.\")\n\nflags.DEFINE_string(\"map\", None, \"Name of a map to use.\")\nflags.DEFINE_bool(\"battle_net_map\", False, \"Use the battle.net map version.\")\nflags.mark_flag_as_required(\"map\")\n\n\ndef run_thread(agent_classes, players, map_name, visualize):\n \"\"\"Run one thread worth of the environment with agents.\"\"\"\n with sc2_env.SC2Env(\n map_name=map_name,\n battle_net_map=FLAGS.battle_net_map,\n players=players,\n agent_interface_format=sc2_env.parse_agent_interface_format(\n feature_screen=FLAGS.feature_screen_size,\n feature_minimap=FLAGS.feature_minimap_size,\n rgb_screen=FLAGS.rgb_screen_size,\n rgb_minimap=FLAGS.rgb_minimap_size,\n action_space=FLAGS.action_space,\n use_feature_units=FLAGS.use_feature_units,\n use_raw_units=FLAGS.use_raw_units),\n step_mul=FLAGS.step_mul,\n game_steps_per_episode=FLAGS.game_steps_per_episode,\n disable_fog=FLAGS.disable_fog,\n visualize=visualize) as env:\n env = available_actions_printer.AvailableActionsPrinter(env)\n agents = [agent_cls() for agent_cls in agent_classes]\n run_loop.run_loop(agents, env, FLAGS.max_agent_steps, FLAGS.max_episodes)\n if FLAGS.save_replay:\n env.save_replay(agent_classes[0].__name__)\n\n\ndef main(unused_argv):\n \"\"\"Run an agent.\"\"\"\n if FLAGS.trace:\n stopwatch.sw.trace()\n elif FLAGS.profile:\n stopwatch.sw.enable()\n\n map_inst = maps.get(FLAGS.map)\n\n agent_classes = []\n players = []\n\n agent_module, agent_name = FLAGS.agent.rsplit(\".\", 1)\n agent_cls = getattr(importlib.import_module(agent_module), agent_name)\n agent_classes.append(agent_cls)\n players.append(sc2_env.Agent(sc2_env.Race[FLAGS.agent_race],\n FLAGS.agent_name or agent_name))\n\n if map_inst.players >= 2:\n if FLAGS.agent2 == \"Bot\":\n players.append(sc2_env.Bot(sc2_env.Race[FLAGS.agent2_race],\n sc2_env.Difficulty[FLAGS.difficulty],\n sc2_env.BotBuild[FLAGS.bot_build]))\n else:\n agent_module, agent_name = FLAGS.agent2.rsplit(\".\", 1)\n agent_cls = getattr(importlib.import_module(agent_module), agent_name)\n agent_classes.append(agent_cls)\n players.append(sc2_env.Agent(sc2_env.Race[FLAGS.agent2_race],\n FLAGS.agent2_name or agent_name))\n\n threads = []\n for _ in range(FLAGS.parallel - 1):\n t = threading.Thread(target=run_thread,\n args=(agent_classes, players, FLAGS.map, False))\n threads.append(t)\n t.start()\n\n run_thread(agent_classes, players, FLAGS.map, FLAGS.render)\n\n for t in threads:\n t.join()\n\n if FLAGS.profile:\n print(stopwatch.sw)\n\n\ndef entry_point(): # Needed so setup.py scripts work.\n app.run(main)\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/agent_remote.py",
"content": "#!/usr/bin/python\n# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\nr\"\"\"Play an agent with an SC2 instance that isn't owned.\n\nThis can be used to play on the sc2ai.net ladder, as well as to play vs humans.\n\nTo play on ladder:\n $ python -m pysc2.bin.agent_remote --agent \\\n --host_port --lan_port \n\nTo play vs humans:\n $ python -m pysc2.bin.agent_remote --human --map \nthen copy the string it generates which is something similar to above\n\nIf you want to play remotely, you'll need to port forward (eg with ssh -L or -R)\nthe host_port from localhost on one machine to localhost on the other.\n\nYou can also set your race, observation options, etc by cmdline flags.\n\nWhen playing vs humans it launches both instances on the human side. This means\nyou only need to port-forward a single port (ie the websocket betwen SC2 and the\nagent), but you also need to transfer the entire observation, which is much\nbigger than the actions transferred over the lan connection between the two SC2\ninstances. It also makes it easy to maintain version compatibility since they\nare the same binary. Unfortunately it means higher cpu usage where the human is\nplaying, which on a Mac becomes problematic as OSX slows down the instance\nrunning in the background. There can also be observation differences between\nMac/Win and Linux. For these reasons, prefer play_vs_agent which runs the\ninstance next to the agent, and tunnels the lan actions instead.\n\"\"\"\n\nimport getpass\nimport importlib\nimport platform\nimport sys\nimport time\n\nfrom absl import app\nfrom absl import flags\nfrom absl import logging\n\nfrom pysc2 import maps\nfrom pysc2 import run_configs\nfrom pysc2.env import remote_sc2_env\nfrom pysc2.env import run_loop\nfrom pysc2.env import sc2_env\nfrom pysc2.lib import point_flag\nfrom pysc2.lib import portspicker\nfrom pysc2.lib import renderer_human\n\nfrom s2clientprotocol import sc2api_pb2 as sc_pb\n\nFLAGS = flags.FLAGS\nflags.DEFINE_bool(\"render\", platform.system() == \"Linux\",\n \"Whether to render with pygame.\")\nflags.DEFINE_bool(\"realtime\", False, \"Whether to run in realtime mode.\")\n\nflags.DEFINE_string(\"agent\", \"pysc2.agents.random_agent.RandomAgent\",\n \"Which agent to run, as a python path to an Agent class.\")\nflags.DEFINE_string(\"agent_name\", None,\n \"Name of the agent in replays. Defaults to the class name.\")\nflags.DEFINE_enum(\"agent_race\", \"random\", sc2_env.Race._member_names_, # pylint: disable=protected-access\n \"Agent's race.\")\n\nflags.DEFINE_float(\"fps\", 22.4, \"Frames per second to run the game.\")\nflags.DEFINE_integer(\"step_mul\", 8, \"Game steps per agent step.\")\n\npoint_flag.DEFINE_point(\"feature_screen_size\", \"84\",\n \"Resolution for screen feature layers.\")\npoint_flag.DEFINE_point(\"feature_minimap_size\", \"64\",\n \"Resolution for minimap feature layers.\")\npoint_flag.DEFINE_point(\"rgb_screen_size\", \"256\",\n \"Resolution for rendered screen.\")\npoint_flag.DEFINE_point(\"rgb_minimap_size\", \"128\",\n \"Resolution for rendered minimap.\")\nflags.DEFINE_enum(\"action_space\", \"FEATURES\",\n sc2_env.ActionSpace._member_names_, # pylint: disable=protected-access\n \"Which action space to use. Needed if you take both feature \"\n \"and rgb observations.\")\nflags.DEFINE_bool(\"use_feature_units\", False,\n \"Whether to include feature units.\")\n\nflags.DEFINE_string(\"user_name\", getpass.getuser(),\n \"Name of the human player for replays.\")\nflags.DEFINE_enum(\"user_race\", \"random\", sc2_env.Race._member_names_, # pylint: disable=protected-access\n \"User's race.\")\n\nflags.DEFINE_string(\"host\", \"127.0.0.1\", \"Game Host\")\nflags.DEFINE_integer(\"host_port\", None, \"Host port\")\nflags.DEFINE_integer(\"lan_port\", None, \"Host port\")\n\nflags.DEFINE_string(\"map\", None, \"Name of a map to use to play.\")\n\nflags.DEFINE_bool(\"human\", False, \"Whether to host a game as a human.\")\n\nflags.DEFINE_integer(\"timeout_seconds\", 300,\n \"Time in seconds for the remote agent to connect to the \"\n \"game before an exception is raised.\")\n\n\ndef main(unused_argv):\n if FLAGS.human:\n human()\n else:\n agent()\n\n\ndef agent():\n \"\"\"Run the agent, connecting to a (remote) host started independently.\"\"\"\n agent_module, agent_name = FLAGS.agent.rsplit(\".\", 1)\n agent_cls = getattr(importlib.import_module(agent_module), agent_name)\n\n logging.info(\"Starting agent:\")\n with remote_sc2_env.RemoteSC2Env(\n map_name=FLAGS.map,\n host=FLAGS.host,\n host_port=FLAGS.host_port,\n lan_port=FLAGS.lan_port,\n name=FLAGS.agent_name or agent_name,\n race=sc2_env.Race[FLAGS.agent_race],\n step_mul=FLAGS.step_mul,\n agent_interface_format=sc2_env.parse_agent_interface_format(\n feature_screen=FLAGS.feature_screen_size,\n feature_minimap=FLAGS.feature_minimap_size,\n rgb_screen=FLAGS.rgb_screen_size,\n rgb_minimap=FLAGS.rgb_minimap_size,\n action_space=FLAGS.action_space,\n use_feature_units=FLAGS.use_feature_units),\n visualize=FLAGS.render) as env:\n agents = [agent_cls()]\n logging.info(\"Connected, starting run_loop.\")\n try:\n run_loop.run_loop(agents, env)\n except remote_sc2_env.RestartError:\n pass\n logging.info(\"Done.\")\n\n\ndef human():\n \"\"\"Run a host which expects one player to connect remotely.\"\"\"\n run_config = run_configs.get()\n\n map_inst = maps.get(FLAGS.map)\n\n if not FLAGS.rgb_screen_size or not FLAGS.rgb_minimap_size:\n logging.info(\"Use --rgb_screen_size and --rgb_minimap_size if you want rgb \"\n \"observations.\")\n\n ports = portspicker.pick_contiguous_unused_ports(4) # 2 * num_players\n host_proc = run_config.start(extra_ports=ports, host=FLAGS.host,\n timeout_seconds=FLAGS.timeout_seconds,\n window_loc=(50, 50))\n client_proc = run_config.start(extra_ports=ports, host=FLAGS.host,\n connect=False, window_loc=(700, 50))\n\n create = sc_pb.RequestCreateGame(\n realtime=FLAGS.realtime, local_map=sc_pb.LocalMap(map_path=map_inst.path))\n create.player_setup.add(type=sc_pb.Participant)\n create.player_setup.add(type=sc_pb.Participant)\n\n controller = host_proc.controller\n controller.save_map(map_inst.path, map_inst.data(run_config))\n controller.create_game(create)\n\n print(\"-\" * 80)\n print(\"Join host: agent_remote --map %s --host %s --host_port %s \"\n \"--lan_port %s\" % (FLAGS.map, FLAGS.host, client_proc.port, ports[0]))\n print(\"-\" * 80)\n sys.stdout.flush()\n\n join = sc_pb.RequestJoinGame()\n join.shared_port = 0 # unused\n join.server_ports.game_port = ports.pop(0)\n join.server_ports.base_port = ports.pop(0)\n join.client_ports.add(game_port=ports.pop(0), base_port=ports.pop(0))\n\n join.race = sc2_env.Race[FLAGS.user_race]\n join.player_name = FLAGS.user_name\n if FLAGS.render:\n join.options.raw = True\n join.options.score = True\n if FLAGS.feature_screen_size and FLAGS.feature_minimap_size:\n fl = join.options.feature_layer\n fl.width = 24\n FLAGS.feature_screen_size.assign_to(fl.resolution)\n FLAGS.feature_minimap_size.assign_to(fl.minimap_resolution)\n if FLAGS.rgb_screen_size and FLAGS.rgb_minimap_size:\n FLAGS.rgb_screen_size.assign_to(join.options.render.resolution)\n FLAGS.rgb_minimap_size.assign_to(join.options.render.minimap_resolution)\n controller.join_game(join)\n\n if FLAGS.render:\n renderer = renderer_human.RendererHuman(\n fps=FLAGS.fps, render_feature_grid=False)\n renderer.run(run_configs.get(), controller, max_episodes=1)\n else: # Still step forward so the Mac/Windows renderer works.\n try:\n while True:\n frame_start_time = time.time()\n if not FLAGS.realtime:\n controller.step()\n obs = controller.observe()\n\n if obs.player_result:\n break\n time.sleep(max(0, frame_start_time - time.time() + 1 / FLAGS.fps))\n except KeyboardInterrupt:\n pass\n\n for p in [host_proc, client_proc]:\n p.close()\n\n portspicker.return_ports(ports)\n\n\ndef entry_point(): # Needed so setup.py scripts work.\n app.run(main)\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/battle_net_maps.py",
"content": "#!/usr/bin/python\n# Copyright 2019 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Print the list of available maps according to the game.\"\"\"\n\nfrom absl import app\n\nfrom pysc2 import run_configs\n\n\ndef main(unused_argv):\n with run_configs.get().start(want_rgb=False) as controller:\n available_maps = controller.available_maps()\n print(\"\\n\")\n print(\"Local map paths:\")\n for m in sorted(available_maps.local_map_paths):\n print(\" \", m)\n print()\n print(\"Battle.net maps:\")\n for m in sorted(available_maps.battlenet_map_names):\n print(\" \", m)\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/benchmark_observe.py",
"content": "#!/usr/bin/python\n# Copyright 2018 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Benchmark observation times.\"\"\"\n\nimport time\n\nfrom absl import app\nfrom absl import flags\n\nfrom pysc2 import maps\nfrom pysc2 import run_configs\nfrom pysc2.lib import replay\nfrom pysc2.lib import stopwatch\n\nfrom s2clientprotocol import common_pb2 as sc_common\nfrom s2clientprotocol import sc2api_pb2 as sc_pb\n\n\nflags.DEFINE_integer(\"count\", 1000, \"How many observations to run.\")\nflags.DEFINE_integer(\"step_mul\", 16, \"How many game steps per observation.\")\nflags.DEFINE_string(\"replay\", None, \"Which replay to run.\")\nflags.DEFINE_string(\"map\", \"Catalyst\", \"Which map to run.\")\nFLAGS = flags.FLAGS\n\n\ndef interface_options(score=False, raw=False, features=None, rgb=None,\n crop=True):\n \"\"\"Get an InterfaceOptions for the config.\"\"\"\n interface = sc_pb.InterfaceOptions()\n interface.score = score\n interface.raw = raw\n if features:\n if isinstance(features, int):\n screen, minimap = features, features\n else:\n screen, minimap = features\n interface.feature_layer.width = 24\n interface.feature_layer.resolution.x = screen\n interface.feature_layer.resolution.y = screen\n interface.feature_layer.minimap_resolution.x = minimap\n interface.feature_layer.minimap_resolution.y = minimap\n interface.feature_layer.crop_to_playable_area = crop\n if rgb:\n if isinstance(rgb, int):\n screen, minimap = rgb, rgb\n else:\n screen, minimap = rgb\n interface.render.resolution.x = screen\n interface.render.resolution.y = screen\n interface.render.minimap_resolution.x = minimap\n interface.render.minimap_resolution.y = minimap\n return interface\n\n\nconfigs = [\n (\"raw\", interface_options(raw=True)),\n (\"raw-feat-48\", interface_options(raw=True, features=48)),\n (\"raw-feat-128\", interface_options(raw=True, features=128)),\n (\"raw-feat-128-48\", interface_options(raw=True, features=(128, 48))),\n (\"feat-32\", interface_options(features=32)),\n (\"feat-48\", interface_options(features=48)),\n (\"feat-72-no-crop\", interface_options(features=72, crop=False)),\n (\"feat-72\", interface_options(features=72)),\n (\"feat-96\", interface_options(features=96)),\n (\"feat-128\", interface_options(features=128)),\n (\"rgb-64\", interface_options(rgb=64)),\n (\"rgb-128\", interface_options(rgb=128)),\n]\n\n\ndef main(unused_argv):\n stopwatch.sw.enable()\n\n results = []\n try:\n for config, interface in configs:\n print((\" Starting: %s \" % config).center(60, \"-\"))\n timeline = []\n\n run_config = run_configs.get()\n\n if FLAGS.replay:\n replay_data = run_config.replay_data(FLAGS.replay)\n start_replay = sc_pb.RequestStartReplay(\n replay_data=replay_data, options=interface, disable_fog=False,\n observed_player_id=2)\n version = replay.get_replay_version(replay_data)\n run_config = run_configs.get(version=version) # Replace the run config.\n else:\n map_inst = maps.get(FLAGS.map)\n create = sc_pb.RequestCreateGame(\n realtime=False, disable_fog=False, random_seed=1,\n local_map=sc_pb.LocalMap(map_path=map_inst.path,\n map_data=map_inst.data(run_config)))\n create.player_setup.add(type=sc_pb.Participant)\n create.player_setup.add(type=sc_pb.Computer, race=sc_common.Terran,\n difficulty=sc_pb.VeryEasy)\n join = sc_pb.RequestJoinGame(options=interface, race=sc_common.Protoss)\n\n with run_config.start(\n want_rgb=interface.HasField(\"render\")) as controller:\n\n if FLAGS.replay:\n info = controller.replay_info(replay_data)\n print(\" Replay info \".center(60, \"-\"))\n print(info)\n print(\"-\" * 60)\n if info.local_map_path:\n start_replay.map_data = run_config.map_data(info.local_map_path)\n controller.start_replay(start_replay)\n else:\n controller.create_game(create)\n controller.join_game(join)\n\n for _ in range(FLAGS.count):\n controller.step(FLAGS.step_mul)\n start = time.time()\n obs = controller.observe()\n timeline.append(time.time() - start)\n if obs.player_result:\n break\n\n results.append((config, timeline))\n except KeyboardInterrupt:\n pass\n\n names, values = zip(*results)\n\n print(\"\\n\\nTimeline:\\n\")\n print(\",\".join(names))\n for times in zip(*values):\n print(\",\".join(\"%0.2f\" % (t * 1000) for t in times))\n\n print(stopwatch.sw)\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/benchmark_replay.py",
"content": "#!/usr/bin/python\n# Copyright 2018 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Benchmark observation times.\"\"\"\n\nfrom absl import app\nfrom absl import flags\nfrom pysc2 import run_configs\nfrom pysc2.lib import actions\nfrom pysc2.lib import features\nfrom pysc2.lib import point_flag\nfrom pysc2.lib import replay\nfrom pysc2.lib import stopwatch\n\nfrom s2clientprotocol import sc2api_pb2 as sc_pb\n\nFLAGS = flags.FLAGS\nflags.DEFINE_integer(\"step_mul\", 8, \"Game steps per observation.\")\npoint_flag.DEFINE_point(\"feature_screen_size\", \"64\",\n \"Resolution for screen feature layers.\")\npoint_flag.DEFINE_point(\"feature_minimap_size\", \"64\",\n \"Resolution for minimap feature layers.\")\npoint_flag.DEFINE_point(\"rgb_screen_size\", None,\n \"Resolution for rendered screen.\")\npoint_flag.DEFINE_point(\"rgb_minimap_size\", None,\n \"Resolution for rendered minimap.\")\nflags.DEFINE_bool(\"use_feature_units\", True,\n \"Whether to include feature units.\")\nflags.DEFINE_bool(\"use_raw_units\", True,\n \"Whether to include raw units.\")\nflags.DEFINE_string(\"replay\", None, \"Name of a replay to show.\")\nflags.DEFINE_string(\"map_path\", None, \"Override the map for this replay.\")\nflags.mark_flag_as_required(\"replay\")\n\n\ndef main(argv):\n if len(argv) > 1:\n raise app.UsageError(\"Too many command-line arguments.\")\n\n stopwatch.sw.enable()\n\n interface = sc_pb.InterfaceOptions()\n interface.raw = FLAGS.use_feature_units or FLAGS.use_raw_units\n interface.score = True\n interface.feature_layer.width = 24\n if FLAGS.feature_screen_size and FLAGS.feature_minimap_size:\n FLAGS.feature_screen_size.assign_to(interface.feature_layer.resolution)\n FLAGS.feature_minimap_size.assign_to(\n interface.feature_layer.minimap_resolution)\n if FLAGS.rgb_screen_size and FLAGS.rgb_minimap_size:\n FLAGS.rgb_screen_size.assign_to(interface.render.resolution)\n FLAGS.rgb_minimap_size.assign_to(interface.render.minimap_resolution)\n\n run_config = run_configs.get()\n replay_data = run_config.replay_data(FLAGS.replay)\n start_replay = sc_pb.RequestStartReplay(\n replay_data=replay_data,\n options=interface,\n observed_player_id=1)\n version = replay.get_replay_version(replay_data)\n run_config = run_configs.get(version=version) # Replace the run config.\n\n try:\n with run_config.start(\n want_rgb=interface.HasField(\"render\")) as controller:\n info = controller.replay_info(replay_data)\n print(\" Replay info \".center(60, \"-\"))\n print(info)\n print(\"-\" * 60)\n map_path = FLAGS.map_path or info.local_map_path\n if map_path:\n start_replay.map_data = run_config.map_data(map_path)\n controller.start_replay(start_replay)\n\n feats = features.features_from_game_info(\n game_info=controller.game_info(),\n use_feature_units=FLAGS.use_feature_units,\n use_raw_units=FLAGS.use_raw_units,\n use_unit_counts=interface.raw,\n use_camera_position=False,\n action_space=actions.ActionSpace.FEATURES)\n\n while True:\n controller.step(FLAGS.step_mul)\n obs = controller.observe()\n feats.transform_obs(obs)\n if obs.player_result:\n break\n except KeyboardInterrupt:\n pass\n\n print(stopwatch.sw)\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/check_apm.py",
"content": "# Copyright 2018 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Test the apm values of various actions.\"\"\"\n\nimport random\n\nfrom absl import app\nfrom pysc2 import maps\nfrom pysc2 import run_configs\nfrom pysc2.lib import actions\nfrom pysc2.lib import features\nfrom pysc2.lib import point\nfrom pysc2.lib import units\n\nfrom s2clientprotocol import common_pb2 as sc_common\nfrom s2clientprotocol import error_pb2 as sc_error\nfrom s2clientprotocol import sc2api_pb2 as sc_pb\n\n\ndef get_units(obs, filter_fn=None, owner=None, unit_type=None, tag=None):\n \"\"\"Return a dict of units that match the filter.\"\"\"\n if unit_type and not isinstance(unit_type, (list, tuple)):\n unit_type = (unit_type,)\n return {u.tag: u for u in obs.observation.raw_data.units # pylint: disable=g-complex-comprehension\n if ((filter_fn is None or filter_fn(u)) and\n (owner is None or u.owner == owner) and\n (unit_type is None or u.unit_type in unit_type) and\n (tag is None or u.tag == tag))}\n\n\ndef get_unit(*args, **kwargs):\n \"\"\"Return the first unit that matches, or None.\"\"\"\n try:\n return next(iter(get_units(*args, **kwargs).values()))\n except StopIteration:\n return None\n\n\ndef _xy_locs(mask):\n \"\"\"Mask should be a set of bools from comparison with a feature layer.\"\"\"\n ys, xs = mask.nonzero()\n return [point.Point(x, y) for x, y in zip(xs, ys)]\n\n\nclass Env(object):\n \"\"\"Test the apm values of various actions.\"\"\"\n\n def __init__(self):\n run_config = run_configs.get()\n map_inst = maps.get(\"Flat64\")\n self._map_path = map_inst.path\n self._map_data = map_inst.data(run_config)\n\n self._sc2_proc = run_config.start(want_rgb=False)\n self._controller = self._sc2_proc.controller\n self._summary = []\n self._features = None\n\n def close(self):\n self._controller.quit()\n self._sc2_proc.close()\n\n print(\" apm name\")\n for name, info in self._summary:\n print(\"%4d %s\" % (info.player_info[0].player_apm, name))\n\n def __enter__(self):\n return self\n\n def __exit__(self, unused_exception_type, unused_exc_value, unused_traceback):\n self.close()\n\n def __del__(self):\n self.close()\n\n def step(self, count=22):\n self._controller.step(count)\n return self._controller.observe()\n\n def fl_obs(self, obs):\n return self._features.transform_obs(obs)\n\n def raw_unit_command(self, ability_id, unit_tags, pos=None, target=None):\n \"\"\"Send a raw unit command.\"\"\"\n if isinstance(ability_id, str):\n ability_id = actions.FUNCTIONS[ability_id].ability_id\n action = sc_pb.Action()\n cmd = action.action_raw.unit_command\n cmd.ability_id = ability_id\n if isinstance(unit_tags, (list, tuple)):\n cmd.unit_tags.extend(unit_tags)\n else:\n cmd.unit_tags.append(unit_tags)\n if pos:\n cmd.target_world_space_pos.x = pos[0]\n cmd.target_world_space_pos.y = pos[1]\n elif target:\n cmd.target_unit_tag = target\n response = self._controller.act(action)\n for result in response.result:\n assert result == sc_error.Success\n\n def fl_action(self, obs, act, *args):\n return self._controller.act(self._features.transform_action(\n obs.observation, actions.FUNCTIONS[act](*args), skip_available=True))\n\n def check_apm(self, name):\n \"\"\"Set up a game, yield, then check the apm in the replay.\"\"\"\n interface = sc_pb.InterfaceOptions(raw=True, score=False)\n interface.feature_layer.width = 24\n interface.feature_layer.resolution.x = 64\n interface.feature_layer.resolution.y = 64\n interface.feature_layer.minimap_resolution.x = 64\n interface.feature_layer.minimap_resolution.y = 64\n\n create = sc_pb.RequestCreateGame(\n random_seed=1, local_map=sc_pb.LocalMap(map_path=self._map_path,\n map_data=self._map_data))\n create.player_setup.add(type=sc_pb.Participant)\n create.player_setup.add(type=sc_pb.Computer, race=sc_common.Protoss,\n difficulty=sc_pb.VeryEasy)\n\n join = sc_pb.RequestJoinGame(race=sc_common.Protoss, options=interface)\n\n self._controller.create_game(create)\n self._controller.join_game(join)\n\n self._info = self._controller.game_info()\n self._features = features.features_from_game_info(\n self._info, use_feature_units=True, use_raw_units=True)\n self._map_size = point.Point.build(self._info.start_raw.map_size)\n\n for i in range(60):\n yield i, self.step()\n\n data = self._controller.save_replay()\n replay_info = self._controller.replay_info(data)\n self._summary.append((name, replay_info))\n\n\ndef main(unused_argv):\n env = Env()\n\n def rand_fl_coord():\n return (point.Point.unit_rand() * 64).floor()\n\n def rand_world_coord():\n return (point.Point.unit_rand() * 20).floor() + 20\n\n def random_probe_loc(obs):\n return random.choice(_xy_locs(\n env.fl_obs(obs).feature_screen.unit_type == units.Protoss.Probe))\n\n def random_probe_tag(obs):\n return random.choice(get_units(obs, unit_type=units.Protoss.Probe).keys())\n\n for i, obs in env.check_apm(\"no-op\"):\n pass\n\n for i, obs in env.check_apm(\"fl stop, single probe\"):\n if i == 0:\n env.fl_action(obs, \"select_point\", \"select\", random_probe_loc(obs))\n env.fl_action(obs, \"Stop_quick\", \"now\")\n\n for i, obs in env.check_apm(\"fl smart, single probe, random location\"):\n if i == 0:\n env.fl_action(obs, \"select_point\", \"select\", random_probe_loc(obs))\n env.fl_action(obs, \"Smart_screen\", \"now\", rand_fl_coord())\n\n for i, obs in env.check_apm(\"fl move, single probe, random location\"):\n if i == 0:\n env.fl_action(obs, \"select_point\", \"select\", random_probe_loc(obs))\n env.fl_action(obs, \"Move_screen\", \"now\", rand_fl_coord())\n\n for i, obs in env.check_apm(\"fl stop, random probe\"):\n env.fl_action(obs, \"select_point\", \"select\", random_probe_loc(obs))\n env.fl_action(obs, \"Stop_quick\", \"now\")\n\n for i, obs in env.check_apm(\"fl move, random probe, random location\"):\n env.fl_action(obs, \"select_point\", \"select\", random_probe_loc(obs))\n env.fl_action(obs, \"Move_screen\", \"now\", rand_fl_coord())\n\n for i, obs in env.check_apm(\"raw stop, random probe\"):\n env.raw_unit_command(\"Stop_quick\", random_probe_tag(obs))\n\n for i, obs in env.check_apm(\"raw move, random probe, random location\"):\n env.raw_unit_command(\"Move_screen\", random_probe_tag(obs),\n rand_world_coord())\n\n probe = None\n for i, obs in env.check_apm(\"raw move, single probe, random location\"):\n if not probe:\n probe = random_probe_tag(obs)\n env.raw_unit_command(\"Move_screen\", probe, rand_world_coord())\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/compare_binaries.py",
"content": "#!/usr/bin/python\n# Copyright 2019 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Compare the observations from multiple binaries.\"\"\"\n\nimport collections\nimport sys\n\nfrom absl import app\nfrom absl import flags\nfrom pysc2 import run_configs\nfrom pysc2.lib import image_differencer\nfrom pysc2.lib import proto_diff\nfrom pysc2.lib import remote_controller\nfrom pysc2.lib import replay\nfrom pysc2.lib import stopwatch\n\nfrom s2clientprotocol import sc2api_pb2 as sc_pb\n\n\nFLAGS = flags.FLAGS\n\nflags.DEFINE_bool(\"diff\", False, \"Whether to diff the observations.\")\nflags.DEFINE_integer(\"truncate\", 0,\n \"Number of characters to truncate diff values to, or 0 \"\n \"for no truncation.\")\n\nflags.DEFINE_integer(\"step_mul\", 8, \"Game steps per observation.\")\nflags.DEFINE_integer(\"count\", 100000, \"How many observations to run.\")\nflags.DEFINE_string(\"replay\", None, \"Name of a replay to show.\")\n\n\ndef _clear_non_deterministic_fields(obs):\n for unit in obs.observation.raw_data.units:\n unit.ClearField(\"tag\")\n for order in unit.orders:\n order.ClearField(\"target_unit_tag\")\n\n for action in obs.actions:\n if action.HasField(\"action_raw\"):\n if action.action_raw.HasField(\"unit_command\"):\n action.action_raw.unit_command.ClearField(\"target_unit_tag\")\n\n\ndef _is_remote(arg):\n return \":\" in arg\n\n\ndef main(argv):\n \"\"\"Compare the observations from multiple binaries.\"\"\"\n if len(argv) <= 1:\n sys.exit(\n \"Please specify binaries to run / to connect to. For binaries to run, \"\n \"specify the executable name. For remote connections, specify \"\n \":. The version must match the replay.\")\n\n targets = argv[1:]\n\n interface = sc_pb.InterfaceOptions()\n interface.raw = True\n interface.raw_affects_selection = True\n interface.raw_crop_to_playable_area = True\n interface.score = True\n interface.show_cloaked = True\n interface.show_placeholders = True\n interface.feature_layer.width = 24\n interface.feature_layer.resolution.x = 48\n interface.feature_layer.resolution.y = 48\n interface.feature_layer.minimap_resolution.x = 48\n interface.feature_layer.minimap_resolution.y = 48\n interface.feature_layer.crop_to_playable_area = True\n interface.feature_layer.allow_cheating_layers = True\n\n run_config = run_configs.get()\n replay_data = run_config.replay_data(FLAGS.replay)\n start_replay = sc_pb.RequestStartReplay(\n replay_data=replay_data,\n options=interface,\n observed_player_id=1,\n realtime=False)\n version = replay.get_replay_version(replay_data)\n\n timers = []\n controllers = []\n procs = []\n for target in targets:\n timer = stopwatch.StopWatch()\n timers.append(timer)\n with timer(\"launch\"):\n if _is_remote(target):\n host, port = target.split(\":\")\n controllers.append(remote_controller.RemoteController(host, int(port)))\n else:\n proc = run_configs.get(\n version=version._replace(binary=target)).start(want_rgb=False)\n procs.append(proc)\n controllers.append(proc.controller)\n\n diff_counts = [0] * len(controllers)\n diff_paths = collections.Counter()\n\n try:\n print(\"-\" * 80)\n print(controllers[0].replay_info(replay_data))\n print(\"-\" * 80)\n\n for controller, t in zip(controllers, timers):\n with t(\"start_replay\"):\n controller.start_replay(start_replay)\n\n # Check the static data.\n static_data = []\n for controller, t in zip(controllers, timers):\n with t(\"data\"):\n static_data.append(controller.data_raw())\n\n if FLAGS.diff:\n diffs = {i: proto_diff.compute_diff(static_data[0], d)\n for i, d in enumerate(static_data[1:], 1)}\n if any(diffs.values()):\n print(\" Diff in static data \".center(80, \"-\"))\n for i, diff in diffs.items():\n if diff:\n print(targets[i])\n diff_counts[i] += 1\n print(diff.report(truncate_to=FLAGS.truncate))\n for path in diff.all_diffs():\n diff_paths[path.with_anonymous_array_indices()] += 1\n else:\n print(\"No diffs in static data.\")\n\n # Run some steps, checking speed and diffing the observations.\n for _ in range(FLAGS.count):\n for controller, t in zip(controllers, timers):\n with t(\"step\"):\n controller.step(FLAGS.step_mul)\n\n obs = []\n for controller, t in zip(controllers, timers):\n with t(\"observe\"):\n obs.append(controller.observe())\n\n if FLAGS.diff:\n for o in obs:\n _clear_non_deterministic_fields(o)\n\n diffs = {i: proto_diff.compute_diff(obs[0], o)\n for i, o in enumerate(obs[1:], 1)}\n if any(diffs.values()):\n print((\" Diff on step: %s \" %\n obs[0].observation.game_loop).center(80, \"-\"))\n for i, diff in diffs.items():\n if diff:\n print(targets[i])\n diff_counts[i] += 1\n print(diff.report([image_differencer.image_differencer],\n truncate_to=FLAGS.truncate))\n for path in diff.all_diffs():\n diff_paths[path.with_anonymous_array_indices()] += 1\n\n if obs[0].player_result:\n break\n except KeyboardInterrupt:\n pass\n finally:\n for c in controllers:\n c.quit()\n c.close()\n\n for p in procs:\n p.close()\n\n if FLAGS.diff:\n print(\" Diff Counts by target \".center(80, \"-\"))\n for target, count in zip(targets, diff_counts):\n print(\" %5d %s\" % (count, target))\n print()\n\n print(\" Diff Counts by observation path \".center(80, \"-\"))\n for path, count in diff_paths.most_common(100):\n print(\" %5d %s\" % (count, path))\n print()\n\n print(\" Timings \".center(80, \"-\"))\n for v, t in zip(targets, timers):\n print(v)\n print(t)\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/gen_actions.py",
"content": "#!/usr/bin/python\n# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Generate the action definitions for actions.py.\"\"\"\n\nimport itertools\n\nfrom absl import app\nfrom absl import flags\nfrom pysc2 import maps\nfrom pysc2 import run_configs\nfrom pysc2.lib import static_data\n\nfrom s2clientprotocol import common_pb2 as sc_common\nfrom s2clientprotocol import data_pb2 as sc_data\nfrom s2clientprotocol import sc2api_pb2 as sc_pb\n\n\nflags.DEFINE_enum(\"command\", None, [\"csv\", \"python\"], \"What to generate.\")\nflags.DEFINE_string(\"map\", \"Acropolis\", \"Which map to use.\")\nflags.mark_flag_as_required(\"command\")\nFLAGS = flags.FLAGS\n\n\ndef get_data():\n \"\"\"Retrieve static data from the game.\"\"\"\n run_config = run_configs.get()\n\n with run_config.start(want_rgb=False) as controller:\n m = maps.get(FLAGS.map)\n create = sc_pb.RequestCreateGame(local_map=sc_pb.LocalMap(\n map_path=m.path, map_data=m.data(run_config)))\n create.player_setup.add(type=sc_pb.Participant)\n create.player_setup.add(type=sc_pb.Computer, race=sc_common.Random,\n difficulty=sc_pb.VeryEasy)\n join = sc_pb.RequestJoinGame(race=sc_common.Random,\n options=sc_pb.InterfaceOptions(raw=True))\n\n controller.create_game(create)\n controller.join_game(join)\n return controller.data()\n\n\ndef generate_name(ability):\n return (ability.friendly_name or ability.button_name or\n ability.link_name)\n\n\ndef sort_key(data, ability):\n # Alphabetical, with specifics immediately after their generals.\n name = generate_name(ability)\n if ability.remaps_to_ability_id:\n general = data.abilities[ability.remaps_to_ability_id]\n name = \"%s %s\" % (generate_name(general), name)\n return name\n\n\ndef generate_csv(data):\n \"\"\"Generate a CSV of the abilities for easy commenting.\"\"\"\n print(\",\".join([\n \"ability_id\",\n \"link_name\",\n \"link_index\",\n \"button_name\",\n \"hotkey\",\n \"friendly_name\",\n \"remap_to\",\n \"mismatch\",\n ]))\n for ability in sorted(data.abilities.values(),\n key=lambda a: sort_key(data, a)):\n ab_id = ability.ability_id\n if ab_id in skip_abilities or (ab_id not in data.general_abilities and\n ab_id not in used_abilities):\n continue\n\n general = \"\"\n if ab_id in data.general_abilities:\n general = \"general\"\n elif ability.remaps_to_ability_id:\n general = ability.remaps_to_ability_id\n\n mismatch = \"\"\n if ability.remaps_to_ability_id:\n def check_mismatch(ability, parent, attr):\n if getattr(ability, attr) != getattr(parent, attr):\n return \"%s: %s\" % (attr, getattr(ability, attr))\n\n parent = data.abilities[ability.remaps_to_ability_id]\n mismatch = \"; \".join(filter(None, [\n check_mismatch(ability, parent, \"available\"),\n check_mismatch(ability, parent, \"target\"),\n check_mismatch(ability, parent, \"allow_minimap\"),\n check_mismatch(ability, parent, \"allow_autocast\"),\n check_mismatch(ability, parent, \"is_building\"),\n check_mismatch(ability, parent, \"footprint_radius\"),\n check_mismatch(ability, parent, \"is_instant_placement\"),\n check_mismatch(ability, parent, \"cast_range\"),\n ]))\n\n print(\",\".join(map(str, [\n ability.ability_id,\n ability.link_name,\n ability.link_index,\n ability.button_name,\n ability.hotkey,\n ability.friendly_name,\n general,\n mismatch,\n ])))\n\n\ndef generate_py_abilities(data):\n \"\"\"Generate the list of functions in actions.py.\"\"\"\n def print_action(func_id, name, func, ab_id, general_id):\n args = [func_id, '\"%s\"' % name, func, ab_id]\n if general_id:\n args.append(general_id)\n print(\" Function.ability(%s),\" % \", \".join(str(v) for v in args))\n\n func_ids = itertools.count(12) # Leave room for the ui funcs.\n for ability in sorted(data.abilities.values(),\n key=lambda a: sort_key(data, a)):\n ab_id = ability.ability_id\n if ab_id in skip_abilities or (ab_id not in data.general_abilities and\n ab_id not in used_abilities):\n continue\n\n name = generate_name(ability).replace(\" \", \"_\")\n\n if ability.target in (sc_data.AbilityData.Target.Value(\"None\"),\n sc_data.AbilityData.PointOrNone):\n print_action(next(func_ids), name + \"_quick\", \"cmd_quick\", ab_id,\n ability.remaps_to_ability_id)\n if ability.target != sc_data.AbilityData.Target.Value(\"None\"):\n print_action(next(func_ids), name+ \"_screen\", \"cmd_screen\", ab_id,\n ability.remaps_to_ability_id)\n if ability.allow_minimap:\n print_action(next(func_ids), name + \"_minimap\", \"cmd_minimap\", ab_id,\n ability.remaps_to_ability_id)\n if ability.allow_autocast:\n print_action(next(func_ids), name + \"_autocast\", \"autocast\", ab_id,\n ability.remaps_to_ability_id)\n\n\ndef main(unused_argv):\n data = get_data()\n print(\"-\" * 60)\n\n if FLAGS.command == \"csv\":\n generate_csv(data)\n elif FLAGS.command == \"python\":\n generate_py_abilities(data)\n\nused_abilities = set(static_data.ABILITIES)\n\nfrivolous = {6, 7} # Dance and Cheer\n# These need a slot id and so are exposed differently.\ncancel_slot = {313, 1039, 305, 307, 309, 1832, 1834, 3672}\nunload_unit = {410, 415, 397, 1440, 2373, 1409, 914, 3670}\n\nskip_abilities = cancel_slot | unload_unit | frivolous\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/gen_data.py",
"content": "#!/usr/bin/python\n# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Generate the unit definitions for units.py.\"\"\"\n\nimport collections\n\nfrom absl import app\nfrom pysc2 import maps\nfrom pysc2 import run_configs\nfrom pysc2.lib import static_data\n\nfrom s2clientprotocol import common_pb2 as sc_common\nfrom s2clientprotocol import sc2api_pb2 as sc_pb\n\n\ndef get_data():\n \"\"\"Get the game's static data from an actual game.\"\"\"\n run_config = run_configs.get()\n\n with run_config.start(want_rgb=False) as controller:\n m = maps.get(\"Sequencer\") # Arbitrary ladder map.\n create = sc_pb.RequestCreateGame(local_map=sc_pb.LocalMap(\n map_path=m.path, map_data=m.data(run_config)))\n create.player_setup.add(type=sc_pb.Participant)\n create.player_setup.add(type=sc_pb.Computer, race=sc_common.Random,\n difficulty=sc_pb.VeryEasy)\n join = sc_pb.RequestJoinGame(race=sc_common.Random,\n options=sc_pb.InterfaceOptions(raw=True))\n\n controller.create_game(create)\n controller.join_game(join)\n return controller.data_raw()\n\n\ndef generate_py_units(data):\n \"\"\"Generate the list of units in units.py.\"\"\"\n units = collections.defaultdict(list)\n for unit in sorted(data.units, key=lambda a: a.name):\n if unit.unit_id in static_data.UNIT_TYPES:\n units[unit.race].append(unit)\n\n def print_race(name, race):\n print(\"class %s(enum.IntEnum):\" % name)\n print(' \"\"\"%s units.\"\"\"' % name)\n for unit in units[race]:\n print(\" %s = %s\" % (unit.name, unit.unit_id))\n print(\"\\n\")\n\n print(\" units.py \".center(60, \"-\"))\n print_race(\"Neutral\", sc_common.NoRace)\n print_race(\"Protoss\", sc_common.Protoss)\n print_race(\"Terran\", sc_common.Terran)\n print_race(\"Zerg\", sc_common.Zerg)\n\n\ndef generate_py_buffs(data):\n \"\"\"Generate the list of buffs in buffs.py.\"\"\"\n print(\" buffs.py \".center(60, \"-\"))\n print(\"class Buffs(enum.IntEnum):\")\n print(' \"\"\"The list of buffs, as returned from RequestData.\"\"\"')\n for buff in sorted(data.buffs, key=lambda a: a.name):\n if buff.name and buff.buff_id in static_data.BUFFS:\n print(\" %s = %s\" % (buff.name, buff.buff_id))\n print(\"\\n\")\n\n\ndef generate_py_upgrades(data):\n \"\"\"Generate the list of upgrades in upgrades.py.\"\"\"\n print(\" upgrades.py \".center(60, \"-\"))\n print(\"class Upgrades(enum.IntEnum):\")\n print(' \"\"\"The list of upgrades, as returned from RequestData.\"\"\"')\n for upgrade in sorted(data.upgrades, key=lambda a: a.name):\n if upgrade.name and upgrade.upgrade_id in static_data.UPGRADES:\n print(\" %s = %s\" % (upgrade.name, upgrade.upgrade_id))\n print(\"\\n\")\n\n\ndef main(unused_argv):\n data = get_data()\n generate_py_units(data)\n generate_py_buffs(data)\n generate_py_upgrades(data)\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/gen_versions.py",
"content": "#!/usr/bin/python\n# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Generate the list of versions for run_configs.\"\"\"\n\nfrom absl import app\nimport requests\n\n# raw version of:\n# https://github.com/Blizzard/s2client-proto/blob/master/buildinfo/versions.json\nVERSIONS_FILE = \"https://raw.githubusercontent.com/Blizzard/s2client-proto/master/buildinfo/versions.json\"\n\n\ndef main(argv):\n del argv # Unused.\n\n versions = requests.get(VERSIONS_FILE).json()\n\n for v in versions:\n version_str = v[\"label\"]\n if version_str.count(\".\") == 1:\n version_str += \".0\"\n print(' Version(\"%s\", %i, \"%s\", None),' % (\n version_str, v[\"base-version\"], v[\"data-hash\"]))\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/map_list.py",
"content": "#!/usr/bin/python\n# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Print the list of defined maps.\"\"\"\n\nfrom absl import app\n\nfrom pysc2 import maps\n\n\ndef main(unused_argv):\n for _, map_class in sorted(maps.get_maps().items()):\n mp = map_class()\n if mp.path:\n print(mp, \"\\n\")\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/mem_leak_check.py",
"content": "#!/usr/bin/python\n# Copyright 2018 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Test for memory leaks.\"\"\"\n\n# pylint: disable=g-import-not-at-top\n\nimport collections\nimport random\nimport sys\nimport time\n\nfrom absl import app\nfrom absl import flags\n\ntry:\n import psutil\nexcept ImportError:\n sys.exit(\n \"`psutil` library required to track memory. This can be installed with:\\n\"\n \"$ pip install psutil\\n\"\n \"and needs the python-dev headers installed, for example:\\n\"\n \"$ apt install python-dev\")\n\nfrom pysc2 import maps\nfrom pysc2 import run_configs\nfrom pysc2.lib import protocol\n\nfrom s2clientprotocol import common_pb2 as sc_common\nfrom s2clientprotocol import sc2api_pb2 as sc_pb\n\n# pylint: enable=g-import-not-at-top\n\nraces = {\n \"random\": sc_common.Random,\n \"protoss\": sc_common.Protoss,\n \"terran\": sc_common.Terran,\n \"zerg\": sc_common.Zerg,\n}\n\n\nflags.DEFINE_integer(\"mem_limit\", 2000, \"Max memory usage in Mb.\")\nflags.DEFINE_integer(\"episodes\", 200, \"Max number of episodes.\")\nflags.DEFINE_enum(\"race\", \"random\", races.keys(), \"Which race to play as.\")\nflags.DEFINE_list(\"map\", \"Catalyst\", \"Which map(s) to test on.\")\nFLAGS = flags.FLAGS\n\n\nclass Timestep(collections.namedtuple(\n \"Timestep\", [\"episode\", \"time\", \"cpu\", \"memory\", \"name\"])):\n\n def __str__(self):\n return \"[%3d: %7.3f] cpu: %5.1f s, mem: %4d Mb; %s\" % self\n\n\ndef main(unused_argv):\n for m in FLAGS.map: # Verify they're all valid.\n maps.get(m)\n\n interface = sc_pb.InterfaceOptions()\n interface.raw = True\n interface.score = True\n interface.feature_layer.width = 24\n interface.feature_layer.resolution.x = 84\n interface.feature_layer.resolution.y = 84\n interface.feature_layer.minimap_resolution.x = 64\n interface.feature_layer.minimap_resolution.y = 64\n\n timeline = []\n\n start = time.time()\n run_config = run_configs.get()\n proc = run_config.start(want_rgb=interface.HasField(\"render\"))\n process = psutil.Process(proc.pid)\n episode = 1\n\n def add(s):\n cpu_times = process.cpu_times() # pytype: disable=wrong-arg-count\n cpu = cpu_times.user + cpu_times.system\n mem = process.memory_info().rss / 2 ** 20 # In Mb # pytype: disable=wrong-arg-count\n step = Timestep(episode, time.time() - start, cpu, mem, s)\n print(step)\n timeline.append(step)\n if mem > FLAGS.mem_limit:\n raise MemoryError(\"%s Mb mem limit exceeded\" % FLAGS.mem_limit)\n\n try:\n add(\"Started process\")\n\n controller = proc.controller\n for _ in range(FLAGS.episodes):\n map_inst = maps.get(random.choice(FLAGS.map))\n create = sc_pb.RequestCreateGame(\n realtime=False, disable_fog=False, random_seed=episode,\n local_map=sc_pb.LocalMap(map_path=map_inst.path,\n map_data=map_inst.data(run_config)))\n create.player_setup.add(type=sc_pb.Participant)\n create.player_setup.add(type=sc_pb.Computer, race=races[FLAGS.race],\n difficulty=sc_pb.CheatInsane)\n join = sc_pb.RequestJoinGame(race=races[FLAGS.race], options=interface)\n\n controller.create_game(create)\n add(\"Created game on %s\" % map_inst.name)\n controller.join_game(join)\n add(\"Joined game\")\n for i in range(2000):\n controller.step(16)\n obs = controller.observe()\n if obs.player_result:\n add(\"Lost on step %s\" % i)\n break\n if i > 0 and i % 100 == 0:\n add(\"Step %s\" % i)\n episode += 1\n add(\"Done\")\n except KeyboardInterrupt:\n pass\n except (MemoryError, protocol.ConnectionError) as e:\n print(e)\n finally:\n proc.close()\n\n print(\"Timeline:\")\n for t in timeline:\n print(t)\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/play.py",
"content": "#!/usr/bin/python\n# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Run SC2 to play a game or a replay.\"\"\"\n\nimport getpass\nimport platform\nimport sys\nimport time\n\nfrom absl import app\nfrom absl import flags\nfrom pysc2 import maps\nfrom pysc2 import run_configs\nfrom pysc2.env import sc2_env\nfrom pysc2.lib import point_flag\nfrom pysc2.lib import renderer_human\nfrom pysc2.lib import replay\nfrom pysc2.lib import stopwatch\n\nfrom s2clientprotocol import sc2api_pb2 as sc_pb\n\nFLAGS = flags.FLAGS\nflags.DEFINE_bool(\"render\", True, \"Whether to render with pygame.\")\nflags.DEFINE_bool(\"realtime\", False, \"Whether to run in realtime mode.\")\nflags.DEFINE_bool(\"full_screen\", False, \"Whether to run full screen.\")\n\nflags.DEFINE_float(\"fps\", 22.4, \"Frames per second to run the game.\")\nflags.DEFINE_integer(\"step_mul\", 1, \"Game steps per observation.\")\nflags.DEFINE_bool(\"render_sync\", False, \"Turn on sync rendering.\")\npoint_flag.DEFINE_point(\"feature_screen_size\", \"84\",\n \"Resolution for screen feature layers.\")\npoint_flag.DEFINE_point(\"feature_minimap_size\", \"64\",\n \"Resolution for minimap feature layers.\")\nflags.DEFINE_integer(\"feature_camera_width\", 24,\n \"Width of the feature layer camera.\")\npoint_flag.DEFINE_point(\"rgb_screen_size\", \"256,192\",\n \"Resolution for rendered screen.\")\npoint_flag.DEFINE_point(\"rgb_minimap_size\", \"128\",\n \"Resolution for rendered minimap.\")\npoint_flag.DEFINE_point(\"window_size\", \"640,480\",\n \"Screen size if not full screen.\")\nflags.DEFINE_string(\"video\", None, \"Path to render a video of observations.\")\n\nflags.DEFINE_integer(\"max_game_steps\", 0, \"Total game steps to run.\")\nflags.DEFINE_integer(\"max_episode_steps\", 0, \"Total game steps per episode.\")\n\nflags.DEFINE_string(\"user_name\", getpass.getuser(),\n \"Name of the human player for replays.\")\nflags.DEFINE_enum(\"user_race\", \"random\", sc2_env.Race._member_names_, # pylint: disable=protected-access\n \"User's race.\")\nflags.DEFINE_enum(\"bot_race\", \"random\", sc2_env.Race._member_names_, # pylint: disable=protected-access\n \"AI race.\")\nflags.DEFINE_enum(\"difficulty\", \"very_easy\", sc2_env.Difficulty._member_names_, # pylint: disable=protected-access\n \"Bot's strength.\")\nflags.DEFINE_enum(\"bot_build\", \"random\", sc2_env.BotBuild._member_names_, # pylint: disable=protected-access\n \"Bot's build strategy.\")\nflags.DEFINE_bool(\"disable_fog\", False, \"Disable fog of war.\")\nflags.DEFINE_integer(\"observed_player\", 1, \"Which player to observe.\")\n\nflags.DEFINE_bool(\"profile\", False, \"Whether to turn on code profiling.\")\nflags.DEFINE_bool(\"trace\", False, \"Whether to trace the code execution.\")\n\nflags.DEFINE_bool(\"save_replay\", True, \"Whether to save a replay at the end.\")\n\nflags.DEFINE_string(\"map\", None, \"Name of a map to use to play.\")\nflags.DEFINE_bool(\"battle_net_map\", False, \"Use the battle.net map version.\")\n\nflags.DEFINE_string(\"map_path\", None, \"Override the map for this replay.\")\nflags.DEFINE_string(\"replay\", None, \"Name of a replay to show.\")\n\n\ndef main(unused_argv):\n \"\"\"Run SC2 to play a game or a replay.\"\"\"\n if FLAGS.trace:\n stopwatch.sw.trace()\n elif FLAGS.profile:\n stopwatch.sw.enable()\n\n if (FLAGS.map and FLAGS.replay) or (not FLAGS.map and not FLAGS.replay):\n sys.exit(\"Must supply either a map or replay.\")\n\n if FLAGS.replay and not FLAGS.replay.lower().endswith(\"sc2replay\"):\n sys.exit(\"Replay must end in .SC2Replay.\")\n\n if FLAGS.realtime and FLAGS.replay:\n # TODO(tewalds): Support realtime in replays once the game supports it.\n sys.exit(\"realtime isn't possible for replays yet.\")\n\n if FLAGS.render and (FLAGS.realtime or FLAGS.full_screen):\n sys.exit(\"disable pygame rendering if you want realtime or full_screen.\")\n\n if platform.system() == \"Linux\" and (FLAGS.realtime or FLAGS.full_screen):\n sys.exit(\"realtime and full_screen only make sense on Windows/MacOS.\")\n\n if not FLAGS.render and FLAGS.render_sync:\n sys.exit(\"render_sync only makes sense with pygame rendering on.\")\n\n run_config = run_configs.get()\n\n interface = sc_pb.InterfaceOptions()\n interface.raw = FLAGS.render\n interface.raw_affects_selection = True\n interface.raw_crop_to_playable_area = True\n interface.score = True\n interface.show_cloaked = True\n interface.show_burrowed_shadows = True\n interface.show_placeholders = True\n if FLAGS.feature_screen_size and FLAGS.feature_minimap_size:\n interface.feature_layer.width = FLAGS.feature_camera_width\n FLAGS.feature_screen_size.assign_to(interface.feature_layer.resolution)\n FLAGS.feature_minimap_size.assign_to(\n interface.feature_layer.minimap_resolution)\n interface.feature_layer.crop_to_playable_area = True\n interface.feature_layer.allow_cheating_layers = True\n if FLAGS.render and FLAGS.rgb_screen_size and FLAGS.rgb_minimap_size:\n FLAGS.rgb_screen_size.assign_to(interface.render.resolution)\n FLAGS.rgb_minimap_size.assign_to(interface.render.minimap_resolution)\n\n max_episode_steps = FLAGS.max_episode_steps\n\n if FLAGS.map:\n create = sc_pb.RequestCreateGame(\n realtime=FLAGS.realtime,\n disable_fog=FLAGS.disable_fog)\n try:\n map_inst = maps.get(FLAGS.map)\n except maps.lib.NoMapError:\n if FLAGS.battle_net_map:\n create.battlenet_map_name = FLAGS.map\n else:\n raise\n else:\n if map_inst.game_steps_per_episode:\n max_episode_steps = map_inst.game_steps_per_episode\n if FLAGS.battle_net_map:\n create.battlenet_map_name = map_inst.battle_net\n else:\n create.local_map.map_path = map_inst.path\n create.local_map.map_data = map_inst.data(run_config)\n\n create.player_setup.add(type=sc_pb.Participant)\n create.player_setup.add(type=sc_pb.Computer,\n race=sc2_env.Race[FLAGS.bot_race],\n difficulty=sc2_env.Difficulty[FLAGS.difficulty],\n ai_build=sc2_env.BotBuild[FLAGS.bot_build])\n join = sc_pb.RequestJoinGame(\n options=interface, race=sc2_env.Race[FLAGS.user_race],\n player_name=FLAGS.user_name)\n version = None\n else:\n replay_data = run_config.replay_data(FLAGS.replay)\n start_replay = sc_pb.RequestStartReplay(\n replay_data=replay_data,\n options=interface,\n disable_fog=FLAGS.disable_fog,\n observed_player_id=FLAGS.observed_player)\n version = replay.get_replay_version(replay_data)\n run_config = run_configs.get(version=version) # Replace the run config.\n\n with run_config.start(\n full_screen=FLAGS.full_screen,\n window_size=FLAGS.window_size,\n want_rgb=interface.HasField(\"render\")) as controller:\n if FLAGS.map:\n controller.create_game(create)\n controller.join_game(join)\n else:\n info = controller.replay_info(replay_data)\n print(\" Replay info \".center(60, \"-\"))\n print(info)\n print(\"-\" * 60)\n map_path = FLAGS.map_path or info.local_map_path\n if map_path:\n start_replay.map_data = run_config.map_data(map_path,\n len(info.player_info))\n controller.start_replay(start_replay)\n\n if FLAGS.render:\n renderer = renderer_human.RendererHuman(\n fps=FLAGS.fps, step_mul=FLAGS.step_mul,\n render_sync=FLAGS.render_sync, video=FLAGS.video)\n renderer.run(\n run_config, controller, max_game_steps=FLAGS.max_game_steps,\n game_steps_per_episode=max_episode_steps,\n save_replay=FLAGS.save_replay)\n else: # Still step forward so the Mac/Windows renderer works.\n try:\n while True:\n frame_start_time = time.time()\n if not FLAGS.realtime:\n controller.step(FLAGS.step_mul)\n obs = controller.observe()\n\n if obs.player_result:\n break\n time.sleep(max(0, frame_start_time + 1 / FLAGS.fps - time.time()))\n except KeyboardInterrupt:\n pass\n print(\"Score: \", obs.observation.score.score)\n print(\"Result: \", obs.player_result)\n if FLAGS.map and FLAGS.save_replay:\n replay_save_loc = run_config.save_replay(\n controller.save_replay(), \"local\", FLAGS.map)\n print(\"Replay saved to:\", replay_save_loc)\n # Save scores so we know how the human player did.\n with open(replay_save_loc.replace(\"SC2Replay\", \"txt\"), \"w\") as f:\n f.write(\"{}\\n\".format(obs.observation.score.score))\n\n if FLAGS.profile:\n print(stopwatch.sw)\n\n\ndef entry_point(): # Needed so setup.py scripts work.\n app.run(main)\n\n\nif __name__ == \"__main__\":\n app.run(main)\n"
},
{
"path": "pysc2/bin/play_vs_agent.py",
"content": "#!/usr/bin/python\n# Copyright 2017 Google Inc. All Rights Reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS-IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Play as a human against an agent by setting up a LAN game.\n\nThis needs to be called twice, once for the human, and once for the agent.\n\nThe human plays on the host. There you run it as:\n$ python -m pysc2.bin.play_vs_agent --human --map ![\"DeepMind](\"http://img.youtube.com/vi/-fKUyT14G-8/0.jpg\"\n)
\n \n \n ![\"StarCraft](\"http://img.youtube.com/vi/6L448yg0Sm0/0.jpg\"\n)
\n \n \n ![\"Trained](\"http://img.youtube.com/vi/WEOzide5XFc/0.jpg\"\n)
\n \n