Struct Bot

pub struct Bot {

    pub race: Race,
    pub enemy_race: Race,
    pub player_id: u32,
    pub enemy_player_id: u32,
    pub opponent_id: String,
    pub debug: Debugger,
    pub game_info: GameInfo,
    pub game_data: Rc<GameData>,
    pub state: GameState,
    pub race_values: Rc<RaceValues>,
    pub units: AllUnits,
    pub time: f32,
    pub minerals: u32,
    pub vespene: u32,
    pub supply_army: u32,
    pub supply_workers: u32,
    pub supply_cap: u32,
    pub supply_used: u32,
    pub supply_left: u32,
    pub start_location: Point2,
    pub enemy_start: Point2,
    pub start_center: Point2,
    pub enemy_start_center: Point2,
    pub expansions: Vec<Expansion>,
    pub vision_blockers: Vec<Point2>,
    pub ramps: Ramps,
    /* private fields */
}

Main bot struct. Structs with #[bot] attribute will get all it’s fields and methods through Deref and DerefMut traits.

Fields

race: Race

Actual race of your bot.

enemy_race: Race

Requested race of your opponent.

player_id: u32

Your in-game id.

enemy_player_id: u32

Opponent’s in-game id.

opponent_id: String

Opponent id on ladder, filled in --OpponentId.

debug: Debugger

Debug API

game_info: GameInfo

Information about map.

game_data: Rc<GameData>

Constant information about abilities, unit types, upgrades, buffs and effects.

state: GameState

Information about current state, updated each step.

race_values: Rc<RaceValues>

Values, which depend on bot’s race

units: AllUnits

Structured collection of units.

time: f32

In-game time in seconds.

minerals: u32

Amount of minerals bot has.

vespene: u32

Amount of gas bot has.

supply_army: u32

Amount of supply used by army.

supply_workers: u32

Amount of supply used by workers.

supply_cap: u32

The supply limit.

supply_used: u32

Total supply used.

supply_left: u32

Amount of free supply.

start_location: Point2

Bot’s starting location.

enemy_start: Point2

Opponent’s starting location.

start_center: Point2

Bot’s resource center on start location.

enemy_start_center: Point2

Opponents’s resource center on start location.

expansions: Vec<Expansion>

All expansions.

vision_blockers: Vec<Point2>

Obstacles on map which block vision of ground units, but still pathable.

ramps: Ramps

Ramps on map.

Implementations

impl Bot

pub fn api(&self) -> &API

Interface for interacting with SC2 API through Request/Response.

pub fn set_game_step(&self, val: u32)

Sets step between every on_step iteration (e.g. on 1 on_step will be called every frame, on 2 every second frame, …). Must be bigger than 0.

pub fn game_step(&self) -> u32

Returns current game step.

pub fn set_allow_spam(&self, val: bool)

Sets to true, allows units to forcibly execute commands, ignoring spam filter.

pub fn allow_spam(&self) -> bool

Returns true if units allowed to spam commands, false otherwise.

pub fn counter(&self) -> CountOptions<'_>

Constructs new CountOptions, used to count units fast and easy.

Examples

Count all ready marines:

let count = self.counter().count(UnitTypeId::Marine);

Count all supplies in progress:

let count = self.counter().ordered().count(UnitTypeId::SupplyDepot);

Count all ready and ordered nexuses:

let count = self.counter().all().count(UnitTypeId::Nexus);

Count all ready zerglings, taking burrowed ones into accont:

let count = self.counter().alias().count(UnitTypeId::Zergling);

Count all terran bases and alias (orbital, planetary fortress), including ccs in progress:

let count = self.counter().all().tech().count(UnitTypeId::CommandCenter);

pub fn enemy_counter(&self) -> CountOptions<'_>

The same as counter, but counts enemy units instead.

All information about enemy units count is based on scouting. Also there’s no way to see ordered enemy units, but bot sees enemy structures in-progress.

pub fn get_unit_api_cost(&self, unit: UnitTypeId) -> Cost

Returns full cost of building given unit type, without any corrections.

pub fn get_unit_cost(&self, unit: UnitTypeId) -> Cost

Returns correct cost of building given unit type.

pub fn can_afford(&self, unit: UnitTypeId, check_supply: bool) -> bool

Checks if bot has enough resources and supply to build given unit type.

pub fn get_upgrade_cost(&self, upgrade: UpgradeId) -> Cost

Checks cost of making given upgrade.

pub fn can_afford_upgrade(&self, upgrade: UpgradeId) -> bool

Checks if bot has enough resources to make given upgrade.

pub fn subtract_resources(&mut self, unit: UnitTypeId, subtract_supply: bool)

Subtracts cost of given unit type from minerals, vespene, supply_left and adds to supply_used.

pub fn subtract_upgrade_cost(&mut self, upgrade: UpgradeId)

Subtracts cost of given upgrade from minerals and vespene.

