Helpers

There are several classes related to processing information about the game state and the input from Starcraft. All these classes are taken more or less directly from the original CommandCenter, but we have left all decision-making to the user of the API.

Here is a full list of all managers:

The rest of this page contains a brief description of each manager.

BaseLocationManager

class library.BaseLocationManager
base_locations

A list of all library.BaseLocation on the current map

starting_base_locations

A list of all library.BaseLocation on the current map which a player started at, indexed by Player constant (see Player constants).

BaseLocationManager.get_occupied_base_locations(self: library.BaseLocationManager, player_constant: int) → Set[library.BaseLocation]
BaseLocationManager.get_player_starting_base_location(self: library.BaseLocationManager, player_constant: int) → library.BaseLocation
BaseLocationManager.get_next_expansion(self: library.BaseLocationManager, player_constant: int) → library.BaseLocation

BaseLocation

class library.BaseLocation

Closely related to BaseLocationManager. This is the datastructure used by the BaseLocationManager to keep track of all base locations and related information.

position

The position of the center of the BaseLocation, defined as a library.Point2D.

depot_position

A suitable position for building a town hall (Command Center, Hatchery or Nexus), defined as a library.Point2DI.

BaseLocation.mineral_fields

Alias for minerals in order to differentiate from harvested minerals

BaseLocation.minerals

List of mineral fields at base location (List of unit)

BaseLocation.geysers

List of geysers at base location (List of units)

BaseLocation.get_ground_distance(*args, **kwargs)

Overloaded function.

  1. get_ground_distance(self: library.BaseLocation, arg0: library.Point2D) -> int
  2. get_ground_distance(self: library.BaseLocation, arg0: library.Point2DI) -> int

This function uses BFS and moves in a vertical and horizontal position. Because of this, the distance might overshoot compared to calculating it with Pythagoras’ theorem.

BaseLocation.is_occupied_by_player(self: library.BaseLocation, player constant: int) → bool
BaseLocation.is_player_start_location(self: library.BaseLocation, player_constant: int) → bool
BaseLocation.contains_position(self: library.BaseLocation, arg0: library.Point2D) → bool

TechTree

class library.TechTree

This class contains all information about units and what is required to build a certain unit and what builds it. It only has one method, which is used to look-up unit types properties:

This class has some invalid information by default, this can be corrected by placing the file techtree.json in the working directory. The techtree.json files are available here, select the lastest version. A techtree for SC2 version >=4.10 is now available (not fully tested yet), this can be found under the folder data in this link. A recent file is included in the template repository.

Instead of using TechTree, it’s possible to use the functions in UnitType for structure, etc. In IDABot there is functions for getting data about upgrades.

get_data(argument) → library.TypeData

Argument is either an instance of the class library.UnitType or an instance of the class library.CCUpgrade, depending on what information is wanted.

TypeData

class library.TypeData
build_ability

the ability that creates this item

build_time

build time of the item in seconds (should be 32 game updates per tick, can someone verify this?)

gas_cost

gas cost of the item

is_addon
is_building
is_refinery
is_resource_depot
is_supply_provider
is_unit
is_worker
mineral_cost

mineral cost of the item

race
required_addons

a unit of this type must be present next to the producer -> List[UnitType]

required_units

owning ONE of these is required to make -> List[UnitType]

required_upgrades

having ALL of these is required to make -> List[UPGRADE_ID]

supply_cost

supply cost of the item

warp_ability

the ability that creates this item via warp-in

what_builds

any of these units can build the item

MapTools

class library.MapTools

This class contains two types of methods:

  • Methods for drawing information to the screen
  • Methods for extracting information about the map

First, let us look at the method concerning drawing information to the screen. Methods with the suffix _screen takes percentages of the screens height and width, i.e. values between 0 and 1. Methods without this suffix uses the same coordinate system as the game, i.e. world coordinates.

The top three methods below takes in a Point2D, but it’s possible to send in x and y as floats instead of Point2D.

