The BotAI class

The class sc2.BotAI provides a base class for all bots. It has methods that can be used to access the game state and to create actions.

Properties

Name	Type	Description
player_id	int	Unique identifier (1 or 2)
race	Race	Your bot's race
enemy_race	Race	The opponent race. Stays Random even if you scout a random players race.
time	float	Game time in seconds
time_formatted	str	Game time in minutes:seconds format
start_location	Point2	Your spawn location
enemy_start_locations	list[Point2]	Possible enemy start locations
known_enemy_units	Units	Currently visible enemy units and structures, also snapshots of the seen structures in the fog of war
known_enemy_structures	Units	Currently visible structures and snapshots of the seen structures in the fog of war
main_base_ramp	Ramp	Your main base ramp. There are terran building positions for the ramp available for supply depots and barracks placement.
expansion_locations	dict[Point2:Units]	A dict with key: Point2 and value: Units of each bases' resources (minerals and gas geysers) with the key being optimal base location
owned_expansions	dict[Point2:Unit]	A dict with key Point2 of the own expansion locations and value Unit the own expansion at that location
workers	Units	Own workers
units	Units	Own units
townhalls	Units	Own townhalls
geysers	Units	Own gas extraction buildings
minerals	int	Amount of minerals
vespene	int	Amount of vespene gas
supply_used	int	Current supply used by units
supply_cap	int	Current supply cap limited by bases, supply depots (+ extra calldown supply), pylons, overlords and overseers.
supply_left	int	Difference supply_cap - supply_used. Can be negative.
game_info	GameInfo	Contains the initial/static game state (for more info see below)
_game_data	GameData	Contains data about units, abilities, upgrades, buffs and effects
state	GameState	Contains data about the current state of the game (fore more info see below)

Methods

Name	Description
can_afford(item_id)	Tests if the player has enough resources to build a unit, research an upgrade or use an ability. It takes previous actions (ran through self.do) into account
select_build_worker(pos, force=False)	Selects a free worker near to pos to build a building. If force=True is given, selects a random worker if no workers were available or near
async can_place(building, position)	async Tests if the building can be placed in the given position
async find_placement(building, near, max_distance=20)	async Finds a free position for the building near the given position
already_pending(unit_type)	Tests if the given unit is already being built
async build(building, near, max_distance=20, unit=None)	async Builds the given building, optionally with the specific unit given. Use the near param to specify a structure or a position near to which this building is to be built.
async do(action)	async Executes the given action. Returns error object if fails.
async do_actions(list_of_actions)	async Executes the given actions. Returns no errors. It is recommended to use this instead of await self.do(action) when your bot starts to run very slowly
async def chat_send(self, message)	async Sends a chat message. Emojis are supported, so e.g. writing (glhf) is replaced with the glhf-icon

Inheriting

The async on_step methods, called on every game step, must be overridden. Optionally you can also override the on_start method to set up your class after the game data has been given. The on_end method will be called after a game has successfully (without crashing) ended.

Race-specific methods and properties

Protoss

Name	Description
state.psionic_matrix.covers(pos)	Check psionic matrix coverage

The GameInfo Class

Properties

Name	Description
_proto	The raw data from the protocol
players	A list of players as Player object
pathing_grid	A PixelMap object containing data of possible unit movement locations
terrain_height	A PixelMap object containing data of terrain height. This is not exactly the same as the Z-location of a unit.position3d
placement_grid	A PixelMap object containing data of possible building placement locations (1x1 grid positions)
playable_area	A Rect object
map_ramps	A list of ramps as Ramp object. See main_base_ramp
player_races	A dict of player id mapped to their Race
start_locations	A list of start locations as Point2
player_start_location	Same as from the bot class self.start_location
map_center	The center of the map as Point2

The GameState Class

Properties

Name	Description
actions	A list of sucessful unit actions since last game loop
action_errors	A list of unsucessful unit actions since last game loop
observation	The raw observation from the API
player_result	The player result at the end of the game. Recommendation: use the self.on_end() function instead.
chat	A list of chat messages sent from the opponent
common	A Common object that will be extracted each game loop to self.minerals, self.vespene and the supply values
psionic_matrix	A list of PsionicMatrix objects for checking if a protoss building is powered
game_loop	An integer of the current game loop. By default, this increments by 8 every iteration which means every game second around 3 iterations will be executed
score	A ScoreDetails object containing up to date stats of income, spending and destruction (resources related)
abilities	A list of available abilities this game loop from the selected units (not useful for this API)
destructables	A Units object of all the destructable rocks (excluding the one next to the main ramp)
units	A Units object of all units (own, enemy and neutral)
blips	A set of Blip objects (units detected by own terran sensor towers), more limited information than normal enemy units
visibility	A PixelMap object containing data about if you have (or had) vision to a position
creep	A PixelMap object containing data about if there is creep on a position
dead_units	A set of unit tags (int) that died last game loop
effects	A set of EffectData objects (e.g. high templar storms, ravager biles)
upgrades	A set of UpgradeId enum entries that have been researched
mineral_field	Equivalent to using self.state.units.mineral_field: A Units object containing all mineral fields
vespene_geyser	Equivalent to using self.state.units.vespene_geyser: A Units object containing all vespene geysers fields