Datastructure

Data structures in sc2reader (draft) Basing this half on sc2reader, half on obslib; just to get a clear and concise external interface

Reading a replay

The main function to read a replay has the following signature:

Replay read (string location, read_details=True, read_messages=True, read_events=True, processors=DEFAULT_PROCESSORS)

In the default run, the entire replay file is read and processed with a couple of default processors.

• basic is the header which contains the StarCraft2 version which created the replay and the length of the replay. This data is always read.
• details are the player and game details; it entails the players, matchup, teams, map and play date.
• messages are all in-game chat elements.
• events are all game events, this is the actual data needed for replaying the game.

If any of these keyword arguments gets switched of, the corresponding attributes on the objects will not be available.

processors is a list of post-processing objects which puzzle together more aspects of the game by analysing the game events. A good example is the calculation of APM, which is not recorded in the game events, but is calculated from them.

TODO Which default processors?

Basic structures

These are the objects which the default read uses.

class Replay

Main class representing a replay file. Replays can be partially loaded, in which case not all attributes are available.

Attributes

Base: always available

Version info

• tuple version Tuple with version numbers (major, minor, revision, build number).
• string release String created from version (major.minor.revision.build). convenience
• integer build Build number which created the replay file. convenience

Duration/Length

• integer frames Length of replay in frames (1/16th of a game second).
• integer seconds Length of replay in game seconds. convenience
• tuple length Length of replay in (minutes, seconds) tuple. convenience

Details attributes

• string map Name of the map played on. This will get normalised to the English name of the map (if known).
• datetime played datetime instance of time the game started (localised, containing timezone info).
• string format (1v1,2v2,3v3,4v4,ffa) Format of the game.
• string type (public,private,ladder,singleplayer) Type of the game; public and private are custom maps, ladder is also known as AMM (automatic match maker).
• string speed (slower,slow,normal,fast,faster) Speed of the game.
• string realm (NA,EU,KR,SEA,PTR) Realm/gateway on which the game was played.

Matchup attributes

• list teams List containing the teams playing in this game; teams are again lists of Player instances. Team lists are ordered according to the game (index 0 is team 1, etc.).
• list clients List containing all clients in this game (Client instances), contains players, observers and referees.
• list players List containing the players in this game (Player instances). convenience
• list observers List containing the observers in this game (Observer instances). convenience
• list referees (??) List containing the referees in this game (Referee instances). convenience

Matchup properties convenience

• string race_matchup String containing the first letters of the races joined with 'v', for example: ZvP or ZTvPp. Lowercase indicates random was chosen as race.
• string team_matchup String containing the names of the players in teams, for example: ShadesOfGraylin vs. fizzgig or Player A, Player B vs. Player C, Player D.
• string game_filename Suggested filename for this replay; format is Y.M.D.hhmm.<team_matchup>.<map>.sc2replay. Team matchup is a compressed version (A+B+C.vs.D+E+F).

Message attributes

• list messages List containing all in-game messages (Message instances).

Event attributes

• list events List containing all game events (Event instances).

Functions

...

class Client

Base class for players, observers and referees.

Attributes

• string name Name used by the client in the replay.
• Replay replay Replay this client is part of. convenience

Functions

...

class Observer

extends Client

class Referee

extends Client

class Player

extends Client

Attributes

• string race (Terran,Protoss,Zerg) Actual race played in game.
• boolean is_random Indicates this player chose random race in lobby.
• integer team Team number (1-based).

Battle.net information

• integer user_id Battle.net user id.
• integer subregion Battle.net user subregion.
• string realm (NA,EU,KR,SEA) Realm/gateway of player (same as replay). convenience
• string profile_url URL to battle.net profile. convenience

Event-based attributes

• list abilities_used List of (integer frame, string ability, [list objects]) tuples indicating ability use ?
• list objects List of GameObject instances indicating the units and buildings the player selected during play.
• Selection selection Object representing all selections during gameplay; Selection is a dict-like object with frame as key.
• list hotkeys List of Selection objects representing hotkeys 0-9.

class GameObject

Selectable object in the game like a unit or building.

Attributes

• Player player (optional) Player owning this object.
• tuple observed (integer, integer) tuple denoting when object was first and last seen.
• TimeDict object_type A TimeDict dictionary containing information about which object type (morphs, upgrades) this object had at a specific frame.

Methods

• boolean alive_at (integer frame)
• boolean alive_between (integer from, integer to)

class Selection

Selection is a subclass of dict and uses an integer frame as key. It interpolates the data, so querying a frame between set keys X and Y results in the data set for X.

Selection keeps all data (in values) ordered by object id. This is based on the internal ordering used in the replay file.

Class methods

Class methods are used as helper-functions on selections represented by lists (do not modify anything on Selection instances)

• list replace (list selection, list indexes) Replace selection with just the indexes given in indexes; for example selection [4,5,6] with indexes [1,2] yields [5,6].
• list deselect (list selection, list indexes) Deselect objects on indexes in selection; for example selection [4,5,6] with indexes [1,2] yields [4].
• list mask (list selection, list mask) Deselect objects on the mask in selection; for example selection [4,5,6] with mask [True,False,True] yields [4,6].

class Event

Events are in-game events like selecting units or moving the camera.

Attributes

• Client client (optional) Client owning this object. If not set, the event was global.
• integer frame Time the event occurred.

class Message

Messages are handled outside of other events in the replay file.

Attributes

• integer sent Frame the message was sent.
• Client sender Client which sent the message.
• string target (all,allies) Target of the message.
• string message Contents of the message.

Processor extensions

These describe what the built-in (possibly optional) post-processors add to the model. I think processors should have their own docs (except for ones in the default processor list, because they modify the structures by default :-))

ResultProcessor

TODO ... adds winner attributes ... also: winner might be recorded in replayfile somewhere?

APMProcessor

TODO ... adds apm, aps and other APM attributes ...

RecorderProcessor

TODO ... figures out which client recorded the replay ...

CompositionProcessor

TODO ... adds compositions to Player objects ...

HotkeyProcessor

TODO ... adds hotkey setup to Player objects

HackDetectionProcessor

TODO ... adds some fancy probabilities/hack detects to Player objects or Event objects ...