Game Events

Game events are what the Starcraft II engine uses to reconstruct games for you to watch and take over in. Because the game is deterministic, only event data directly created by a player action is recorded. These player actions are then replayed automatically when watching a replay. Because the AI is 100% deterministic no events are ever recorded for a computer player.

class sc2reader.events.game.AbilityEvent(frame, pid, data)

Ability events are generated when ever a player in the game issues a command to a unit or group of units. They are split into three subclasses of ability, each with their own set of associated data. The attributes listed below are shared across all ability event types.

See LocationAbilityEvent, TargetAbilityEvent, and SelfAbilityEvent for individual details.

is_player_action = True
logger = <logging.Logger object>
name = u'AbilityEvent'
class sc2reader.events.game.AddToHotkeyEvent(frame, pid, data)

Extends HotkeyEvent

This event adds the current selection to the control group.

name = u'AddToHotkeyEvent'
class sc2reader.events.game.CameraEvent(frame, pid, data)

Camera events are generated when ever the player camera moves, zooms, or rotates. It does not matter why the camera changed, this event simply records the current state of the camera after changing.

logger = <logging.Logger object>
name = u'CameraEvent'
class sc2reader.events.game.GameEvent(frame, pid)

This is the base class for all game events. The attributes below are universally available.

logger = <logging.Logger object>
name = u'GameEvent'
class sc2reader.events.game.GameStartEvent(frame, pid, data)

Recorded when the game starts and the frames start to roll. This is a global non-player event.

name = u'GameStartEvent'
class sc2reader.events.game.GetFromHotkeyEvent(frame, pid, data)

Extends HotkeyEvent This event replaces the current selection with the contents of the control group. The mask data is used to limit that selection to units that are currently selectable. You might have 1 medivac and 8 marines on the control group but if the 8 marines are inside the medivac they cannot be part of your selection.

name = u'GetFromHotkeyEvent'
class sc2reader.events.game.HotkeyEvent(frame, pid, data)

Hotkey events are recorded when ever a player action modifies a control group. I know that calling control group events hotkey events doesn’t make sense but for backwards compatibility I haven’t changed it yet. Sorry.

There are three kinds of hotkey events, generated by each of the possible player actions:

All three events have the same set of data (shown below) but are interpretted differently. See the class entry for details.

is_player_action = True
logger = <logging.Logger object>
name = u'HotkeyEvent'
class sc2reader.events.game.LocationAbilityEvent(frame, pid, data)

Extends AbilityEvent

This event is recorded when ever a player issues a command that targets a location and NOT a unit. Commands like Psistorm, Attack Move, Fungal Growth, and EMP fall under this category.

Note that like all AbilityEvents, the event will be recorded regardless of whether or not the command was successful.

name = u'LocationAbilityEvent'
class sc2reader.events.game.PlayerActionEvent(frame, pid)
name = u'PlayerActionEvent'
class sc2reader.events.game.PlayerLeaveEvent(frame, pid, data)

Recorded when a player leaves the game.

name = u'PlayerLeaveEvent'
class sc2reader.events.game.ResourceRequestCancelEvent(frame, pid, data)
name = u'ResourceRequestCancelEvent'
class sc2reader.events.game.ResourceRequestEvent(frame, pid, data)
name = u'ResourceRequestEvent'
class sc2reader.events.game.ResourceRequestFulfillEvent(frame, pid, data)
name = u'ResourceRequestFulfillEvent'
class sc2reader.events.game.ResourceTradeEvent(frame, pid, data)
logger = <logging.Logger object>
name = u'ResourceTradeEvent'
class sc2reader.events.game.SelectionEvent(frame, pid, data)

Selection events are generated when ever the active selection of the player is updated. Unlike other game events, these events can also be generated by non-player actions like unit deaths or transformations.

Starting in Starcraft 2.0.0, selection events targetting control group buffers are also generated when control group selections are modified by non-player actions. When a player action updates a control group a HotkeyEvent is generated.

is_player_action = True
logger = <logging.Logger object>
name = u'SelectionEvent'
class sc2reader.events.game.SelfAbilityEvent(frame, pid, data)

Extends AbilityEvent

SelfAbilityEvents are recorded when ever a player issues a command that has no target. Commands like Burrow, SeigeMode, Train XYZ, and Stop fall under this category.

Note that all AbilityEvents are recorded regardless of whether or not the command was successful.

name = u'SelfAbilityEvent'
class sc2reader.events.game.SetToHotkeyEvent(frame, pid, data)

Extends HotkeyEvent

This event does a straight forward replace of the current control group contents with the player’s current selection. This event doesn’t have masks set.

name = u'SetToHotkeyEvent'
class sc2reader.events.game.TargetAbilityEvent(frame, pid, data)

Extends AbilityEvent

TargetAbilityEvents are recorded when ever a player issues a command that targets a unit. The location of the target unit at the time of the command is also recorded. Commands like Chronoboost, Transfuse, and Snipe fall under this category.

Note that all AbilityEvents are recorded regardless of whether or not the command was successful.

name = u'TargetAbilityEvent'
class sc2reader.events.game.UserOptionsEvent(frame, pid, data)

This event is recorded for each player at the very beginning of the game before the GameStartEvent.

name = u'UserOptionsEvent'
sc2reader.events.game.create_command_event(frame, pid, data)
sc2reader.events.game.create_control_group_event(frame, pid, data)