wiki:SC2ReplayFormat

Sc2Replay

The following is a documentation of SC2Replay files.

WARNING: The file structure of SC2Replay files as state below is neither complete, nor completely correct! Refer to http://code.google.com/p/starcraft2replay/ for a better documentation. This page is currently being updated.

Data types

General

The types used in this documentation are:

TypeDescription
int8A single byte.
int16Two bytes.
int32Four bytes.
stringOne byte that represents the length of the following string. The string has as many characters, as the byte's value
bytesXA number of bytes whose functions and grouping are unknown, where X represents the number of bytes.

All types are Big-Endian and offsets are relative to the described block, unless specified otherwise.

Time offset

There is another type that will be called time offset. It is of variable length and describes the amount of time that has passed since the last action has occured. Time seems to be measured in something I will call time frames or just frames. 25 frames give a real second. Say you read a byte. If this byte has the flag 0b00000001 set, the time offset is followed by another byte. If the flag 0b00000010 set, it followed by another two bytes (not tested yet). It is likely that the time offset consists of two byte, if any of the 8 bits are set, though. Let a be the first byte you read that contains the flags and b be the second byte, then the value of the time offset t is calculated:

  t = b + (a >> 2) * 255

Variable Length Format

Additionally, SC2Replay files have a quirk concerning the way integers are stored. An integer consists of a variable number of bytes in Big Endian order. When parsing an integer, the first i.e. most significant bit of a byte indicates that the succeeding byte is counted towards the integer's value. After parsing all bytes of a number, the least significant bit of the result indicates the sign. Extract this bit and shift the number's value to the right by one. If the bit is set, change the sign to negative, otherwise leave it positive. Examples:

  significant bits
       |-----|
    0b10000000
      ^
Indicates succeeding byte
 0x02       0x0C
 0b00000010 0b00001100

Most significant bit is not set and sign is positive. Parsed values are 2 and 12.
 0x83       0x0C
 0b10000011 0b00001100

Most significant bit is set and sign is negative. Parsed value is -769 (-0b1100000001).

Routine:
  ((0x83 & 0x7F) | 0x0C << 7) >> 1
= (    0x03      |   0x0600 ) >> 1
= 0x0603 >> 1 (Check sign bit before shifting)
=> -0x0301

Information about parsing these variable length integer values has been figured out by noko1111 1, who referred to it as VLF (Variable Length Format). His documentation also includes further test cases.

Enum values

This section describes the encodings of game settings that can change within a predefined range of values.

Game Speed Value
Slower 0
Slow 1
Normal 2
Fast 3
Faster 4
Difficulty Value
Very Easy 0
Easy 1
Medium 2
Hard 3
Very Hard 4
Insane 5
Color index Value
Red 1
Blue 2
Teal 3
Purple 4
Yellow 5
Orange 6
Green 7
Light pink 8
Violet 9
Light grey 10
Dark green 11
Brown 12
Light green 13
Dark grey 14
Pink 15
Event type Value
Initialization 0x00
Action 0x01
Unknown 0x02
Replay 0x03
Inaction 0x04
System 0x05

Format versions

Currently, 2 versions of the SC2Replay format are documented. To distinguish between them in this article, a color encoding is used. No coloring means that the description of a section is universally valid for all versions of the format.

Information about Replay version 1 is valid for the following game versions of Starcraft 2:

  • 0.2.0.13891
  • 0.3.0.14093
  • 0.4.0.14133
  • 0.5.0.14219
  • 0.6.0.14259
  • 0.7.0.14356
  • 0.8.0.14593
  • 0.9.0.14621
  • 0.10.0.14803

Information about Replay version 2 is valid for the following game versions of Starcraft 2:

  • 0.11.0.15133
  • 0.12.0.15133
  • 0.13.0.15250
  • 0.14.0.15343
  • 0.14.0.15392
  • 0.14.1.15392
  • 0.15.0.15449
  • 0.16.0.15580
  • 0.17.0.15623

File Structure

The SC2Replay file format is a binary file format. It basically consists of a header and an MPQ archive.

SC2Replay header

