Unit ability event

Unit Ability Event - Code 0x[0-9]B

This event has Type = 0x01 and Code = 0x[0-9]B.

Event structure

The main structure is: flags (1 byte) + ability type (1byte) + ability code (2-3bytes) + <ability specific data>

Flags

This byte has the following structure: ??CD 1AAB.

AA Indicate the ability is a toggle, 01 is off, 11 is on.

BCD are set when the only extra data is a 4-byte identifier. B indicates the extra bytes, C flags an object identifier, while D flags a "creation auto-number" denoting the unique build-order of the unit. This number starts at 0 and gets upped every time a unit is added to a queue. The first one is seen when unloading units from transports, the latter is used when cancelling specific units from a queue since they do not have an object id yet.

Ability type

This byte has the following structure: ABC? ??D?.

A (& 0x80) indicates the ability has a target unit, B (& 0x40) indicates has a target location and C (& 0x20) flags the ability as a "command card" ability. A and B are often right-clicks and it looks like they only use 2 bytes for the ability code, while the command card abilities use 3 bytes. D (& 0x2) indicates the command is queued with shift.

Ability codes

Ability codes refer to a big table of codes ranging from training units to casting spells or basic movement. They are 2 bytes signalling the type of ability (for example: built at a factory) while the last byte, if the ability is a command card ability, signals the final piece of information (a Siege tank). Hidden in the last byte is information about the data provided in the rest of the event; the 3rd and 4th bit signal either no (0x0) extra info, a target location (0x1) or a target unit (0x2), while 0x3 is used for unloading specific unit (location+unit maybe?). The 1st and 2nd bit are not part of the ability code, but are the start for the rest of the data.

Extra bit and pieces

This might be bit shifted all the way for command-card abilities, not yet confirmed. Check out our bit shift documentation to learn how to read them correctly

Locations

Coordinates are packed in a 40 bit format.

Target units

Just read a plain 4-byte integer.

Build number

Cancels (flagged in the first byte) employ a different code since the units are not on the map yet and have no object id. This number seems to be a auto-increment 4-byte integer starting from 0. The number signals which unit in the build-queue was cancelled.

Unknowns

Abilities are still a big work in progress and they are by far the largest part of data in replay-files, so this will be continued.

Build >= 16561

sc2reader employs the following logic in parsing abilities in newer version of Starcrft II:

first,atype = (bytes.getBigInt(1),bytes.getBigInt(1))

#I'm not sure why we chop the last byte into bits here, its what phpsc2replay project does
event.ability = bytes.getBigInt(1) << 16 | bytes.getBigInt(1) << 8 | (bytes.getBigInt(1) & 0x3F)

if atype == 0x20 or atype == 0x22:
    #Command Card Ability like Blink,Build,Attack,Move,etc
    if event.ability & 0xFF > 0x07:
        if first == 0x29 or first == 0x19:
            bytes.skip(4)
        else:
            bytes.skip(9)
            if event.ability & 0x20 != 0:
                bytes.skip(9)

elif atype == 0x48 or atype == 0x4A:
    #identifies right click (I think) location
    bytes.skip(7)

elif atype == 0x88 or atype == 0x8A:
    #identifies right click (I think) unit
    bytes.skip(15)

Build < 16561

Not much is known about the ability event from the 1.0 release versions. The following approach has been used in the phpsc2replay project:

bytes.skip(4)
event.ability = bytes.getBigInt(3)
reqTarget = bytes.getBigInt(1)

#In certain cases we need an extra byte
if reqTarget == 0x30 or reqTarget == 0x05:
    bytes.skip(25)
else:
    bytes.skip(24)

I've not investigated this myself yet.