Game

class BWAPI.Game

The Game class is implemented by BWAPI and is the primary means of obtaining all game state information from Starcraft Broodwar.

Game state information includes all units, resources, players, forces, bullets, terrain, fog of war, regions, etc.

See also

BWAPI.Broodwar

Constructors

This class is not constructable through Lua.

Member Variables

clientInfo

A Lua table that can be used to store arbitrary data associated with the current object.

Example usage
obj.clientInfo["test"] = 5
print(obj.clientInfo["test"]) -- prints "5"

See also

The differences between the C++ and Lua implementations

Member Functions

registerEvent(action[, condition = nil][, timesToRun = -1][, framesToCheck = 0])

Registers an event and associates it with the current object.

Events can be used to automate tasks (like train X Marines until Y of them have been created by the given Barracks) or to create user-defined callbacks.

Parameters:
  • action (function) – The callback to be executed when the event conditions are true.
  • condition (function) – (optional) The condition callback which will return true if the action is intended to be executed. The condition will always be true if omitted.
  • timesToRun (int) – (optional) The number of times to execute the action before the event is removed. If the value is negative, then the event will never be removed. The value will be -1 if omitted, causing the event to execute until the game ends.
  • framesToCheck (int) – (optional) The number of frames to skip between checks. If this value is 0, then a condition check is made once per frame. If this value is 1, then the condition for this event is only checked every other frame. This value is 0 by default, meaning the event’s condition is checked every frame.
allies() → Playerset

Retrieves a set of all the current player’s remaining allies.

Returns:Playerset containing all allied players.
Return type:BWAPI.Playerset
canBuildHere(position, type[, builder = nil][, checkExplored = false]) → boolean

Checks if the given unit type can be built at the given build tile position.

This function checks for creep, power, and resource distance requirements in addition to the tiles’ buildability and possible units obstructing the build location.

Parameters:
  • position (BWAPI.TilePosition) – Indicates the tile position that the top left corner of the structure is intended to go.
  • type (BWAPI.UnitType) – The UnitType to check for.
  • builder (BWAPI.Unit) – (optional) The intended unit that will build the structure. If specified, then this function will also check if there is a path to the build site and exclude the builder from the set of units that may be blocking the build site.
  • checkExplored (boolean) – (optional) If this parameter is true, it will also check if the target position has been explored by the current player. This value is false by default, ignoring the explored state of the build site.
Returns:

true indicating that the structure can be placed at the given tile position, and false if something may be obstructing the build location.
Return type:

boolean

Note

If the type is an addon and a builer is provided, then the location of the addon will be placed 4 tiles to the right and 1 tile down from the given position. If the builder is not given, then the check for the addon will be conducted at position.

Note

If the type is UnitTypes.Special_Start_Location, then the are for a resource depot (Command Center, Hatchery, Nexus) is checked as normal, but any potential obstructions (existing structures, creep, units, etc.) are ignored.

canMake(type[, builder = nil]) → boolean

Checks all the requirements in order to make a given unit type for the current player.

These include resources, supply, technology tree, availability, and required units.

Parameters:
  • type (BWAPI.UnitType) – The UnitType to check.
  • builder (BWAPI.Unit) – (optional) The Unit that will be used to build/train the provided unit type. If this value is nil or excluded, then the builder will be excluded in the check.
Returns:

true indicating that the type can be made. If builder is provided, then it is only true if builder can make the type. Otherwise it will return false, indicating that the unit type can not be made.
Return type:

boolean
canResearch(type[, unit = nil][, checkCanIssueCommandType = true]) → boolean

Checks all the requirements in order to research a given technology type for the current player.

These include resources, technology tree, availability, and required units.

Parameters:
  • type (BWAPI.TechType) – The TechType to check.
  • unit (BWAPI.Unit) – (optional) The Unit that will be used to research the provided technology type. If this value is nil or excluded, then the unit will be excluded in the check.
  • checkCanIssueCommandType (boolean) – (optional) TODO fill this in
Returns:

true indicating that the type can be researched. If unit is provided, then it is only true if unit can research the type. Otherwise it will return false, indicating that the technology can not be researched.
Return type:

boolean
canUpgrade(type[, unit = nil][, checkCanIssueCommandType = true]) → boolean

Checks all the requirements in order to upgrade a given upgrade type for the current player.

These include resources, technology tree, availability, and required units.

Parameters:
  • type (BWAPI.UpgradeType) – The UpgradeType to check.
  • unit (BWAPI.Unit) – (optional) The Unit that will be used to upgrade the provided upgrade type. If this value is nil or excluded, then the unit will be excluded in the check.
  • checkCanIssueCommandType (boolean) – (optional) TODO fill this in
Returns:

true indicating that the type can be upgraded. If unit is provided, then it is only true if unit can upgrade the type. Otherwise it will return false, indicating that the upgrade can not be upgraded.
Return type:

boolean
countdownTimer() → int

Returns the remaining countdown time.

The countdown timer is used in Capture The Flag and Use Map Settings game types.

Returns:Integer containing the time (in game seconds) on the countdown timer.
Return type:int
Example usage
local Broodwar = BWAPI.Broodwar

function BWAPI.onStart()
  -- Register a callback that only occurs once when the countdown timer reaches 0
  if Broodwar:getGameType() == BWAPI.GameTypes.Capture_The_Flag or
     Broodwar:getGameType() == BWAPI.GameTypes.Team_Capture_The_Flag
  then
    Broodwar:registerEvent(
      function() Broodwar:sendText("Try to find my flag!") end,
      function() return Broodwar:countdownTimer() == 0 end,
      1
    )
  end
end
elapsedTime() → int

Retrieves current amount of time in seconds that the game has elapsed.

Returns:Time, in seconds, that the game has elapsed as an integer.
Return type:int
enableFlag(flag)

Enables the state of a given flag.

Parameters:flag (int) – The Flag entry describing the flag’s effects on BWAPI.

Note

Flags may only be enabled at the start of the match during the BWAPI.onStart() callback.

See also

Flag

enemies() → Playerset

Retrieves a set of all the current player’s remaining enemies.

Returns:Playerset containing all enemy players.
Return type:BWAPI.Playerset
enemy() → Player

Retrieves the Player interface that represents the enemy player.

If there is more than one enemy, and that enemy is destroyed, then this function will still retrieve the same, defeated enemy. If you wish to handle multiple opponents, see the Game.enemies() function.

Returns:Player interface representing an enemy player. Returns nil if there is no enemy or the current game is a replay.
Return type:BWAPI.Player

See also

enemies()

getAllRegions() → Regionset

Retrieves the set of all regions on the map.

Returns:Regionset containing all map regions.
Return type:BWAPI.Regionset
getAllUnits() → Unitset

Retrieves the set of all accessible units.