draw_box(self: library.MapTools, top_left: library.Point2D, bottom_right: library.Point2D, color: library.Color=<Color (255, 255, 255)>) → None
draw_circle(self: library.MapTools, center: library.Point2D, radius: float, color: library.Color=<Color (255, 255, 255)>) → None
draw_resource_sphere(self: library.MapTools, center: sc2::Point3D, radius: float, color: library.Color=<Color (255, 255, 255)>) → None
draw_line(self: library.MapTools, start: library.Point2D, stop: library.Point2D, color: library.Color=<Color (255, 255, 255)>) → None
draw_text(self: library.MapTools, position: library.Point2D, text: str, color: library.Color=<Color (255, 255, 255)>) → None
draw_text_screen(self: library.MapTools, percentage_x: float, percentage_y: float, text: str, color: library.Color=<Color (255, 255, 255)>) → None

These are methods which are useful for extracting information about the game map:

can_build_type_at_position(self: library.MapTools, x: int, y: int, unit_type: library.UnitType) → bool
get_closest_tiles_to(self: library.MapTools, point2di: library.Point2DI) → List[library.Point2DI]

Returns a list of positions, where the first position is the closest and the last is the furthest

get_distance_map(*args, **kwargs)

Overloaded function.

  1. get_distance_map(self: library.MapTools, point2di: library.Point2DI) -> library.DistanceMap
  2. get_distance_map(self: library.MapTools, point2d: library.Point2D) -> library.DistanceMap
get_ground_distance(self: library.MapTools, from: library.Point2D, to: library.Point2D) → int
get_least_recently_seen_tile(self: library.MapTools) → library.Point2DI
height

The height of the map

width

The width of the map

is_buildable(*args, **kwargs)

Overloaded function.

  1. is_buildable(self: library.MapTools, x: int, y: int) -> bool
  2. is_buildable(self: library.MapTools, point2di: library.Point2DI) -> bool
is_connected(*args, **kwargs)

Overloaded function.

  1. is_connected(self: library.MapTools, x1: int, y1: int, x2: int, y2: int) -> bool
  2. is_connected(self: library.MapTools, from: library.Point2DI, too: library.Point2DI) -> bool
  3. is_connected(self: library.MapTools, from: library.Point2D, too: library.Point2D) -> bool
is_depot_buildable_tile(self: library.MapTools, x: int, y: int) → bool
is_explored(*args, **kwargs)

Overloaded function.

  1. is_explored(self: library.MapTools, x: int, y: int) -> bool
  2. is_explored(self: library.MapTools, point2d: library.Point2D) -> bool
  3. is_explored(self: library.MapTools, point2di: library.Point2DI) -> bool
is_powered(self: library.MapTools, x: int, y: int) → bool
is_valid_position(self: library.MapTools, point_2d: library.Point2D) → bool
is_valid_tile(*args, **kwargs)

Overloaded function.

  1. is_valid_tile(self: library.MapTools, x: int, y: int) -> bool
  2. is_valid_tile(self: library.MapTools, point_2di: library.Point2DI) -> bool
is_visible(self: library.MapTools, x: int, y: int) → bool
is_walkable(*args, **kwargs)

Overloaded function.

  1. is_walkable(self: library.MapTools, x: int, y: int) -> bool
  2. is_walkable(self: library.MapTools, point2di: library.Point2DI) -> bool
can_build_type_at_position(self: library.MapTools, x: int, y: int, unit_type: library.UnitType) → bool
draw_box(self: library.MapTools, top_left: library.Point2D, bottom_right: library.Point2D, color: library.Color=<Color (255, 255, 255)>) → None
draw_circle(self: library.MapTools, center: library.Point2D, radius: float, color: library.Color=<Color (255, 255, 255)>) → None
draw_line(self: library.MapTools, start: library.Point2D, stop: library.Point2D, color: library.Color=<Color (255, 255, 255)>) → None
draw_resource_sphere(self: library.MapTools, center: sc2::Point3D, radius: float, color: library.Color=<Color (255, 255, 255)>) → None
draw_text(self: library.MapTools, position: library.Point2D, text: str, color: library.Color=<Color (255, 255, 255)>) → None
draw_text_screen(self: library.MapTools, percentage_x: float, percentage_y: float, text: str, color: library.Color=<Color (255, 255, 255)>) → None
get_closest_tiles_to(self: library.MapTools, point2di: library.Point2DI) → List[library.Point2DI]

Returns a list of positions, where the first position is the closest and the last is the furthest

get_distance_map(*args, **kwargs)

Overloaded function.

  1. get_distance_map(self: library.MapTools, point2di: library.Point2DI) -> library.DistanceMap
  2. get_distance_map(self: library.MapTools, point2d: library.Point2D) -> library.DistanceMap
