Changes between Version 14 and Version 15 of SC2ReplayFormat


Ignore:
Timestamp:
Aug 9, 2010, 5:30:36 PM (8 years ago)
Author:
mseifert
Comment:

Added information on VLF

Legend:

Unmodified
Added
Removed
Modified
  • SC2ReplayFormat

    v14 v15  
    66Refer to [http://code.google.com/p/starcraft2replay/] for a better documentation. This page is currently being updated.
    77
     8== Data types ==
     9=== General ===
    810The types used in this documentation are:
    911||'''Type'''||'''Description'''||
     
    1416||bytesX||A number of bytes whose functions and grouping are unknown, where X represents the number of bytes.||
    1517
    16 All types are Big-Endian.
    17 
     18All types are Big-Endian and offsets are relative to the described block, unless specified otherwise.
     19
     20=== Time offset ===
    1821There 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:
    1922{{{
    2023  t = b + (a >> 2) * 255
    2124}}}
     25
     26=== Variable Length Format ===
     27Additionally, 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.
     28Examples:
     29{{{
     30  significant bits
     31       |-----|
     32    0b10000000
     33      ^
     34Indicates succeeding byte
     35}}}
     36
     37{{{
     38 0x02       0x0C
     39 0b00000010 0b00001100
     40
     41Most significant bit is not set and sign is positive. Parsed values are 2 and 12.
     42}}}
     43
     44{{{
     45 0x83       0x0C
     46 0b10000011 0b00001100
     47
     48Most significant bit is set and sign is negative. Parsed value is -769 (-0b1100000001).
     49
     50Routine:
     51  ((0x83 & 0x7F) | 0x0C << 7) >> 1
     52= (    0x03      |   0x0600 ) >> 1
     53= 0x0603 >> 1 (Check sign bit before shifting)
     54=> -0x0301
     55}}}
     56Information about parsing these variable length integer values has been figured out by noko1111 ^[#vlfDocumentation 1]^, who referred to it as VLF (Variable Length Format). His documentation also includes further test cases.
    2257
    2358== Format versions ==
     
    78113The MPQ archive starts at an offset of 1024 bytes and contains 8 files.
    79114
     115{{{
     116#!div class="version1"
    80117==== replay.info ====
    81 This file contains information about the players and the game in general. All offsets are relative to the described block, unless specified otherwise.
     118This file contains information about the players and the game in general.
    82119
    83120===== Players =====
     
    102139||0x05+string+3||bytes11||Function unknown.||
    103140||0x05+string+14||string||Some kind of checksum or hash. Usually 76 bytes long (75 without the length indicator of the string).||
     141}}}
     142
     143{{{#!div class="version2"
     144==== replay.details ====
     145}}}
     146
     147{{{#!div class="version2"
     148==== replay.init.data ====
     149}}}
    104150
    105151==== replay.game.events ====
     
    275321
    276322=== References ===
    277 [=#starcraft2replay 1.] [http://code.google.com/p/starcraft2replay/]
     3231. [=#vlfDocumentation] [http://www.teamliquid.net/forum/viewmessage.php?topic_id=117260&currentpage=3#45 Documentation of the variable length format (VLF) by noko1111]
     3242. [=#starcraft2replay] [http://code.google.com/p/starcraft2replay/ Abandoned project of an SC2Replay parser in c++]