If BWAPI.Flag.CompleteMapInformation is enabled, then the set also includes units that are not visible to the player.

Returns:Unitset containing all known units in the game.
Return type:BWAPI.Unitset

Note

Units that are inside refineries are not included in this set.

getAPM([includeSelects = false]) → int

Retrieves the Actions Per Minute (APM) that the bot is producing.

Parameters:includeSelects (boolean) – (optional) If true, the return value will include selections as individual commands, otherwise it will exclude selections. This value is false by default.
Returns:The number of actions that the bot has executed per minute, on average.
Return type:int
getAverageFPS() → double

Retrieves the average logical frame rate of the game in frames per second (FPS).

Returns:Average logical frames per second that the game is currently running at as a double.
Return type:double

See also

getFPS()

getBestUnit(best, pred[, center = Positions.Origin][, radius = 999999]) → Unit

Compares all units that match pred using best to determine which of them is the best.

All units are checked. If center and radius are specified, then it will check all units that are within the radius of the position.

Parameters:
  • best (function) – A function that takes two Unit arguments and returns the best out of the two.
  • pred (function) – A predicate function that takes a Unit and returns true for units that satisfy the intended filter and false otherwise (can be a BWAPI.Filter unary filter).
  • center (BWAPI.Position) – (optional) The position to use in the search. If omitted, then the entire map is searched.
  • radius (int) – (optional) The distance from center to search for units. If omitted, then the entire map is searched.
Returns:

The desired unit that best matches the given criteria. Returns nil if a suitable unit was not found.
Return type:

BWAPI.Unit

See also

getClosestUnit(), Filter, BWAPI.Lowest(), BWAPI.Highest()

getBuildLocation(type, desiredPosition[, maxRange = 64][, creep = false]) → TilePosition

Retrieves a basic build position just as the default Computer AI would.

This allows users to find simple build locations without relying on external libraries.

Parameters:
  • type (BWAPI.UnitType) – A valid UnitType representing the unit type to accomodate space for.
  • desiredPosition (BWAPI.TilePosition) – A valid TilePosition containing the desired placement position.
  • maxRange (int) – (optional) The maximum distance (in tiles) to build from desiredPosition.
  • creep (boolean) – (optional) A special boolean value that changes the behaviour of Zerg_Creep_Colony> placement.
Returns:

A TilePosition containing the location that the structure should be constructed at. Returns TilePositions.Invalid if a build location could not be found within maxRange.
Return type:

BWAPI.TilePosition
getBullets() → Bulletset

Retrieves the set of all accessible bullets.

Returns:Bulletset containing all accessible Bullet objects.
Return type:BWAPI.Bulletset
getClosestUnit(center[, pred = nil][, radius = 999999]) → Unit

Retrieves the closest unit to center that matches the criteria of the callback pred within an optional radius.

Parameters:
  • center (BWAPI.Position) – The position to start searching for the closest unit.
  • pred (function) – (optional) A predicate function that takes a Unit and returns true for units that satisfy the intended filter and false otherwise (can be a BWAPI.Filter unary filter). Defaults to nil, which means no filter.
  • radius (int) – (optional) The radius to search in. If omitted, the entire map will be searched.
Returns:

The desired unit that is closest to center. Returns nil if a suitable unit was not found.
Return type:

BWAPI.Unit

See also

getBestUnit(), Filter

getClosestUnitInRectangle(center[, pred = nil][, left = 0][, top = 0][, right = 999999][, bottom = 999999]) → Unit

Retrieves the closest unit to center that matches the criteria of the callback pred within an optional rectangle.

Parameters:
  • center (BWAPI.Position) – The position to start searching for the closest unit.
  • pred (function) – (optional) A predicate function that takes a Unit and returns true for units that satisfy the intended filter and false otherwise (can be a BWAPI.Filter unary filter). Defaults to nil, which means no filter.
  • left (int) – (optional) The left position of the rectangle. This value is 0 by default.
  • top (int) – (optional) The top position of the rectangle. This value is 0 by default.
  • right (int) – (optional) The right position of the rectangle. This value includes the entire map width by default.
  • bottom (int) – (optional) The bottom position of the rectangle. This value includes the entire map height by default.
Returns:
Return type:

BWAPI.Unit

See also

Filter

getDamageFrom(fromType, toType[, fromPlayer = nil][, toPlayer = nil]) → int

Calculates the damage received for a given player.

It can be understood as the damage from fromType to toType. Does not include shields in calculation. Includes upgrades if players are provided.

Parameters:
  • fromType (BWAPI.UnitType) – The unit type that will be dealing the damage.
  • toType (BWAPI.UnitType) – The unit type that will be receiving the damage.
  • fromPlayer (BWAPI.Player) – (optional) The player owner of the given type that will be dealing the damage. If omitted, then no player will be used to calculate the upgrades for fromType.
  • toPlayer (BWAPI.Player) – (optional) The player owner of the type that will be receiving the damage. If omitted, then this parameter will default to Broodwar:self().
Returns:

The amount of damage that fromType would deal to toType.
Return type:

int

See also

getDamageTo()

getDamageTo(toType, fromType[, toPlayer = nil][, fromPlayer = nil]) → int

Calculates the damage dealt for a given player.

It can be understood as the damage to toType from fromType. Does not include shields in calculation. Includes upgrades if players are provided.

Parameters:
  • toType (BWAPI.UnitType) – The unit type that will be receiving the damage.
  • fromType (BWAPI.UnitType) – The unit type that will be dealing the damage.
  • toPlayer (BWAPI.Player) – (optional) The player owner of the type that will be receiving the damage. If omitted, then no player will be used to calculate the upgrades for toType.
  • fromPlayer (BWAPI.Player) – (optional) The player owner of the given type that will be dealing the damage. If omitted, then this parameter will default to Broodwar:self().
Returns:

The amount of damage that fromType would deal to toType.
Return type:

int

Note

This function is nearly the same as getDamageFrom. The only difference is that the last parameter is intended to default to Broodwar:self().

See also

getDamageFrom()

getRandomSeed() → number

Retrieves the initial random seed that was used in this game’s creation.

This is used to identify the seed that started this game, in case an error occurred, so that developers can deterministically reproduce the error. Works in both games and replays.

Returns:This game’s random seed.
Return type:number
getForce(forceID) → Force

Retrieves the Force interface object associated with a given identifier.

Parameters:forceID (int) – The identifier for the Force object.
Returns:Force interface object mapped to the given forceID. Returns nil if the given identifier is invalid.
Return type:BWAPI.Force
getForces() → Forceset

Retrieves the set of all teams/forces.

Forces are commonly seen in Use Map Settings game types and some others such as Top vs Bottom and the team versions of game types.

Returns:Forceset containing all forces in the game.
Return type:BWAPI.Forceset
getFPS() → int

Retrieves the logical frame rate of the game in frames per second (FPS).

