wiki:SC2ReplayFormat

Version 16 (modified by mseifert, 7 years ago) (diff)

Added information on the replay.details file

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.

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.

replay.init.data

replay.game.events

This file stores all actions the players have ordered.

An action looks like the following:

OffsetTypeDescription
0x00time informationGives information about the time offset of an action to the preceding action. Equivalent to the time information in the chat log.
time informationbyteUnknown.
time information + 1byteAction code.
time information + 2bytesXBytes storing information on the respective action. The size seems to depend on the action code.
Action codes

Action codes are unique identifiers that distinguish one action from another. They are 1 byte long.

Known action codes are:

Action codeIn-game action
0x00Unknown action. Randomly appears after other actions.
0x0BUsage of any kind of ability or assignment of orders. Includes constructing buildings, training units, moving, attacking, gathering resources, and so on.
0x0DGroup 0
0x1DGroup 1
0x2DGroup 2
0x3DGroup 3
0x4DGroup 4
0x5DGroup 5
0x6DGroup 6
0x7DGroup 7
0x8DGroup 8
0x9DGroup 9
0x81Movement of the screen.
0x89Unknown action.
0xACSelection or deselection.
Group actions
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

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++