SC2replay Documentation

It is important to understand the interaction between the Starcraft II game engine and the replay file and how they come together in the built-in replay viewer. Without this understanding, many of the design decisions that were made with regard to the file format, replay viewer, and SC2Reader library may not be clear or seem logical. We'll address each of the components briefly and examine how they contribute to some limitations on the replay viewing engine before digging into the file format details.

The Game Engine

The game state at any specific point in time is 100% deterministic.

This is a simple and perhaps obvious statement but is incredibly important to understand so chew it over for a minute. Given the same starting context and the same sequence of timed player actions, the Starcraft II game engine will reproduce any game in exact detail.

Examples:

1. If you start the game as Terran in the top right on Shattered Temple (starting context) and perform the same SCV split at the same time the resulting resource amounts and unit positions will be identical each game.
2. When you order a group of 5 Marines to attack move to an enemy base from the top of your ramp the path the Marines will take to arrive at that destination will be exactly the same every time if their initial positions and destination points are the same.

Given the same set of player actions, the game engine will always produce exactly the same game state.

This consistency of action and reaction is certainly essential for making Starcraft playable and competitive but it is also the key to understanding why replays are recorded the way that they are. It also provides a key channel for insight into the limitations of their internal replay engine.

The Replay File

Now that we know that the game is really just a gigantic state machine that players drive via their specific actions we can more fully understand how replays are recorded.

A replay, at its core, stores the only two things the state machine (game engine) needs to run. The initial game context and the chronological list of events that drive the game. Nothing else is stored*. The replay file knows who was playing, who was observing, what their races and starting locations were and what map was played on. It also records each player input along with the exact time the action was executed. Player inputs include pings, chat messages, camera movements, selections, hot keys, unit commands, etc.

Now for long games with large teams and high APMs this can be a HUGE amount of information. To reduce the file size of the replays Blizzard took pains to store the information as concisely as possible in a variety of byte and bit encoded formats. We'll get into that in a bit, but lets pause and consider the implications these decisions place on the built-in replay viewer.

*Not exactly true, but true enough for the moment.

The Replay Viewer

Ever wonder why you couldn't skip forward in the replay engine? How about why you need to exit Battle.net in order to watch some old replay files but not others? Now these answers should be mostly self-evident.

You can't skip forward in replays because the information to do so just doesn't exist. In order to view the state at the 10 minute mark you need to run every stored event in the first 10 minutes of the game through the game engine. In view of this limitation, Blizzard has given an 8x speed option which feeds events through faster, but its just fundamentally not possible to skip steps because no intermediate information is stored.

You have to exit Battle.net in order to watch some old replay files because in order to be 100% deterministic the events stored in the replay must be run through the same exact game engine that created the replay file. Some versions of Starcraft introduce changes to the game engine (like nerfing Infestors and High Templar) and when you run the same events through a different game engine you'd create a different game. In order to swap in the old game engine Starcraft has to log you out of battle.net; probably related to some other technical limitations in the design of Battle.net.

TODO: there are many more implications here. Talk about summary and stats on replay files maybe?

Replay File Format

SC2Replay files as you know them are actually archives like a tar or a zip file. A replay "file" is actually an MPQ archive of 8 different files containing all the different information required to recreate the game. For a detailed look into this archive format see the wiki at devlog. The header of the MPQ file (aka the replay) also contains some basic game information. See .sc2replay for more information on that.

The eight files archived in each replay are as follows:

• replay.attributes.events - Contains all the player/game attribute information in a fixed width byte format. Attributes include player teams, colors, races, handicaps, game speed, etc.
• replay.details - Contains player information such as win/loss, race, team, bnet url components, player number, player name, map name, etc.
• replay.game.events - Contains all the player input events required to regenerate the game state in a variable width bit-encoded format. Includes, selections, hotkeys, commands, camera movements, player join/leave, etc.
• replay.initData - Contains game realm as well as a full (including observers) player list. The full format and purpose of this file isn't really known.
• replay.load.info - Contains a bunch of null bytes and a loading screen file path. Unexciting.
• replay.message.events - Contains all the player pings and chat messages in a variable length format. Also appears to contain some network packets of some sort.
• replay.smartcam.events - TODO
• replay.sync.events - Contains a series of fixed width events that appear to be some sort of checksum or pseudo random number, probably used to validate game state and prevent cheating/bootlegging etc.

When we speak about the format of these files it is important to note that every incremental release of Starcraft II gives Blizzard an opportunity to tweak the game engine and replay file formats. As such each file listed above actually has at least one, if not 3 or more different formats to be applied depending on the version number of the game engine that created the replay.

The documentation for each of these file formats can be found on the pages linked above but the written documentation is generally quite dated so make sure to use the code as your primary reference guide. To get started with the SC2Reader code base see the SC2Reader Documentation.