Returns:Logical frames per second that the game is currently running at as an integer.
Return type:int
Example:
BWAPI.Broodwar:setLocalSpeed(0)

-- Log and display the best logical FPS seen in the game
local bestFPS = 0
function BWAPI.onFrame()
  bestFPS = math.max(bestFPS, BWAPI.Broodwar:getFPS())
  BWAPI.Broodwar:drawTextScreen(BWAPI.Positions.Origin, string.format("%cBest: %d GFPS\nCurrent: %d GFPS", BWAPI.Text.White, bestFPS, BWAPI.Broodwar:getFPS()))
end

See also

getAverageFPS()

getFrameCount() → int

Retrieves the number of logical frames since the beginning of the match.

If the game is paused, then getFrameCount will not increase.

Returns:Number of logical frames that have elapsed since the game started as an integer.
Return type:int
getGameType() → GameType

Retrieves the GameType of the current game.

Returns:GameType indicating the rules of the match.
Return type:BWAPI.GameType

See also

GameType

getGeysers() → Unitset

Retrieves the set of all accessible Vespene Geysers in the game.

Returns:Unitset containing Vespene Geysers
Return type:BWAPI.Unitset
getGroundHeight(tileX, tileY) → int

Returns the ground height at the given tile position.

Parameters:
  • tileX (int) – X position to query, in tiles
  • tileY (int) – Y position to query, in tiles
Returns:

The tile height as an integer. Possible values are: 0: Low ground; 1: Low ground doodad; 2: High ground; 3: High ground doodad; 4: Very high ground; 5: Very high ground doodad
Return type:

int
getGroundHeight(position) → int

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:position (BWAPI.TilePosition) –
Returns:The tile height as an integer. Possible values are: 0: Low ground; 1: Low ground doodad; 2: High ground; 3: High ground doodad; 4: Very high ground; 5: Very high ground doodad
Return type:int
getInstanceNumber() → int

Retrieves the Starcraft instance number recorded by BWAPI to identify which Starcraft instance an AI module belongs to.

The very first instance should return 0.

Returns:An integer value representing the instance number.
Return type:int

Note

This function is considered thread-safe.

getKeyState(key) → boolean

Retrieves the state of the given keyboard key.

Parameters:key (BWAPI.Key) – A Key enum member indicating which key on the keyboard to check.
Returns:A bool indicating the state of the given key. Returns true if the key was pressed and false if it was not. Returns false always if Flag.UserInput is disabled.
Return type:boolean

See also

Key

getLastError() → Error

Returns the last error that was set using setLastError.

If a function call in BWAPI has failed, you can use this function to retrieve the reason it failed.

Returns:Error type containing the reason for failure.
Return type:BWAPI.Error

See also

setLastError(), Errors

getLastEventTime() → int

Retrieves the amount of time (in milliseconds) that has elapsed when running the last AI module callback.

This is used by tournament modules to penalize AI modules that use too much processing time.

Returns:Time in milliseconds spent in last AI module call. Returns 0 when called from an AI module.
Return type:int
getLatency() → int

Retrieves the current latency setting that the game is set to.

Latency indicates the delay between issuing a command and having it processed.

Returns:The latency setting of the game, which is of Latency.
Return type:int

See also

Latency

getLatencyFrames() → int

Retrieves the maximum delay, in number of frames, between a command being issued and the command being executed by Broodwar.

Returns:Difference in frames between commands being sent and executed.
Return type:int

Note

In Broodwar, latency is used to keep the game synchronized between players without introducing lag.

See also

getLatencyTime(), getRemainingLatencyFrames()

getLatencyTime() → int

Retrieves the maximum delay, in milliseconds, between a command being issued and the command being executed by Broodwar.

Returns:Difference in milliseconds between commands being sent and executed.
Return type:int

See also

getLatencyFrames(), getRemainingLatencyTime()

getMinerals() → Unitset

Retrieves the set of all accessible Mineral Fields in the game.

Returns:Unitset containing Mineral Fields
Return type:BWAPI.Unitset
getMousePosition() → Position

Retrieves the position of the user’s mouse on the screen, in Position coordinates.

Returns:Position indicating the location of the mouse. Returns Positions.Unknown if Flag.UserInput is disabled.
Return type:BWAPI.Position
getMouseState(button) → boolean

Retrieves the state of the given mouse button.

Parameters:button (BWAPI.MouseButton) – A MouseButton enum member indicating which button on the mouse to check.
Returns:A bool indicating the state of the given button. true if the button was pressed and false if it was not. Returns false always if Flag::UserInput is disabled.
Return type:boolean

See also

MouseButton

getNeutralUnits() → Unitset

Retrieves the set of all accessible neutral units in the game.

This includes Mineral Fields, Vespene Geysers, and Critters.

Returns:Unitset containing all neutral units.
Return type:BWAPI.Unitset
getNukeDots() → positions

Retrieves the set of all accessible Nuke dots.

Returns:Table of Positions giving the coordinates of nuke locations.
Return type:table

Note

Nuke dots are the red dots painted by a Ghost when using the nuclear strike ability.

getPlayer(playerID) → Player

Retrieves the Player associated with a given identifier.

Parameters:playerID (int) – The identifier for the Player object.
Returns:Player interface object mapped to the given playerID. Returns nil if the given identifier is invalid.
Return type:BWAPI.Player
getPlayers() → Playerset

Retrieves the set of all players in the match.

This includes the neutral player, which owns all the resources and critters by default.

Returns:Playerset containing all players in the game.
Return type:BWAPI.Playerset
getRegion(regionID) → Region

Retrieves the Region associated with a given identifier.

Parameters:regionID (int) – The identifier for the Region object.
Returns:Region object mapped to the given regionID. Returns nil if the given ID is invalid.
Return type:BWAPI.Region
getRegionAt(x, y) → Region

Retrieves the region at a given position.

Parameters:
  • x (int) – The x coordinate, in pixels.
  • y (int) – The y coordinate, in pixels.
Returns:

The Region at the given position. Returns nil if the provided position is not valid (i.e. not within the map bounds).
Return type:

BWAPI.Region

Note

If the provided position is invalid, the error Errors.Invalid_Parameter is set.

See also

getAllRegions(), getRegion()

getRegionAt(position) → Region

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:position (BWAPI.Position) –
Returns:
Return type:BWAPI.Region
getRemainingLatencyFrames() → int

Retrieves the number of frames it will take before a command sent in the current frame will be executed by the game.

Returns:Number of frames until a command is executed if it were sent in the current frame.
Return type:int

See also

getRemainingLatencyTime(), getLatencyFrames()

getRemainingLatencyTime() → int

Retrieves the number of milliseconds it will take before a command sent in the current frame will be executed by Broodwar.

Returns:Amount of time, in milliseconds, until a command is executed if it were sent in the current frame.
Return type:int