get_ground_distance(self: library.MapTools, from: library.Point2D, to: library.Point2D) → int
get_least_recently_seen_tile(self: library.MapTools) → library.Point2DI
height

The height of the map

is_buildable(*args, **kwargs)

Overloaded function.

  1. is_buildable(self: library.MapTools, x: int, y: int) -> bool
  2. is_buildable(self: library.MapTools, point2di: library.Point2DI) -> bool
is_connected(*args, **kwargs)

Overloaded function.

  1. is_connected(self: library.MapTools, x1: int, y1: int, x2: int, y2: int) -> bool
  2. is_connected(self: library.MapTools, from: library.Point2DI, too: library.Point2DI) -> bool
  3. is_connected(self: library.MapTools, from: library.Point2D, too: library.Point2D) -> bool
is_depot_buildable_tile(self: library.MapTools, x: int, y: int) → bool
is_explored(*args, **kwargs)

Overloaded function.

  1. is_explored(self: library.MapTools, x: int, y: int) -> bool
  2. is_explored(self: library.MapTools, point2d: library.Point2D) -> bool
  3. is_explored(self: library.MapTools, point2di: library.Point2DI) -> bool
is_powered(self: library.MapTools, x: int, y: int) → bool
is_valid_position(self: library.MapTools, point_2d: library.Point2D) → bool
is_valid_tile(*args, **kwargs)

Overloaded function.

  1. is_valid_tile(self: library.MapTools, x: int, y: int) -> bool
  2. is_valid_tile(self: library.MapTools, point_2di: library.Point2DI) -> bool
is_visible(self: library.MapTools, x: int, y: int) → bool
is_walkable(*args, **kwargs)

Overloaded function.

  1. is_walkable(self: library.MapTools, x: int, y: int) -> bool
  2. is_walkable(self: library.MapTools, point2di: library.Point2DI) -> bool
width

The width of the map

Color

class library.Color
__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: library.Color) -> None
  2. __init__(self: library.Color, r: int, g: int, b: int) -> None
BLACK = <Color (0, 0, 0)>
BLUE = <Color (0, 0, 255)>
GRAY = <Color (128, 128, 128)>
GREEN = <Color (0, 255, 0)>
PURPLE = <Color (255, 0, 255)>
RED = <Color (255, 0, 0)>
TEAL = <Color (0, 255, 255)>
WHITE = <Color (255, 255, 255)>
YELLOW = <Color (255, 255, 0)>
b

Blue

g

Green

r

Red

DistanceMap

class library.DistanceMap
computer_distance_map(self: library.DistanceMap, bot: IDABot, start_tile: library.Point2DI) → None
draw(self: library.DistanceMap, bot: IDABot) → None
get_distance(*args, **kwargs)

Overloaded function.

  1. get_distance(self: library.DistanceMap, position: library.Point2DI) -> int
  2. get_distance(self: library.DistanceMap, position: library.Point2D) -> int
get_sorted_tiles(self: library.DistanceMap) → List[library.Point2DI]
get_start_tile(self: library.DistanceMap) → library.Point2DI

BuildingPlacer

class library.BuildingPlacer

This class is useful for placing all buildings, except refineries and town halls (Command Centers, Hacheries and Nexus).

If you want to place a town hall, take a look at attribute depot_location of library.BaseLocation.

If you want to place a refinery, take a look at attribute geysers of library.BaseLocation and the method build_target of library.Unit.

can_build_here(self: library.BuildingPlacer, x: int, y: int, unit_type: library.UnitType) → bool
can_build_here_with_spaces(self: library.BuildingPlacer, x: int, y: int, unit_type: library.UnitType, distance_to_building: int) → bool

Creates a square with the help of x, y, distance_to_building and the size of the unit_type. Good approach if we later gonna make a addon to the building.

free_tiles(self: library.BuildingPlacer, x: int, y: int, width: int, height: int) → None

Free the tile (x, y) from reservation

get_build_location_near(self: library.BuildingPlacer, point2di: library.Point2DI, unit_type: library.UnitType, distance_to_building: int=2, search_count: int=1000) → library.Point2DI

The search_count is how many building we should check (nearby buildings, instead of i < size, we can switch size to search_count). distance_to_building is the distance to the closest building.

reserve_tiles(self: library.BuildingPlacer, x: int, y: int, width: int, height: int) → None

It’s possible to reserve tiles, which makes it impossible to build at the position given by x and y.