wiki:SC2ReplayFormat

Version 12 (modified by mseifert, 9 years ago) (diff)

Added information on incorrectness

Sc2Replay

Table of Contents

  1. File Structure
    1. replay.info
      1. Players
      2. Game settings
    2. replay.game.events
      1. Action codes
        1. Group actions
        2. Select action
      2. Ability codes

WARP currently supports the extraction of the following information from .SC2Replay files:

  • Player name
  • Player race
  • Player color
  • Game duration
  • Game version
  • Chat log
  • Map preview

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 site will be updated soon.

File Structure

SC2Replay files contain an mpq archive with 8 files. The archive starts at an offset of 1024 bytes. 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.

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

replay.info

This file contains information about the players and the game in general. All offsets are relative to the described block, unless specified otherwise.

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