See also

getRemainingLatencyFrames(), getLatencyTime()

getReplayFrameCount() → int

Retrieves the maximum number of logical frames that have been recorded in a replay.

If the game is not a replay, then the value returned is undefined.

Returns:The number of logical frames that the replay contains.
Return type:int
getRevision() → int

Retrieves the current revision of BWAPI.

Returns:The revision number of the current BWAPI interface.
Return type:int

Note

This function is considered thread-safe.

getScreenPosition() → Position

Retrieves the top left position of the viewport from the top left corner of the map, in pixels.

Returns:Position containing the coordinates of the top left corner of the game’s viewport. Returns Positions.Unknown always if Flag.UserInput is disabled.
Return type:BWAPI.Position

See also

setScreenPosition()

getSelectedUnits() → Unitset

Retrieves the set of units that are currently selected by the user outside of BWAPI.

This function requires that BWAPI.Flag.UserInput be enabled.

Returns:A Unitset containing the user’s selected units. If BWAPI.Flag.UserInput is disabled, then this set is always empty.
Return type:BWAPI.Unitset

See also

enableFlag

getStartLocations() → tilePositions

Retrieves the set of all starting locations for the current map.

A starting location is essentially a candidate for a player’s spawn point.

Returns:An array-like table containing all the TilePosition objects that indicate a start location.
Return type:table

See also

Player.getStartLocation()

getStaticGeysers() → Unitset

Retrieves the set of all Vespene Geysers that were available at the beginning of the game.

Returns:Unitset containing static Vespene Geysers
Return type:BWAPI.Unitset

Note

This set includes resources that are inaccessible.

getStaticMinerals() → Unitset

Retrieves the set of all Mineral Fields that were available at the beginning of the game.

Returns:Unitset containing static Mineral Fields
Return type:BWAPI.Unitset

Note

This set includes resources that have been mined out or are inaccessible.

getStaticNeutralUnits() → Unitset

Retrieves the set of all units owned by the neutral player (resources, critters, etc.) that were available at the beginning of the game.

Returns:Unitset containing static neutral units
Return type:BWAPI.Unitset

Note

This set includes units that are inaccessible.

getUnit(unitID) → Unit

Retrieves the Unit interface object associated with a given identifier.

Parameters:unitID (int) – The identifier for the Unit object.
Returns:Unit interface object mapped to the given unitID. Returns nil if the given identifier is invalid.
Return type:BWAPI.Unit
getUnitsInRadius(x, y, radius[, pred = nil]) → Unitset

Retrieves the set of accessible units that are within a given radius of a position.

Parameters:
  • x (int) – The x coordinate of the center, in pixels.
  • y (int) – The y coordinate of the center, in pixels.
  • radius (int) – The radius from the center, in pixels, to include units.
  • pred (function) – (optional) A predicate function that takes a Unit and returns true for units that satisfy the intended filter and false otherwise (can be a BWAPI.Filter unary filter). Defaults to nil, which means no filter.
Returns:

A Unitset object consisting of all the units that have any part of them within the given radius from the center position.
Return type:

BWAPI.Unitset
getUnitsInRadius(center, radius[, pred = nil]) → Unitset

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • center (BWAPI.Position) – The coordinate of the center.
  • radius (int) – The radius from the center, in pixels, to include units.
  • pred (function) – (optional) A predicate function that takes a Unit and returns true for units that satisfy the intended filter and false otherwise (can be a BWAPI.Filter unary filter). Defaults to nil, which means no filter.
Returns:

A Unitset object consisting of all the units that have any part of them within the given radius from the center position.
Return type:

BWAPI.Unitset
getUnitsInRectangle(left, top, right, bottom[, pred = nil]) → Unitset

Retrieves the set of accessible units that are in a given rectangle.

Parameters:
  • left (int) – The X coordinate of the left position of the bounding box, in pixels.
  • top (int) – The Y coordinate of the top position of the bounding box, in pixels.
  • right (int) – The X coordinate of the right position of the bounding box, in pixels.
  • bottom (int) – The Y coordinate of the bottom position of the bounding box, in pixels.
  • pred (function) – (optional) A predicate function that takes a Unit and returns true for units that satisfy the intended filter and false otherwise (can be a BWAPI.Filter unary filter). Defaults to nil, which means no filter.
Returns:

A Unitset object consisting of all the units that have any part of them within the given rectangle bounds.
Return type:

BWAPI.Unitset
getUnitsInRectangle(topLeft, bottomRight[, pred = nil]) → Unitset

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • topLeft (BWAPI.Position) –
  • bottomRight (BWAPI.Position) –
  • pred (function) – (optional) A predicate function that takes a Unit and returns true for units that satisfy the intended filter and false otherwise (can be a BWAPI.Filter unary filter). Defaults to nil, which means no filter.
Returns:

A Unitset object consisting of all the units that have any part of them within the given rectangle bounds.
Return type:

BWAPI.Unitset
getUnitsOnTile(tileX, tileY[, pred = nil]) → Unitset

Retrieves the set of accessible units that are on a given build tile.

Parameters:
  • tileX (int) – The X position, in tiles.
  • tileY (int) – The Y position, in tiles.
  • pred (function) – (optional) A predicate function that takes a Unit and returns true for units that satisfy the intended filter and false otherwise (can be a BWAPI.Filter unary filter). Defaults to nil, which means no filter.
Returns:

A Unitset object consisting of all the units that have any part of them on the given build tile.
Return type:

BWAPI.Unitset
getUnitsOnTile(tile[, pred = nil]) → Unitset

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • tile (BWAPI.TilePosition) –
  • pred (function) – (optional) A predicate function that takes a Unit and returns true for units that satisfy the intended filter and false otherwise (can be a BWAPI.Filter unary filter). Defaults to nil, which means no filter.
Returns:

A Unitset object consisting of all the units that have any part of them on the given build tile.
Return type:

BWAPI.Unitset
hasCreep(tileX, tileY) → boolean

Checks if the given tile position has Zerg creep on it.

Parameters:
  • tileX (int) – The x tile coordinate to check.
  • tileY (int) – The y tile coordinate to check.
Returns:

Returns true if the given tile has creep on it, or false if the given tile does not have creep, or if it is concealed by the fog of war
Return type:

boolean
hasCreep(position) → boolean

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:position (BWAPI.TilePosition) – The coordinate to check
Returns:Returns true if the given tile has creep on it, or false if the given tile does not have creep, or if it is concealed by the fog of war
Return type:boolean
hasPath(source, destination) → boolean

Checks if there is a path from source to destination.

This only checks if the source position is connected to the destination position. This function does not check if all units can actually travel from source to destination. Because of this limitation, it has an O(1) complexity, and cases where this limitation hinders gameplay is uncommon at best.

Note

