# Two tags from 2017, and a licence split across two files > s2client-proto holds the protocol definitions that let external software drive StarCraft II, plus a large archive of downloadable game builds, map packs and replay packs. The protocol is a protobuf file, the reference implementation is a separate repository, and the only two tags date from 2017. **Blizzard/s2client-proto** — StarCraft II Client - protocol definitions used to communicate with StarCraft II. - Repository: https://github.com/Blizzard/s2client-proto - Stars: 3,968 · Forks: 440 - Language: Python - License: MIT - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/blizzard-s2client-proto ## The only two tags are from 2017, while the download list runs to 2020-era builds The release history has two entries, one named after a 2017 game release and one named after the release before it, both from September and November 2017. Nothing has been tagged since. Yet the last commit on the default branch is dated 2026-07-16, so the repository has been worked on continuously and simply not versioned. That distinction matters more here than it would for an ordinary library, because of what this repository contains. The download section lists eighteen Linux client builds, with the version numbers running from 3.17 through 4.10, plus twelve map packs and two replay packs, all as individual URLs in the README. Those URLs are the actual distribution mechanism, and they are not generated from a tag. So the tags tell you almost nothing about what is current, and the newest entry in the download list is the better signal. Anyone tracking this project should treat the file list as the version history and the tags as an abandoned convention. ## Two licence files, and the repository ships a separate one for the protocol The tree contains a file whose name is a licence declaration, distinct in kind from the ordinary licence file the metadata points at. That is not redundant. This repository holds two different kinds of material under two different terms. The first is the protocol definition itself, the interface external software uses to control the game, and it is covered by the dedicated file. The second is everything else: the build scripts, the documentation, the stable identifier mapping, the sample code, and the download index. The project's own metadata reports the permissive open source licence for the repository as a whole, while the protocol file in the root suggests the protocol definitions carry terms of their own. Blizzard publishes protocol definitions for third-party tooling under a separate licence precisely so the tooling is open while the interface specification is governed separately. If you are writing a bot or an analysis tool you are fine with the permissive terms. If you are reimplementing the interface or shipping a compatible client, read the dedicated file, because that is the one that applies to the definitions you would be copying. ## The Python package compiles protobuf at install time, not at build time The packaging script is where the real design decision is, and it is unusual. Rather than shipping generated Python, the build step walks the protocol directory, finds every file ending in a particular extension, and invokes the protocol compiler on each one to produce Python, and then appends to the package's init file and delegates to the normal build. Two details are worth naming. First, the compiler is looked up on the path unless an environment variable points at a specific one, and if it is missing the script exits with a message asking whether the compiler is installed. If a call fails, it exits with a message that the version needs to be at least a particular number and points at the environment variable. Second, the generated code is written into the source directory rather than a build directory, which means running the build twice in a checkout leaves artefacts behind. The upshot for a user is that installing this package requires the protocol compiler to be present, which is a build-time dependency you do not get with a normal Python package. The alternative, committing generated code, would avoid that and would go stale whenever the definitions changed. ## The version of the package is derived from the game, not from the code The setup script does not contain a version number. It imports a module from its own package and calls a function on it that returns the game version. So the package's reported version is whatever the game's own version is, which means the two cannot drift apart. That is a deliberate and rather elegant choice for a repository whose entire purpose is to track an interface that changes with the game. It also means the package version is not a meaningful pin for your own dependency resolution in the usual sense. If two of your dependencies both want this package and they resolve to different versions, the difference is a game version, not an API change in the binding. And a new game release can therefore produce a new package version with no commit to this repository at all, since the version comes from a data file the game ships. That is consistent with the tag history being empty of recent entries. When you pin this package, you are pinning a game version, and the honest question to ask is which game build your bot was tested against. ## The stable identifier file is the bridge between the protocol and the game's internals There is a data file at the repository root that deserves more attention than it gets. The README explains that it defines the action mappings from ability identifiers in the protocol to the internals of the game, and also defines some general identifiers that combine multiple abilities with a similar semantic meaning, giving burrow, cancel and lift and land as the kinds of grouping involved. That is the whole problem this repository exists to solve. A bot does not need to know what a unit is doing internally; it needs to issue an action by a stable number. The game renumbers its internal identifiers between patches, and this mapping is the compatibility layer that absorbs that. It is described as updated occasionally with the game, and the README also explains that you can update it manually by downloading a newer copy and placing it in the root of the game directory. That last point is the important one operationally: the mapping is a data file that can be replaced without touching your code, which means a bot written against an old game patch can often be fixed by swapping one file. Anyone maintaining a bot should know that escape hatch exists. ## Downloading anything requires typing a password that is also your licence acceptance The downloads section has a licensing gate and it is worth reading carefully. To get the Linux packages, map packs or replay packs, you must agree to a separate AI and machine learning licence. The files are password protected, and the password is printed in the README. The README then states that by typing that password you agree to be bound by those terms. So the mechanism is a plaintext password that serves double duty as an assertion of consent, which is not a legal mechanism in any meaningful sense. It is, however, an honest and unglamorous one: the gate exists so that the terms are linked next to the download and not buried, and the password prevents a hotlink from working without someone having seen the page. What this means for you is that the licence terms for the game builds and the data packs are separate from the licence on this repository's code, and they are the ones you accept by downloading. Read them before you do, particularly if you intend to redistribute anything derived from the packs, since the README does not say what that would require. ## The reference implementation is a different repository, and the community list is all unofficial The contents section divides into official and community, and the division is doing more work than the headings suggest. Official means the protocol definition, with a link to the file and to generated documentation, the reference C++ library, which lives in a separate repository, and the downloads. The reference implementation being separate is the arrangement to understand. This repository defines the interface; the library that makes it convenient in a particular language is versioned on its own schedule. So when the interface changes, this repository changes and the library follows, and there is a window where one is ahead of the other. Below that, everything is marked unofficial, and the marking is repeated per item rather than once for the section, which is deliberate: the Python environment wrapper from a well-known research lab, the bot architecture framework, two community-run competitive ladders, a wiki, a chat server, and a social group. Not one of those is supported by the publisher, and the ladders in particular are where your bot would be measured by people with no obligation to you. ## Conclusion s2client-proto suits someone writing a scripted bot, a replay analysis tool, or a reinforcement learning environment for StarCraft II, and who is prepared to treat the game as a moving target. Four things to know before you build on it. Track the file lists rather than the tags, because the only two tags are from 2017 while the download list runs on and the repository is still being committed to. Read the dedicated protocol licence separately from the repository licence, since the two cover different material. Know that installing the Python binding requires the protocol compiler present at build time, because the bindings are generated during install. And keep a copy of the stable identifier file, since swapping that one file is often all it takes to bring a bot back to working after a game patch. ## FAQ ### What is Blizzard's s2client-proto repository? It holds the protocol definitions used to communicate with StarCraft II, published as a protobuf file, along with generated documentation. The interface it defines provides full external control of the game, and the README lists scripted bots, machine-learning bots, replay analysis and tool-assisted human play as the intended uses. The API is available in the retail Windows and Mac clients. ### Does s2client-proto include a reference implementation? Not in this repository. The README points to a separate repository for a reference C++ library designed for building scripted bots using the API. This repository holds the protocol definitions themselves, the documentation, the stable identifier mapping, a sample, and the download index for Linux builds and data packs. ### How do I download the Linux packages or map packs from s2client-proto? The README links eighteen Linux builds, twelve map packs and two replay packs. To access them you must agree to the AI and machine learning licence, and the archives are password protected with a password printed in the README, which the README states counts as agreeing to those terms. All extra game data must be extracted into the game installation directory. ### What is the stableid.json file in s2client-proto? It maps ability identifiers used in the protocol to the game's internal identifiers, and it also defines general identifiers that combine several abilities with a shared meaning. It is updated occasionally with the game, and you can also replace it manually by placing a newer copy in the root of your game directory, which fixes a bot against a new patch without changing code. ### Does installing the s2clientprotocol Python package need the protobuf compiler? Yes. The packaging script walks the protocol directory and invokes the protocol compiler on each definition to generate Python during the build, rather than shipping generated code. It looks for the compiler on the path unless an environment variable points at a specific binary, and exits with an explanatory message if it is missing or too old. ## Sources - [Blizzard/s2client-proto on GitHub](https://github.com/Blizzard/s2client-proto) - [Issues](https://github.com/Blizzard/s2client-proto/issues) - [License: MIT](https://github.com/Blizzard/s2client-proto/blob/master/LICENSE) - [README](https://github.com/Blizzard/s2client-proto/blob/master/README.md) - [Releases](https://github.com/Blizzard/s2client-proto/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/blizzard-s2client-proto