# s2protocol: decoding StarCraft II replay files into Python structures

> s2protocol is Blizzard's reference Python library and standalone tool for decoding StarCraft II replay files into Python data structures. It exposes the replay header, game details, init data, game events, message events and tracker events, and it is deliberately a first stage for a data mining pipeline rather than an analysis tool.

**Blizzard/s2protocol** — Python library to decode StarCraft II replay protocols

- Repository: https://github.com/Blizzard/s2protocol
- Stars: 640 · Forks: 116
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/blizzard-s2protocol

## What the library decodes, and what it deliberately does not

s2protocol is described as a reference Python library and standalone tool to decode StarCraft II replay files into Python data structures. The list of what it decodes is short and specific: the replay header, the game details, the replay init data, game events, message events and tracker events. The scope limit is stated just as plainly. The README says s2protocol does not expose game balance information and does not provide any kind of high level analysis of replays, and that it is meant to be just the first tool in the chain for a data mining application. That framing matters for anyone picking a library, because a parser that gives you structures and a library that gives you answers are different products, and this one is deliberately the former. The primary language is Python, the licence is MIT, and the copyright is held by Blizzard Entertainment.

## Two ways to use it: as a library and as a tool

The README describes the dual usage explicitly. s2protocol can be used as a base-build-specific library to decode binary blobs, or it can be run as a standalone tool to pretty print information from supported replay files. The distinction matters because the version handling differs. The library side is tied to a specific build of the game, which is what a data mining pipeline wants when it needs to decode a specific protocol version correctly, and the setup.py reflects that split by packaging the s2protocol and s2protocol.versions modules and by deriving the version string from the game build rather than a hand written constant.

```python
    entry_points={
        'console_scripts': [
            's2protocol = s2protocol.s2protocol:main',
            's2_cli.py = s2protocol.s2_cli:main',
        ]
    },
```

So the package installs two commands, s2protocol and s2_cli.py, both pointing at entry point functions in the library, and the tool side depends on mpyq to read the Mopaq archive format that the replay file itself is packaged in, which the README acknowledges in its acknowledgements section.

## Version coverage, and the one tag in the repository

The supported versions section is a promise with a caveat. s2protocol supports all StarCraft II replay files that were written with retail versions of the game, and the current plan is to support all future publicly released versions, including public betas. The plan is the operative word, since the repository's own release history is thin. There is exactly one release tag, legacy, dated 2017-09-07, described as a tag for the legacy version of the library, and the README notes that tracker events are new in version 2.0.8 and do not exist in replays recorded with older versions of the game. The repository is not archived, and the last push was on 2026-10-08, so the code is being worked on even though the release tags do not reflect that. The build is a setup.py driven package with a requirements.txt pinning mpyq at 0.2.5 or newer, and the classifiers in setup.py still list Python 2.6 and 2.7, which tells you how old the packaging metadata is.

## Tracker events, and the unit tag arithmetic you need

The tracker events section is the densest part of the README and the part a data mining pipeline will spend the most time with. The first note is that tracker events did not exist before version 2.0.8. The second is a practical instruction: convert a unit tag index and recycle pairs into unit tags, as seen in game events, with the call protocol.unit_tag(index, recycle). The rest of the section is a set of semantics for the event types, and the README gives a worked snippet for interpreting the unit positions event.

```python
    unitIndex = event['m_firstUnitIndex']
    for i in range(0, len(event['m_items']), 3):
        unitIndex += event['m_items'][i + 0]
        x = event['m_items'][i + 1] * 4
        y = event['m_items'][i + 2] * 4
        # unit identified by unitIndex at the current event['_gameloop'] time is at approximate position (x, y)
```

The accumulator pattern matters, because the items array is a delta encoding rather than a list of absolute positions, and the coordinates are stored in units that need multiplying by four. Alongside that, the README documents the lifecycle events: unit init events appear for units under construction and are followed by a unit done event with the same unit tag when complete, unit born events appear for units created fully constructed, and a unit died event may arrive after either an init or a born event for the corresponding tag.