If making queries on a unit, it’s better to call Unit.hasPath(), since it is a more lenient version of this function that accounts for some edge cases.

Parameters:
Returns:

Returns true if there is a path between the two positions, or false if there is no path
Return type:

boolean

See also

Unit.hasPath()

hasPower(tileX, tileY[, unitType = UnitTypes.None]) → boolean

Checks if the given tile position if powered by an owned Protoss_Pylon for an optional unit type.

Parameters:
  • tileX (int) – The x tile coordinate to check.
  • tileY (int) – The y tile coordinate to check.
  • unitType (BWAPI.UnitType) – (optional) Checks if the given UnitType will be powered if placed at the given tile position. If omitted, then only the immediate tile position is checked for power, and the function will assume that the location requires power for any unit type.
Returns:

Returns true if the type at the given tile position will receive power, or false if the type will be unpowered at the given tile position
Return type:

boolean
hasPower(position[, unitType = UnitTypes.None]) → boolean

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • position (BWAPI.TilePosition) – The tile coordinate to check
  • unitType (BWAPI.UnitType) – (optional) Checks if the given UnitType will be powered if placed at the given tile position. If omitted, then only the immediate tile position is checked for power, and the function will assume that the location requires power for any unit type.
Returns:

Returns true if the type at the given tile position will receive power, or false if the type will be unpowered at the given tile position
Return type:

boolean
hasPower(tileX, tileY, tileWidth, tileHeight[, unitType = UnitTypes.None]) → boolean

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • tileX (int) –
  • tileY (int) –
  • tileWidth (int) –
  • tileHeight (int) –
  • unitType (BWAPI.UnitType) –
Returns:
Return type:

boolean
hasPower(position, tileWidth, tileHeight[, unitType = UnitTypes.None]) → boolean

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
Returns:
Return type:

boolean
hasPowerPrecise(x, y[, unitType = UnitTypes.None]) → boolean

Checks if the given pixel position is powered by an owned Protoss_Pylon for an optional unit type.

Parameters:
  • x (int) – The x pixel coordinate to check.
  • y (int) – The y pixel coordinate to check.
  • unitType (BWAPI.UnitType) – (optional) Checks if the given UnitType requires power or not. If ommitted, then it will assume that the position requires power for any unit type.
Returns:

Returns true if the type at the given position will have power, or false if the type at the given position will be unpowered
Return type:

boolean
hasPowerPrecise(position[, unitType = UnitTypes.None]) → boolean

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
Returns:
Return type:

boolean
indexToUnit(unitIndex) → Unit

Retrieves a Unit interface object from a given unit index.

The value given as an index maps directly to Broodwar’s unit array index and matches the index found in replay files. In order to use this function, CompleteMapInformation must be enabled.

Parameters:unitIndex (int) – The unitIndex to identify the Unit with. A valid index is 0 <= unitIndex & 0x7FF < 1700.
Returns:Unit interface object that matches the given unitIndex. Returns nil if the given index is invalid.
Return type:BWAPI.Unit
isBattleNet() → boolean

Checks if the client is in a game that was created through the Battle.net multiplayer gaming service.

Returns:true if the client is in a multiplayer Battle.net game and false if it is not.
Return type:boolean
isBuildable(tileX, tileY[, includeBuildings = false]) → boolean

Checks if a given tile position is buildable.

This means that, if all other requirements are met, a structure can be placed on this tile. This function uses static map data.

Parameters:
  • tileX (int) – The x value of the tile to check.
  • tileY (int) – The y value of the tile to check.
  • includeBuildings (boolean) – (optional) If this is true, then this function will also check if any visible structures are occupying the space. If this value is false, then it only checks the static map data for tile buildability. This value is false by default.
Returns:

boolean identifying if the given tile position is buildable (true) or not (false). If includeBuildings was provided, then it will return false if a structure is currently occupying the tile.
Return type:

boolean
isBuildable(position[, includeBuildings = false]) → boolean

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
Returns:
Return type:

boolean
isDebug() → boolean

Retrieves the debug state of the BWAPI build.

Returns:true if the BWAPI module is a DEBUG build, and false if it is a RELEASE build.
Return type:boolean

Note

This function is considered thread-safe.

isExplored(tileX, tileY) → boolean

Checks if a given tile position has been explored by the player.

An explored tile position indicates that the player has seen the location at some point in the match, partially revealing the fog of war for the remainder of the match.

Parameters:
  • tileX (int) – The x tile coordinate to check.
  • tileY (int) – The y tile coordinate to check.
Returns:

Returns true if the player has explored the given tile position (partially revealed fog), or false if the tile position was never explored (completely black fog)
Return type:

boolean

See also

isVisible

isExplored(position) → boolean

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:position (BWAPI.TilePosition) –
Returns:
Return type:boolean
isFlagEnabled(flag) → boolean

Checks if the state of the given flag is enabled or not.

Parameters:flag (int) – The BWAPI.Flag entry describing the flag’s effects on BWAPI.
Returns:true if the given flag is enabled, false if the flag is disabled.
Return type:boolean

Note

Flags may only be enabled at the start of the match during the AIModule::onStart callback.

See also

BWAPI.Flag

isGUIEnabled() → boolean

Checks if the GUI is enabled.

The GUI includes all drawing functions of BWAPI, as well as screen updates from Broodwar.

Returns:Returns true if the GUI is enabled, and everything is visible, or false if the GUI is disabled and drawing functions are rejected
Return type:boolean

See also

setGUIEnabled()

isInGame() → boolean

Checks if the current client is inside a game.

Returns:true if the client is in a game, and false if it is not.
Return type:boolean
isLatComEnabled() → boolean

Checks the state of latency compensation.

Returns:true if latency compensation is enabled, false if it is disabled.
Return type:boolean

See also

setLatCom()

isMultiplayer() → boolean

Checks if the current client is inside a multiplayer game.

Returns:true if the client is in a multiplayer game, and false if it is a single player game, a replay, or some other state.
Return type:boolean
isPaused() → boolean

Checks if the current game is paused.

While paused, BWAPI.onFrame() will still be called.

Returns:true if the game is paused and false otherwise
Return type:boolean

See also

pauseGame(), resumeGame()

isReplay() → boolean

Checks if the client is watching a replay.

Returns:true if the client is watching a replay and false otherwise
Return type:boolean
issueCommand(units, command) → boolean

Issues a given command to a set of units.

This function automatically splits the set into groups of 12 and issues the same command to each of them. If a unit is not capable of executing the command, then it is simply ignored.

Parameters:
Returns:

true if any one of the units in the Unitset were capable of executing the command, and false if none of the units were capable of executing the command.
Return type:

boolean
isVisible(tileX, tileY) → boolean

Checks if a given tile position is visible to the current player.

Parameters:
  • tileX (int) – The x value of the tile to check.
  • tileY (int) – The y value of the tile to check.