Offset Type Description
0 bytes39 Unknown
39 int8 Major version, minor version, revision number and build number of the replay (see ticket #3)
40 int8
41 int8
42 int32
46 bytes6 Unknown
52 int16 Duration of the recorded game in half seconds (see ticket #4)
54 bytes970 Unknown

MPQ Archive

The MPQ archive starts at an offset of 1024 bytes and contains 8 files.

replay.info

This file contains information about the players and the game in general.

Players

The first part of this file simply stores the player names.

OffsetTypeDescription
0x00int8 Number of player names that are contained in this block. This value usually is 0x10 i.e. 16.

Now, for each player, the entry looks the following:

OffsetTypeDescription
0x00stringPlayer name.
stringbytes5Function unknown. Always seems to be 0x00.
Game settings

The player block is followed by:

OffsetTypeDescription
0x00bytes5Unknown.
0x05stringProbably an indicator for a compression algorithm used somewhere. Always seems to be "Dflt".
0x05+stringbyteThis byte contains some flags. If the alliances in the game are locked, the rightmost bit is set.
0x05+string+1byteFunction unknown. Always seems to be 0x00.
0x05+string+2byteByte indicating the game speed. 0x00 = Slowest, 0x01 = Slow, 0x02 = Normal, 0x03 = Fast, 0x04 = Fastest
0x05+string+3bytes11Function unknown.
0x05+string+14stringSome kind of checksum or hash. Usually 76 bytes long (75 without the length indicator of the string).

replay.details

noko1111 states the following in his documentation of the replay.details file:

It consists of one data type marker followed by data itself. Data type marker is a single byte and can have following values:

02: Binary data. 02 is followed by size of binary data in VLF after that comes data itself; in most cases it's text in utf8. 02 12 41 55 54 4F 4D 41 54 49 43 is a string AUTOMATIC.

04: An array. 04 is alway followed by 01 00, after that there is number of elements in array in VLF, and elements follow. Each element is a data type marker followed by data, all in same format.

05: An array. Followed by number in VLF which indicates how many pairs will follow -- a pair consists of array element index in VLF and element itself (data type marker followed by data).

06: A number. Its value follows in one byte.

07: A number. Its value follows in four bytes.

09: A number. Its value follows in VLF.

Here are examples:

  binary data (right align)    equivalent in JSON
  =========================    ==================
           02 04 68 69 => "hi"
  05 02 00 02 04 68 69 => ["hi"]
  05 04 00 02 04 68 69 02
           02 04 68 69 => ["hi","hi"]
  05 06 00 09 02 02 09 04
              08 09 06 => [1,2,null,3] [''sic''. Correct result: "[1,2,null,null,3]"]
  05 04 00 05 02 09 02 02
           05 02 09 04 => [[1],[2]]
  05 04 00 06 01 02 07 02
              00 00 00 => [1,2]

In terms of memory efficiency, it might considered to use a dictionary/map for the 0x05 array type.

The following is a description of the respective data elements of replay.details. Indices separated with a comma represent nested arrays (e.g. 0.2 means that the element on position 0 contains another array, whose item at index 2 is described).

IndexTypeDescription
00x05Base array
0.00x04Array of player structs
0.0.x0x05Player struct
0.0.x.00x02Player name
0.0.x.10x05Probably some further details
0.0.x.1.00x09Unknown
0.0.x.1.10x07Unknown
0.0.x.1.20x09Unknown
0.0.x.1.30x02RealID
0.0.x.20x02Localized race name
0.0.x.30x05Array of player color values
0.0.x.3.00x09alpha
0.0.x.3.10x09red
0.0.x.3.20x09green
0.0.x.3.30x09blue
0.0.x.40x09Unknown
0.0.x.50x09Unknown
0.0.x.60x09Handicap
0.0.x.70x09Unknown
0.0.x.80x09Team
0.10x02Localized map name
0.20x02Unknown
0.30x05Array containing map preview file names
0.3.00x02Map preview file name
0.40x06Unknown
0.50x09Save time of the replay
0.60x09Unknown
0.70x02Unknown
0.80x02Unknown
0.90x02Unknown
0.100x04Likely something about the map file
0.10.00x02Unknown
0.10.10x02Unknown
0.110x06Unknown
0.120x09Unknown
0.130x09Unknown

replay.init.data

replay.game.events

This file stores all events that have occurred during the match.

An event has the following structure:

OffsetTypeDescription
0x00Time offsetGives information about the time offset of an action to the preceding action. Equivalent to the time information in the chat log.
Time offsetbyteEvent type, flag, and player id. EventType = byte >> 5; flag = byte & 0x0F; playerID = byte & 0x0E;
Time offset + 1byteEvent code.
Time offset + 2bytesXBytes storing information on the respective action. The size depends on the event type and the event code.
Event codes

Event codes are unique identifiers that distinguish one event from another. They are 1 byte long.

Initialization

Events belonging to the initialization type:

Event codeCause
0x05Game starts
0x0BPlayer enters game
0x2BPlayer enters game
0x0CPlayer enters game (for build >= 17326)
0x2CPlayer enters game
Action

Events belonging to the action type:

Event codeCause
0x09Player leaves game
0x09Player leaves game
0x0BPlayer uses any ability. Orders count as abilities, too.
0x1BPlayer uses any ability. Orders count as abilities, too.
0x2BPlayer uses any ability. Orders count as abilities, too.
0x3BPlayer uses any ability. Orders count as abilities, too.
0x4BPlayer uses any ability. Orders count as abilities, too.
0x5BPlayer uses any ability. Orders count as abilities, too.
0x6BPlayer uses any ability. Orders count as abilities, too.
0x7BPlayer uses any ability. Orders count as abilities, too.
0x8BPlayer uses any ability. Orders count as abilities, too.
0x9BPlayer uses any ability. Orders count as abilities, too.
0x0CPlayer changes selection
0x1CPlayer changes selection
0x2CPlayer changes selection
0x3CPlayer changes selection
0x4CPlayer changes selection
0x5CPlayer changes selection
0x6CPlayer changes selection
0x7CPlayer changes selection
0x8CPlayer changes selection
0x9CPlayer changes selection
0xACPlayer changes selection
0x0DGroup 0
0x1DGroup 1
0x2DGroup 2
0x3DGroup 3
0x4DGroup 4
0x5DGroup 5
0x6DGroup 6
0x7DGroup 7
0x8DGroup 8
0x9DGroup 9
0x1FPlayer sends resources
0x2FPlayer sends resources
0x3FPlayer sends resources
0x4FPlayer sends resources
0x5FPlayer sends resources
0x6FPlayer sends resources
0x7FPlayer sends resources
0x8FPlayer sends resources
Unknown

Events belonging to the action type:

Event codeCause
0x06Unknown
0x07Unknown
0x0EUnknown
Replay
Event codeCause
0x01Screen movement
0x11Screen movement
0x21Screen movement
0x31Screen movement
0x41Screen movement
0x51Screen movement
0x61Screen movement
0x71Screen movement
0x81Screen movement
0x91Screen movement
0xA1Screen movement
0xB1Screen movement
0xC1Screen movement
0xD1Screen movement
0xE1Screen movement
0xF1Screen movement
0x08Unknown
0x18Unknown
0x87Unknown
Ability actions
OffsetTypeDescription
0x00byteByte a. Flag byte.
0x01byteByte b. Flag byte.
0x02byteByte c. First byte of ability code.
0x03byteByte d. Second byte of ability code.
0x04byteByte e. Third byte of ability code.

The ability code can be assembled the following way:

int abilityCode = c << 16 | d << 8 | (e & 0x7F);

Meaning of flags in byte a:

BitPurpose
8Unknown
7Unknown
6Unknown
5Unknown
4Unknown
3The ability has no target (Assumption)
2Unknown
1Unknown

Meaning of flags in byte b:

BitPurpose
8Unknown
7Unknown
6Unknown
5Unknown
4Unknown
3Unknown
2Unknown. This bit is always set along with others.
1Unknown

If bit 3 of byte a is set (a & 0x04), we can skip 4 additional bytes. I suppose this is the case, if an ability without any target is used, like the stop command. Else, if byte b has the bit 6 set (b & 0x20), the target of the ability can either be a unit or a pair of coordinates. If the second bit of e is set (e & 0x40)), the target is a unit and we can skip 2 bytes (purpose unknown) and read a 4 byte integer to get the executing unit's id. To get the target unit's id, we read another 2 bytes (Note: further processing needed) and skip another 10 bytes (or 11 bytes if build >= 19595) for the event to be completed. If the second bit of e is not set, we read another 2 bytes (called e2, e3) and compute the id of the unit executing the ability with the following code:

(e & 0x80) << 16 | e2 << 15 | e3 << 9

Additionally, we skip another 4 bytes and are done.

Group actions

<Clean up>

OffsetTypeDescription
0x00byteIf the group is assigned, this byte's value is 0x00. If the group is selected, this byte's value is 0x02.
0x01byteFunction unknown. Always seems to be 0x00.
Select action

<Clean up>

This action is not reliably documented. The length of the action varies.

OffsetTypeDescription
0x00byteThe currently selected subgroup with 0x00 being the first.
0x01byteNot fully documented! Selection index of the unit that is affected by this action. A value of 0x00 means that the newly selected unit is appended to the current selection. If the player's old selection will be discarded (read further), this should be 0x01.
0x02byteByte containing flags.
0x03byteByte containing flags. If 0b00000001 is set, the player's current selection will be discarded and the units described in this action will be the only units remaining in the player's new selection. If not set, the units of this action will be added to the player's selection.
0x04byteIf this byte and the previous byte are 0x00, the action ends here. This only occurs, if units are deselected. Deselection in this case means that only some of the units in the player's current selection are deselected. In other words, if A is the player's current selection and B is the player's new selection, B is a subset of A. If this byte is not 0x00, however, it has something to do with the unit IDs.
0x05byteFunction unknown.
0x06byteFunction unknown. Probably an indicator for the selection type that occurred (left-click, shift-click, rectangle or ctrl-click).
0x07byteNumber of units that will be added to the player's current selection.
0x08byteFunction unknown.

This "header" which provides general information for the selection is followed by the block for the newly selected units. Each unit is described as follows:

OffsetTypeDescription
0x00byteUnit ID.
0x01byteFunction unknown.
0x02byteFunction unknown.
0x03byteFunction unknown. Only present, if the unit is not the last unit of the select action. The exception is that it is present at the last unit entry, if the old selection is dicarded.
Ability codes

To distinguish abilities or orders, a 3 byte identifier for each order is used. These 3 bytes will be called the "ability code".

Known ability codes are:

Ability codeAbility
0x020400Stop
0x020501Hold Fire
0x020600Move
0x020601Patrol
0x020602Hold position
0x020900Attack
0x030A00Point Defense Drone
0x040700Seeker Missile
0x050500Set rally point
0x050D00Stimpack (Marauder)
0x050F00250mm Strike Cannon
0x060400Gather
0x060401Return cargo
0x060800Cancel
0x060D00Build Command Center
0x060D01Build Supply Depot
0x060D02Build Refinery
0x060D03Build Barracks
0x060D04Build Engineering Bay
0x060D05Build Missile Turret
0x060D06Build Bunker
0x060D08Build Sensor Tower
0x060D09Build Ghost Academy
0x060D0ABuild Factory
0x060D0BBuild Starport
0x060D0DBuild Armory
0x060D0FBuild Fusion Core
0x060F00Stimpack (Marine)
0x070000Cloack (Ghost)
0x070001Decloack (Ghost)
0x070100Sniper Round
0x070200Heal (Medivac)
0x070300Siege Mode (Siege Tank)
0x070400Tank Mode (Siege Tank)
0x070500Cloack (Banshee)
0x070501Decloack (Banshee)
0x070600Load (Medivac)
0x070602Unload all (Medivac)
0x070800Yamato Cannon
0x070900Assault Mode (Viking)
0x070A00Fighter Mode (Viking)
0x070C01Unload all (Command Center)
0x070C04Load (Command Center)
0x070D00Lift off (Command Center)
0x070E00Land (Command Center)
0x070F00Build Tech Lab (Barracks)
0x070F01Build Reactor (Barracks)
0x080100Build Tech Lab (Factory)
0x080300Build Tech Lab (Starport)
0x080700Train SCV
0x080900Lower (Supply Depot)
0x080A00Raise (Supply Depot)
0x080B00Train Marine
0x080B01Train Reaper
0x080B02Train Ghost
0x080B03Train Marauder
0x080C01Train Siege Tank
0x080C04Train Thor
0x080C05Train Hellion
0x080D00Train Medivac
0x080D01Train Banshee
0x080D02Train Raven
0x080D03Train Battlecruiser
0x080D04Train Viking
0x080E00Upgrade Hi-Sec Auto Tracking
0x080E01Upgrade Building Armor
0x080E02Upgrade Infantry Weapons 1
0x080E03Upgrade Infantry Weapons 2
0x080E04Upgrade Infantry Weapons 3
0x080E06Upgrade Infantry Armor 1
0x080E07Upgrade Infantry Armor 2
0x080E08Upgrade Infantry Armor 3
0x080E05Upgrade Neosteel Frame
0x080F03Research Nitro Packs
0x090000Arm Silo with Nuke
0x090100Research Stimpack
0x090101Research Combat Shield
0x090200Research Siege Tech
0x090201Research Infernal Pre-Igniter
0x090300Research Cloacking Field
0x090302Research Caduceus Reactor
0x090303Research Corvid Reactor
0x090306Research Seeker Missiles
0x090307Research Durable Materials
0x090400Research Personal Cloacking
0x090401Research Moebius Reactor
0x090502Upgrade Vehicle Plating 1
0x090503Upgrade Vehicle Plating 2
0x090504Upgrade Vehicle Plating 3
0x090505Upgrade Vehicle Weapons 1
0x090506Upgrade Vehicle Weapons 2
0x090507Upgrade Vehicle Weapons 3
0x09050BUpgrade Ship Weapons 1
0x09050CUpgrade Ship Weapons 2
0x09050DUpgrade Ship Weapons 3
0x090508Upgrade Ship Plating 1
0x090509Upgrade Ship Plating 2
0x09050AUpgrade Ship Plating 3
0x0C0700Upgrade to Planetary Fortress
0x0D0600Research Weapon Refit
0x0D0601Research Behemoth Reactor
0x0D0900Tac Nuclear Strike
0x0D0C00EMP Round
0x0F0400Auto-Turret

Simply right clicking on an object in order to attack, gather resources, or move, depending on what is the default action, occupies a special ability code:

Ability codeAbility
0xFFFF0FRight click action

References

  1. Documentation of the variable length format (VLF) and the replay.details file by noko1111
  2. Abandoned project of an SC2Replay parser in c++
Last modified 7 years ago Last modified on Nov 5, 2011, 3:26:59 PM