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.AddToControlGroupEvent(frame, pid, data)

Extends ControlGroupEvent

This event adds the current selection to the control group.

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

Extends CommandEvent

This event is recorded for events that have no extra information recorded.

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

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.

class sc2reader.events.game.CommandEvent(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 TargetPointCommandEvent, TargetUnitCommandEvent, and DataCommandEvent for individual details.

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

ControlGroup events are recorded when ever a player action modifies or accesses a control group. There are three kinds of events, generated by each of the possible player actions:

  • SetControlGroup - Recorded when a user sets a control group (ctrl+#).
  • GetControlGroup - Recorded when a user retrieves a control group (#).
  • AddToControlGroup - Recorded when a user adds to a control group (shift+ctrl+#)

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

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

Extends CommandEvent

DataCommandEvent 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 like all CommandEvents, the event will be recorded regardless of whether or not the command was successful.

class sc2reader.events.game.GameEvent(frame, pid)

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

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.

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

Extends ControlGroupEvent

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.

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

Generated when players take over from a replay.

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

Recorded when a player leaves the game.

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

Generated when a player cancels their resource request.

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

Generated when a player creates a resource request.

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

Generated when a player accepts a resource request.

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

Generated when a player trades resources with another player. But not when fullfulling resource requests.

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 ControlGroupEvent is generated.

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

Extends ControlGroupEvent

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.

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

Extends CommandEvent

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 CommandEvents, the event will be recorded regardless of whether or not the command was successful.

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

Extends CommandEvent

This event is 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 like all CommandEvents, the event will be recorded regardless of whether or not the command was successful.

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.