Returns:

boolean identifying the visibility of the tile. If the given tile is visible, then the value is true. If the given tile is concealed by the fog of war, then this value will be false.
Return type:

boolean
isVisible(position) → boolean

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:position (BWAPI.TilePosition) –
Returns:
Return type:boolean
isWalkable(walkX, walkY) → boolean

Checks if the given mini-tile position is walkable.

Parameters:
  • walkX (int) – The x coordinate of the mini-tile, in mini-tile units (8 pixels).
  • walkY (int) – The y coordinate of the mini-tile, in mini-tile units (8 pixels).
Returns:

true if the mini-tile is walkable and false if it is impassable for ground units.
Return type:

boolean

Note

This function only checks if the static terrain is walkable. Its current occupied state is excluded from this check. To see if the space is currently occupied or not, then see getUnitsInRectangle().

isWalkable(position) → boolean

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:position (BWAPI.WalkPosition) –
Returns:
Return type:boolean
leaveGame()

Leaves the current game by surrendering and enters the post-game statistics/score screen.

mapFileName() → string

Retrieves the file name of the currently loaded map.

Returns:Map file name.
Return type:string

See also

mapPathName(), mapName()

mapHash() → string

Calculates the SHA-1 hash of the currently loaded map file.

Returns:string containing SHA-1 hash.
Return type:string

Note

Campaign maps will return a hash of their internal map chunk components (.chk), while standard maps will return a hash of their entire map archive (.scm, .scx).

mapHeight() → int

Retrieves the height of the map in build tile units.

Returns:Height of the map in tiles.
Return type:int

See also

mapWidth()

mapName() → string

Retrieves the title of the currently loaded map.

Returns:Map title.
Return type:string

See also

mapFileName(), mapPathName()

mapPathName() → string

Retrieves the full path name of the currently loaded map.

Returns:Map file name.
Return type:string

See also

mapFileName(), mapName()

mapWidth() → int

Retrieves the width of the map in build tile units.

Returns:Width of the map in tiles.
Return type:int

See also

mapHeight()

neutral() → Player

Retrieves the Player interface object representing the neutral player.

The neutral player owns all the resources and critters on the map by default.

Returns:Player indicating the neutral player.
Return type:BWAPI.Player
observers() → Playerset

Retrieves a set of all players currently observing the game.

An observer is defined typically in a Use Map Settings game type as not having any impact on the game. This means an observer cannot start with any units, and cannot have any active trigger actions that create units for it.

Returns:Playerset containing all currently active observer players
Return type:BWAPI.Playerset
pauseGame()

Pauses the game.

While paused, BWAPI.onFrame() will still be called.

See also

resumeGame()

pingMinimap(x, y)

Pings the minimap at the given position.

Minimap pings are visible to allied players.

Parameters:
  • x (int) – The x coordinate to ping at, in pixels, from the map’s origin (left).
  • y (int) – The y coordinate to ping at, in pixels, from the map’s origin (top).
pingMinimap(pos)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:pos (BWAPI.Position) – The coordinate to ping at, from the map’s origin (top left).
printf(msg)

Prints text to the screen as a notification.

Important

Any formatting needs to be done before the string is passed to the function (e.g. using string.format). See the differences between the C++ and Lua implementations of this function.

Note

This function allows text formatting using BWAPI.Text members. The best way to do this is to use the %c conversion specifier like so: string.format("%cYour string", BWAPI.Text.White)

Parameters:msg (string) – The string to be printed.

Note

That text printed through this function is not seen by other players or in replays.

restartGame()

Restarts the match.

Works the same as if the match was restarted from the in-game menu (F10). This option is only available in single player games.

resumeGame()

Resumes the game from a paused state.

See also

pauseGame()

self() → Player

Retrieves the player object that BWAPI is controlling.

Returns:Player object representing the current player. Returns nil if the current game is a replay.
Return type:BWAPI.Player
Example usage
function BWAPI.onStart()
  if BWAPI.Broodwar:self() then
    BWAPI.Broodwar:sendText("Hello, my name is %s.", BWAPI.Broodwar:self():getName())
  end
end
sendText(msg)

Sends a text message to all other players in the game.

Important

Any formatting needs to be done before the string is passed to the function (e.g. using string.format). See the differences between the C++ and Lua implementations of this function.

Parameters:msg (string) – The string to be sent.

Note

In a single player game this function can be used to execute cheat codes.

See also

sendTextEx(), sendTextToAllies()

sendTextEx(toAllies, msg)

An extended version of Game.sendText() which allows messages to be forwarded to allies.

Parameters:
  • toAllies (boolean) – If this parameter is set to true, then the message is only sent to allied players, otherwise it will be sent to all players.
  • msg (string) – The string to be sent.

See also

Differences Between the C++ and Lua API: Game.sendTextEx, sendTextToAllies(), sendText()

sendTextToAllies(msg)

An extended version of Game.sendText() which always sends messages to allies.

Parameters:msg (string) – The string to be sent.

See also

Differences Between the C++ and Lua API: Game.sendTextEx, sendTextEx(), sendText()

setAlliance(player[, allied = true][, alliedVictory = true]) → boolean

Sets the alliance state of the current player with the target player.

Parameters:
  • player (BWAPI.Player) – The target player to set alliance with.
  • allied (boolean) – (optional) If true, the current player will ally the target player. If false, the current player will make the target player an enemy. This value is true by default.
  • alliedVictory (boolean) – (optional) Sets the state of “allied victory”. If true, the game will end in a victory if all allied players have eliminated their opponents. Otherwise, the game will only end if no other players are remaining in the game. This value is true by default.
Returns:

Returns true if the command was successfully sent to BW, or false otherwise.
Return type:

boolean
setCommandOptimizationLevel(level)

Sets the command optimization level.

Command optimization is a feature in BWAPI that tries to reduce the APM of the bot by grouping or eliminating unnecessary game actions. For example, suppose the bot told 24 Zerglings to Burrow. At command optimization level 0, BWAPI is designed to select each Zergling to burrow individually, which costs 48 actions. With command optimization level 1, it can perform the same behaviour using only 4 actions. The command optimizer also reduces the amount of bytes used for each action if it can express the same action using a different command. For example, Right_Click uses less bytes than Move.

Parameters:level (int) – An integer representation of the aggressiveness for which commands are optimized. A lower level means less optimization, and a higher level means more optimization.
setFrameSkip(frameSkip)

Sets the number of graphical frames for every logical frame.

This allows the game to run more logical frames per graphical frame, increasing the speed at which the game runs.

Parameters:frameSkip (int) – Number of graphical frames per logical frame. If this value is 0 or less, then it will default to 1.

See also

setLocalSpeed()

setGUI(enabled)

Alias for setGUIEnabled().

setGUIEnabled(enabled)