## The data quality caveats you have to design around

Three limitations in the tracker notes are worth designing around rather than discovering later. The first is coverage of the position events: only units that have inflicted or taken damage are mentioned in unit position events, and they occur periodically with a limit of 256 units mentioned per event, so a replay's position data is a sampled view of the fight, not a complete one. The second is a known issue the README states directly, that revived units are not tracked and placeholder units track death but not birth, which means a unit count derived from the tracker will not match a naive expectation of the game's unit lifecycle. The third is a units question inside the player stats event, where m_scoreValueFoodUsed and m_scoreValueFoodMade are in fixed point and need dividing by 4096 for integer values, while all other values in that event are already integers. A pipeline that treats every numeric field the same way will silently produce wrong food statistics.

## Ports to other languages, and the MPQ layer underneath

The README lists unofficial ports, and the most useful thing about them is what they reveal about the dependency structure. A Go implementation exists as a standalone project for both the MPQ parser and the s2protocol implementation, with the Go MPQ parser at icza/mpq and the Go s2protocol at icza/s2prot, and the Go port also provides some higher level API. A Java implementation exists inside the open source Scelight project, which the README describes as much more than just a replay parser because it also gives a high level API, with the Java MPQ parser and the Java s2protocol both inside that project. The split is consistent across both ports, and it maps onto the Python package structure, since the standalone tool uses mpyq to read mopaq files, as the acknowledgements section states. The practical takeaway is that the replay container format and the protocol decoding are separable, so a port can be adopted for one layer while the other is reused, and the two Java links show where the higher level analysis layer that Python does not provide lives.

## Conclusion

Adopt s2protocol if you are building a StarCraft II replay analysis or data mining pipeline and want the protocol decoding handled by the publisher's own reference implementation rather than a third party reverse engineering effort. Do not adopt it expecting analysis, because the README states plainly that it does not expose game balance information or provide high level analysis of replays, and do not expect it to cover replays from before tracker events existed. Before you build on it, confirm your replay files come from a retail version of the game, read the tracker event notes on unit tags and recycled unit pairs, and treat the known issue with revived units as a data quality caveat in your own pipeline.

## FAQ

### What is s2protocol?

It is a reference Python library and standalone tool to decode StarCraft II replay files into Python data structures. The primary language is Python, the licence is MIT, and the copyright is held by Blizzard Entertainment.

### Which StarCraft II replay structures does s2protocol decode?

The README lists the replay header, game details, replay init data, game events, message events and tracker events. It says s2protocol supports all StarCraft II replay files written with retail versions of the game, with the plan to support future publicly released versions including public betas.

### Does s2protocol provide high level analysis of replays?

No. The README states that s2protocol does not expose game balance information or provide any kind of high level analysis of replays, and that it is meant to be just the first tool in the chain for a data mining application.

### How do I convert tracker event unit indices into unit tags?

The README says to convert unit tag index and recycle pairs into unit tags, as seen in game events, with protocol.unit_tag(index, recycle). It also notes that tracker events are new in version 2.0.8 and do not exist in replays recorded with older versions of the game.

### What are the known data issues in s2protocol tracker events?

The README notes that only units that have inflicted or taken damage are mentioned in unit position events, that they occur periodically with a limit of 256 units per event, that there is a known issue where revived units are not tracked and placeholder units track death but not birth, and that the food used and food made values in the player stats event are fixed point and need dividing by 4096.

## Sources

- [Blizzard/s2protocol on GitHub](https://github.com/Blizzard/s2protocol)
- [Issues](https://github.com/Blizzard/s2protocol/issues)
- [License: MIT](https://github.com/Blizzard/s2protocol/blob/master/LICENSE)
- [README](https://github.com/Blizzard/s2protocol/blob/master/README.md)
- [Releases](https://github.com/Blizzard/s2protocol/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/blizzard-s2protocol