pub fn has_upgrade(&self, upgrade: UpgradeId) -> bool

Checks if given upgrade is complete.

pub fn enemy_has_upgrade(&self, upgrade: UpgradeId) -> bool

Checks if predicted opponent’s upgrades contains given upgrade.

pub fn enemy_upgrades(&self) -> RefMut<'_, FxHashSet<UpgradeId>>

Returns mutable set of predicted opponent’s upgrades.

pub fn is_ordered_upgrade(&self, upgrade: UpgradeId) -> bool

Checks if upgrade is in progress.

pub fn upgrade_progress(&self, upgrade: UpgradeId) -> f32

Returns progress of making given upgrade.

• 1 - complete
• 0 - not even ordered
• 0..1 - in progress

pub fn chat(&mut self, message: &str)

Sends message to in-game chat.

pub fn chat_ally(&mut self, message: &str)

Sends message for allies only to in-game chat (can be used for debug).

pub fn get_z_height<P: Into<(usize, usize)>>(&self, pos: P) -> f32

Returns actual terrain height on given position in 3D space.

pub fn get_height<P: Into<(usize, usize)>>(&self, pos: P) -> u8

Returns terrain height on given position.

pub fn is_placeable<P: Into<(usize, usize)>>(&self, pos: P) -> bool

Checks if it’s possible to build on given position.

pub fn is_pathable<P: Into<(usize, usize)>>(&self, pos: P) -> bool

Checks if it’s possible for ground units to walk through given position.

pub fn is_hidden<P: Into<(usize, usize)>>(&self, pos: P) -> bool

Checks if given position is hidden (wasn’t explored before).

pub fn is_fogged<P: Into<(usize, usize)>>(&self, pos: P) -> bool

Checks if given position is in fog of war (was explored before).

pub fn is_visible<P: Into<(usize, usize)>>(&self, pos: P) -> bool

Checks if given position is visible now.

pub fn is_full_hidden<P: Into<(usize, usize)>>(&self, pos: P) -> bool

Checks if given position is fully hidden (terrain isn’t visible, only darkness; only in campain and custom maps).

pub fn is_explored<P: Into<(usize, usize)>>(&self, pos: P) -> bool

Checks if given position is not hidden (was explored before).

pub fn has_creep<P: Into<(usize, usize)>>(&self, pos: P) -> bool

Checks if given position has zerg’s creep.

pub fn can_place(&self, building: UnitTypeId, pos: Point2) -> bool

Simple wrapper around query_placement. Checks if it’s possible to build given building on given position.

pub fn can_place_some(&self, places: Vec<(UnitTypeId, Point2)>) -> Vec<bool>

Simple wrapper around query_placement. Multi-version of can_place.

pub fn find_placement( &self, building: UnitTypeId, near: Point2, options: PlacementOptions, ) -> Option<Point2>

Nice wrapper around query_placement. Returns correct position where it is possible to build given building, or None if position is not found or building can’t be built by a worker.

pub fn find_gas_placement(&self, base: Point2) -> Option<Unit>

Another wrapper around query_placement, used to find free geyser near given base.

Returns Unit of geyser or None if there’re no free geysers around given base.

pub fn get_expansion(&self) -> Option<&Expansion>

Returns next possible location from expansions closest to bot’s start location or None if there aren’t any free locations.

pub fn get_enemy_expansion(&self) -> Option<&Expansion>

Returns next possible location from expansions closest to opponent’s start location or None if there aren’t any free locations.

pub fn owned_expansions(&self) -> impl Iterator<Item = &Expansion>

Returns all expansions taken by bot.

pub fn enemy_expansions(&self) -> impl Iterator<Item = &Expansion>

Returns all expansions taken by opponent.

pub fn free_expansions(&self) -> impl Iterator<Item = &Expansion>

Returns all available expansions.

pub fn query_pathing( &self, paths: Vec<(Target, Point2)>, ) -> SC2Result<Vec<Option<f32>>>

Sends pathing requests to API.

Takes Vec of (start, goal), where start is position or unit tag and goal is position.

Returns Vec ordered by input values, where element is distance of path from start to goal or None if there’s no path.

pub fn query_placement( &self, places: Vec<(AbilityId, Point2, Option<u64>)>, check_resources: bool, ) -> SC2Result<Vec<ActionResult>>

Sends placement requests to API. Takes creep, psionic matrix, and other stuff into account.

Returned results will be successful when:

• given ability can be used by worker
• check_resources is false or bot has enough resources to use given ability
• worker tag is None or worker can reach given position
• given place is free of obstacles

Takes Vec of (build ability, position, tag of worker or None).

Returns Vec of ActionResult ordered by input values.

pub fn leave(&self) -> SC2Result<()>

Leaves current game, which is counted as Defeat for bot.

Note: on_end will not be called, if needed use debug.end_game instead.

Trait Implementations

impl Default for Bot

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Bot

fn drop(&mut self)

Executes the destructor for this type.