Sets the rendering state of the Starcraft GUI.

This typically gives Starcraft a very low graphical frame rate and disables all drawing functionality in BWAPI.

Parameters:enabled (boolean) – A boolean value that determines the state of the GUI. Passing false to this function will disable the GUI, and true will enable it.
Example Usage
-- Make our bot run thousands of games as fast as possible!
function BWAPI.onStart()
  BWAPI.Broodwar:setLocalSpeed(0)
  BWAPI.Broodwar:setGUIEnabled(false)
end

See also

isGUIEnabled()

setLastError([e = Errors.None]) → boolean

Sets the last error so that future calls to getLastError will return the value that was set.

Parameters:e (BWAPI.Error) – (optional) The error code to set. If omitted, then the last error will be cleared.
Returns:Returns true if the type passed was BWAPI.Errors.None, clearing the last error, or false if any other error type was passed
Return type:boolean

See also

getLastError(), Errors

setLatCom(isEnabled)

Changes the state of latency compensation.

Latency compensation modifies the state of BWAPI‘s representation of units to reflect the implications of issuing a command immediately after the command was performed, instead of waiting consecutive frames for the results. Latency compensation is enabled by default.

Parameters:isEnabled (boolean) – Set whether the latency compensation feature will be enabled (true) or disabled (false).

See also

isLatComEnabled()

setLocalSpeed(speed)

Sets the number of milliseconds Broodwar spends in each frame.

The default values are as follows:

  • Fastest: 42ms/frame
  • Faster: 48ms/frame
  • Fast: 56ms/frame
  • Normal: 67ms/frame
  • Slow: 83ms/frame
  • Slower: 111ms/frame
  • Slowest: 167ms/frame
Parameters:speed (int) – The time spent per frame, in milliseconds. A value of 0 indicates that frames are executed immediately with no delay. Negative values will restore the default value as listed above.

Note

Specifying a value of 0 will not guarantee that logical frames are executed as fast as possible. If that is the intention, use this in combination with setFrameSkip.

See also

setFrameSkip(), getFPS()

setMap(mapFileName) → boolean

Changes the map to the one specified.

Once restarted, the game will load the map that was provided. Changes do not take effect unless the game is restarted.

Parameters:mapFileName (string) – A string containing the path and file name to the desired map.
Returns:Returns true if the function succeeded and has changed the map, or false if the function failed, does not have permission from the tournament module, failed to find the map specified, or received an invalid parameter
Return type:boolean
setRevealAll([reveal = true]) → boolean

Sets the state of the fog of war when watching a replay.

Parameters:reveal (boolean) – (optional) The state of the reveal all flag. If false, all fog of war will be enabled. If true, then the fog of war will be revealed. It is true by default.
Returns:Returns true when successful, or false otherwise.
Return type:boolean
setScreenPosition(x, y)

Moves the top left corner of the viewport to the provided position relative to the map’s origin (top left (0,0)).

Parameters:
  • x (int) – The x coordinate to move the screen to, in pixels.
  • y (int) – The y coordinate to move the screen to, in pixels.

See also

getScreenPosition()

setScreenPosition(pos)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:pos (BWAPI.Position) – The coordinate to move the screen to.
setVision(player[, enabled = true]) → boolean

In a game, this function shares the vision of the current BWAPI player with the target player.

In a replay, this function toggles the visibility of the target player.

Parameters:
  • player (BWAPI.Player) – The target player to toggle vision.
  • enabled (boolean) – (optional) The vision state. If true, and in a game, the current player will enable shared vision with the target player, otherwise it will unshare vision. If in a replay, the vision of the target player will be shown, otherwise the target player will be hidden. This value is true by default.
Returns:

Returns true when successful, or false otherwise.
Return type:

boolean
setTextSize([size = Text.Size.Default])

Sets the size of the text for all calls to drawText following this one.

Parameters:size (BWAPI.Text.Size) – (optional) The size of the text. This value is one of BWAPI.Text.Size. If this value is omitted, then a default value of Text.Size.Default is used.
Example usage
function BWAPI.onFrame()
  -- Centers the name of the player in the upper middle of the screen
  BWAPI.Broodwar:setTextSize(BWAPI.Text.Size.Large)
  BWAPI.Broodwar:drawTextScreen(
    BWAPI.Positions.Origin,
    string.format("%c%c%s",
      BWAPI.Text.Align_Center,
      BWAPI.Text.Green,
      BWAPI.Broodwar:self():getName()
    )
  )
  -- Set text size back to default
  BWAPI.Broodwar:setTextSize()
end

See also

BWAPI.Text.Size

drawText(ctype, x, y, text)

Draws text on the screen at the given coordinates.

Text can be drawn in different colors or formatted using the BWAPI.Text members.

Important

Any formatting needs to be done before the string is passed to the function (e.g. using string.format). See the differences between the C++ and Lua implementations of this function.

Note

This function allows text formatting using BWAPI.Text members. The best way to do this is to use the %c conversion specifier like so: string.format("%cYour string", BWAPI.Text.White)

Parameters:
  • ctype (BWAPI.CoordinateType) – The coordinate type. Indicates the relative position to draw the shape.
  • x (int) – The x coordinate, in pixels, relative to ctype.
  • y (int) – The y coordinate, in pixels, relative to ctype.
  • text (string) – The text to draw.
drawTextMap(x, y, text)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x (int) – The x coordinate, in pixels, relative to the top left of the map.
  • y (int) – The y coordinate, in pixels, relative to the top left of the map.
  • text (string) – The text to draw.
drawTextMap(pos, text)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • pos (BWAPI.Position) – The coordinate, relative to the top left of the map.
  • text (string) – The text to draw.
drawTextMouse(x, y, text)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x (int) – The x coordinate, in pixels, relative to the current mouse position.
  • y (int) – The x coordinate, in pixels, relative to the current mouse position.
  • text (string) – The text to draw.
drawTextMouse(pos, text)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • pos (BWAPI.Position) – The coordinate, relative to the current mouse position.
  • text (string) – The text to draw.
drawTextScreen(x, y, text)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x (int) – The x coordinate, in pixels, relative to the top left of the screen.
  • y (int) – The y coordinate, in pixels, relative to the top left of the screen.
  • text (string) – The text to draw.
drawTextScreen(pos, text)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • pos (BWAPI.Position) – The coordinate, relative to the top left of the screen.
  • text (string) – The text to draw.
drawBox(ctype, left, top, right, bottom, color[, isSolid = false])

Draws a rectangle on the screen with the given color.

Parameters:
  • ctype (BWAPI.CoordinateType) – The coordinate type. Indicates the relative position to draw the shape.
  • left (int) – The x coordinate, in pixels, relative to ctype, of the left edge of the rectangle.
  • top (int) – The y coordinate, in pixels, relative to ctype, of the top edge of the rectangle.
  • right (int) – The x coordinate, in pixels, relative to ctype, of the right edge of the rectangle.
  • bottom (int) – The y coordinate, in pixels, relative to ctype, of the bottom edge of the rectangle.
  • color (BWAPI.Color) – The color of the rectangle.
  • isSolid (boolean) – (optional) If true, then the shape will be filled and drawn as a solid, otherwise it will be drawn as an outline. If omitted, this value will default to false.
drawBoxMap(left, top, right, bottom, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • left (int) –
  • top (int) –
  • right (int) –
  • bottom (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawBoxMap(leftTop, rightBottom, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawBoxMouse(left, top, right, bottom, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • left (int) –
  • top (int) –
  • right (int) –
  • bottom (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawBoxMouse(leftTop, rightBottom, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawBoxScreen(left, top, right, bottom, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • left (int) –
  • top (int) –
  • right (int) –
  • bottom (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawBoxScreen(leftTop, rightBottom, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawTriangle(ctype, ax, ay, bx, by, cx, cy, color[, isSolid = false])

Draws a triangle on the screen with the given color.

Parameters:
  • ctype (BWAPI.CoordinateType) – The coordinate type. Indicates the relative position to draw the shape.
  • ax (int) – The x coordinate, in pixels, relative to ctype, of the first point.
  • ay (int) – The y coordinate, in pixels, relative to ctype, of the first point.
  • bx (int) – The x coordinate, in pixels, relative to ctype, of the second point.
  • by (int) – The y coordinate, in pixels, relative to ctype, of the second point.
  • cx (int) – The x coordinate, in pixels, relative to ctype, of the third point.
  • cy (int) – The y coordinate, in pixels, relative to ctype, of the third point.
  • color (BWAPI.Color) – The color of the triangle.
  • isSolid (boolean) – (optional) If true, then the shape will be filled and drawn as a solid, otherwise it will be drawn as an outline. If omitted, this value will default to false.
drawTriangleMap(ax, ay, bx, by, cx, cy, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • ax (int) –
  • ay (int) –
  • bx (int) –
  • by (int) –
  • cx (int) –
  • cy (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawTriangleMap(a, b, c, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawTriangleMouse(ax, ay, bx, by, cx, cy, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • ax (int) –
  • ay (int) –
  • bx (int) –
  • by (int) –
  • cx (int) –
  • cy (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawTriangleMouse(a, b, c, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawTriangleScreen(ax, ay, bx, by, cx, cy, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • ax (int) –
  • ay (int) –
  • bx (int) –
  • by (int) –
  • cx (int) –
  • cy (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawTriangleScreen(a, b, c, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawCircle(ctype, x, y, radius, color[, isSolid = false])

Draws a circle on the screen with the given color.

Parameters:
  • ctype (BWAPI.CoordinateType) – The coordinate type. Indicates the relative position to draw the shape.
  • x (int) – The x coordinate, in pixels, relative to ctype.
  • y (int) – The y coordinate, in pixels, relative to ctype.
  • radius (int) – The radius of the circle, in pixels.
  • color (BWAPI.Color) – The color of the circle.
  • isSolid (boolean) – (optional) If true, then the shape will be filled and drawn as a solid, otherwise it will be drawn as an outline. If omitted, this value will default to false.
drawCircleMap(x, y, radius, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x (int) –
  • y (int) –
  • radius (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawCircleMap(p, radius, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawCircleMouse(x, y, radius, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x (int) –
  • y (int) –
  • radius (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawCircleMouse(p, radius, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawCircleScreen(x, y, radius, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x (int) –
  • y (int) –
  • radius (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawCircleScreen(p, radius, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawEllipse(ctype, x, y, xrad, yrad, color[, isSolid = false])

Draws an ellipse on the screen with the given color.

Parameters:
  • ctype (BWAPI.CoordinateType) – The coordinate type. Indicates the relative position to draw the shape.
  • x (int) – The x coordinate, in pixels, relative to ctype.
  • y (int) – The y coordinate, in pixels, relative to ctype.
  • xrad (int) – The x radius of the ellipse, in pixels.
  • yrad (int) – The y radius of the ellipse, in pixels.
  • color (BWAPI.Color) – The color of the ellipse.
  • isSolid (boolean) – (optional) If true, then the shape will be filled and drawn as a solid, otherwise it will be drawn as an outline. If omitted, this value will default to false.
drawEllipseMap(x, y, xrad, yrad, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x (int) –
  • y (int) –
  • xrad (int) –
  • yrad (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawEllipseMap(p, xrad, yrad, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawEllipseMouse(x, y, xrad, yrad, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x (int) –
  • y (int) –
  • xrad (int) –
  • yrad (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawEllipseMouse(p, xrad, yrad, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawEllipseScreen(x, y, xrad, yrad, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x (int) –
  • y (int) –
  • xrad (int) –
  • yrad (int) –
  • color (BWAPI.Color) –
  • isSolid (boolean) –
drawEllipseScreen(p, xrad, yrad, color[, isSolid = false])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawDot(ctype, x, y, color)

Draws a dot on the map or screen with a given color.

Parameters:
  • ctype (BWAPI.CoordinateType) – The coordinate type. Indicates the relative position to draw the shape.
  • x (int) – The x coordinate, in pixels, relative to ctype.
  • y (int) – The y coordinate, in pixels, relative to ctype.
  • color (BWAPI.Color) – The color of the dot.
drawDotMap(x, y, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawDotMap(p, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawDotMouse(x, y, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawDotMouse(p, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawDotScreen(x, y, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawDotScreen(p, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawLine(ctype, x1, y1, x2, y2, color)

Draws a line on the map or screen with a given color.

Parameters:
  • ctype (BWAPI.CoordinateType) – The coordinate type. Indicates the relative position to draw the shape.
  • x1 (int) – The starting x coordinate, in pixels, relative to ctype.
  • y1 (int) – The starting y coordinate, in pixels, relative to ctype.
  • x2 (int) – The ending x coordinate, in pixels, relative to ctype.
  • y2 (int) – The ending y coordinate, in pixels, relative to ctype.
  • color (BWAPI.Color) – The color of the line.
drawLineMap(x1, y1, x2, y2, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x1 (int) –
  • y1 (int) –
  • x2 (int) –
  • y2 (int) –
  • color (BWAPI.Color) –
drawLineMap(a, b, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawLineMouse(x1, y1, x2, y2, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x1 (int) –
  • y1 (int) –
  • x2 (int) –
  • y2 (int) –
  • color (BWAPI.Color) –
drawLineMouse(a, b, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
drawLineScreen(x1, y1, x2, y2, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x1 (int) –
  • y1 (int) –
  • x2 (int) –
  • y2 (int) –
  • color (BWAPI.Color) –
drawLineScreen(a, b, color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters: