BWAPI  4.1.2
An API for interacting with Starcraft: Broodwar (1.16.1)
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Modules
Public Member Functions | Protected Member Functions | List of all members
BWAPI::Game Class Referenceabstract
Inheritance diagram for BWAPI::Game:
Inheritance graph

Public Member Functions

virtual Playersetallies ()=0
 
virtual bool canBuildHere (TilePosition position, UnitType type, Unit builder=nullptr, bool checkExplored=false)=0
 
virtual bool canMake (UnitType type, Unit builder=nullptr) const =0
 
virtual bool canResearch (TechType type, Unit unit=nullptr, bool checkCanIssueCommandType=true)=0
 
virtual bool canUpgrade (UpgradeType type, Unit unit=nullptr, bool checkCanIssueCommandType=true)=0
 
virtual int countdownTimer () const =0
 
virtual int elapsedTime () const =0
 
virtual void enableFlag (int flag)=0
 
virtual Playersetenemies ()=0
 
virtual Player enemy () const =0
 
virtual const RegionsetgetAllRegions () const =0
 
virtual const UnitsetgetAllUnits () const =0
 
virtual int getAPM (bool includeSelects=false) const =0
 
virtual double getAverageFPS () const =0
 
virtual Unit getBestUnit (const BestUnitFilter &best, const UnitFilter &pred, Position center=Positions::Origin, int radius=999999) const =0
 
TilePosition getBuildLocation (UnitType type, TilePosition desiredPosition, int maxRange=64, bool creep=false) const
 
virtual const BulletsetgetBullets () const =0
 
Unit getClosestUnit (Position center, const UnitFilter &pred=nullptr, int radius=999999) const
 
virtual Unit getClosestUnitInRectangle (Position center, const UnitFilter &pred=nullptr, int left=0, int top=0, int right=999999, int bottom=999999) const =0
 
int getDamageFrom (UnitType fromType, UnitType toType, Player fromPlayer=nullptr, Player toPlayer=nullptr) const
 
int getDamageTo (UnitType toType, UnitType fromType, Player toPlayer=nullptr, Player fromPlayer=nullptr) const
 
virtual const std::list< Event > & getEvents () const =0
 
virtual Force getForce (int forceID) const =0
 
virtual const ForcesetgetForces () const =0
 
virtual int getFPS () const =0
 
virtual int getFrameCount () const =0
 
virtual GameType getGameType () const =0
 
virtual const UnitsetgetGeysers () const =0
 
virtual int getGroundHeight (int tileX, int tileY) const =0
 
int getGroundHeight (TilePosition position) const
 
virtual int getInstanceNumber () const =0
 
virtual bool getKeyState (Key key) const =0
 
virtual Error getLastError () const =0
 
virtual int getLastEventTime () const =0
 
virtual int getLatency () const =0
 
virtual int getLatencyFrames () const =0
 
virtual int getLatencyTime () const =0
 
virtual const UnitsetgetMinerals () const =0
 
virtual Position getMousePosition () const =0
 
virtual bool getMouseState (MouseButton button) const =0
 
virtual const UnitsetgetNeutralUnits () const =0
 
virtual const Position::listgetNukeDots () const =0
 
virtual Player getPlayer (int playerID) const =0
 
virtual const PlayersetgetPlayers () const =0
 
virtual Region getRegion (int regionID) const =0
 
virtual BWAPI::Region getRegionAt (int x, int y) const =0
 
BWAPI::Region getRegionAt (BWAPI::Position position) const
 
virtual int getRemainingLatencyFrames () const =0
 
virtual int getRemainingLatencyTime () const =0
 
virtual int getReplayFrameCount () const =0
 
virtual int getRevision () const =0
 
virtual BWAPI::Position getScreenPosition () const =0
 
virtual const UnitsetgetSelectedUnits () const =0
 
virtual const TilePosition::listgetStartLocations () const =0
 
virtual const UnitsetgetStaticGeysers () const =0
 
virtual const UnitsetgetStaticMinerals () const =0
 
virtual const UnitsetgetStaticNeutralUnits () const =0
 
virtual Unit getUnit (int unitID) const =0
 
Unitset getUnitsInRadius (int x, int y, int radius, const UnitFilter &pred=nullptr) const
 
Unitset getUnitsInRadius (BWAPI::Position center, int radius, const UnitFilter &pred=nullptr) const
 
virtual Unitset getUnitsInRectangle (int left, int top, int right, int bottom, const UnitFilter &pred=nullptr) const =0
 
Unitset getUnitsInRectangle (BWAPI::Position topLeft, BWAPI::Position bottomRight, const UnitFilter &pred=nullptr) const
 
Unitset getUnitsOnTile (int tileX, int tileY, const UnitFilter &pred=nullptr) const
 
Unitset getUnitsOnTile (BWAPI::TilePosition tile, const UnitFilter &pred=nullptr) const
 
virtual bool hasCreep (int tileX, int tileY) const =0
 
bool hasCreep (TilePosition position) const
 
bool hasPath (Position source, Position destination) const
 
bool hasPower (int tileX, int tileY, UnitType unitType=UnitTypes::None) const
 
bool hasPower (TilePosition position, UnitType unitType=UnitTypes::None) const
 
bool hasPower (int tileX, int tileY, int tileWidth, int tileHeight, UnitType unitType=UnitTypes::None) const
 
bool hasPower (TilePosition position, int tileWidth, int tileHeight, UnitType unitType=UnitTypes::None) const
 
virtual bool hasPowerPrecise (int x, int y, UnitType unitType=UnitTypes::None) const =0
 
bool hasPowerPrecise (Position position, UnitType unitType=UnitTypes::None) const
 
virtual Unit indexToUnit (int unitIndex) const =0
 
virtual bool isBattleNet () const =0
 
virtual bool isBuildable (int tileX, int tileY, bool includeBuildings=false) const =0
 
bool isBuildable (TilePosition position, bool includeBuildings=false) const
 
virtual bool isDebug () const =0
 
virtual bool isExplored (int tileX, int tileY) const =0
 
bool isExplored (TilePosition position) const
 
virtual bool isFlagEnabled (int flag) const =0
 
virtual bool isGUIEnabled () const =0
 
virtual bool isInGame () const =0
 
virtual bool isLatComEnabled () const =0
 
virtual bool isMultiplayer () const =0
 
virtual bool isPaused () const =0
 
virtual bool isReplay () const =0
 
virtual bool issueCommand (const Unitset &units, UnitCommand command)=0
 
virtual bool isVisible (int tileX, int tileY) const =0
 
bool isVisible (TilePosition position) const
 
virtual bool isWalkable (int walkX, int walkY) const =0
 
bool isWalkable (BWAPI::WalkPosition position) const
 
virtual void leaveGame ()=0
 
virtual std::string mapFileName () const =0
 
virtual std::string mapHash () const =0
 
virtual int mapHeight () const =0
 
virtual std::string mapName () const =0
 
virtual std::string mapPathName () const =0
 
virtual int mapWidth () const =0
 
virtual Player neutral () const =0
 
virtual Playersetobservers ()=0
 
virtual void pauseGame ()=0
 
virtual void pingMinimap (int x, int y)=0
 
void pingMinimap (BWAPI::Position p)
 
void printf (const char *format,...)
 
virtual void restartGame ()=0
 
virtual void resumeGame ()=0
 
virtual Player self () const =0
 
void sendText (const char *format,...)
 
void sendTextEx (bool toAllies, const char *format,...)
 
virtual bool setAlliance (BWAPI::Player player, bool allied=true, bool alliedVictory=true)=0
 
virtual void setCommandOptimizationLevel (int level)=0
 
virtual void setFrameSkip (int frameSkip)=0
 
virtual void setGUI (bool enabled)=0
 
virtual bool setLastError (BWAPI::Error e=Errors::None) const =0
 
virtual void setLatCom (bool isEnabled)=0
 
virtual void setLocalSpeed (int speed)=0
 
virtual bool setMap (const char *mapFileName)=0
 
bool setMap (const std::string &mapFileName)
 
virtual bool setRevealAll (bool reveal=true)=0
 
virtual void setScreenPosition (int x, int y)=0
 
void setScreenPosition (BWAPI::Position p)
 
virtual bool setVision (BWAPI::Player player, bool enabled=true)=0
 
virtual void vPrintf (const char *format, va_list args)=0
 
void vSendText (const char *format, va_list args)
 
virtual void vSendTextEx (bool toAllies, const char *format, va_list args)=0
 
Debugging Members
virtual void setTextSize (Text::Size::Enum size=Text::Size::Default)=0
 
virtual void vDrawText (CoordinateType::Enum ctype, int x, int y, const char *format, va_list arg)=0
 
void drawText (CoordinateType::Enum ctype, int x, int y, const char *format,...)
 
void drawTextMap (int x, int y, const char *format,...)
 
void drawTextMap (Position p, const char *format,...)
 
void drawTextMouse (int x, int y, const char *format,...)
 
void drawTextMouse (Position p, const char *format,...)
 
void drawTextScreen (int x, int y, const char *format,...)
 
void drawTextScreen (Position p, const char *format,...)
 
virtual void drawBox (CoordinateType::Enum ctype, int left, int top, int right, int bottom, Color color, bool isSolid=false)=0
 
void drawBoxMap (int left, int top, int right, int bottom, Color color, bool isSolid=false)
 
void drawBoxMap (Position leftTop, Position rightBottom, Color color, bool isSolid=false)
 
void drawBoxMouse (int left, int top, int right, int bottom, Color color, bool isSolid=false)
 
void drawBoxMouse (Position leftTop, Position rightBottom, Color color, bool isSolid=false)
 
void drawBoxScreen (int left, int top, int right, int bottom, Color color, bool isSolid=false)
 
void drawBoxScreen (Position leftTop, Position rightBottom, Color color, bool isSolid=false)
 
virtual void drawTriangle (CoordinateType::Enum ctype, int ax, int ay, int bx, int by, int cx, int cy, Color color, bool isSolid=false)=0
 
void drawTriangleMap (int ax, int ay, int bx, int by, int cx, int cy, Color color, bool isSolid=false)
 
void drawTriangleMap (Position a, Position b, Position c, Color color, bool isSolid=false)
 
void drawTriangleMouse (int ax, int ay, int bx, int by, int cx, int cy, Color color, bool isSolid=false)
 
void drawTriangleMouse (Position a, Position b, Position c, Color color, bool isSolid=false)
 
void drawTriangleScreen (int ax, int ay, int bx, int by, int cx, int cy, Color color, bool isSolid=false)
 
void drawTriangleScreen (Position a, Position b, Position c, Color color, bool isSolid=false)
 
virtual void drawCircle (CoordinateType::Enum ctype, int x, int y, int radius, Color color, bool isSolid=false)=0
 
void drawCircleMap (int x, int y, int radius, Color color, bool isSolid=false)
 
void drawCircleMap (Position p, int radius, Color color, bool isSolid=false)
 
void drawCircleMouse (int x, int y, int radius, Color color, bool isSolid=false)
 
void drawCircleMouse (Position p, int radius, Color color, bool isSolid=false)
 
void drawCircleScreen (int x, int y, int radius, Color color, bool isSolid=false)
 
void drawCircleScreen (Position p, int radius, Color color, bool isSolid=false)
 
virtual void drawEllipse (CoordinateType::Enum ctype, int x, int y, int xrad, int yrad, Color color, bool isSolid=false)=0
 
void drawEllipseMap (int x, int y, int xrad, int yrad, Color color, bool isSolid=false)
 
void drawEllipseMap (Position p, int xrad, int yrad, Color color, bool isSolid=false)
 
void drawEllipseMouse (int x, int y, int xrad, int yrad, Color color, bool isSolid=false)
 
void drawEllipseMouse (Position p, int xrad, int yrad, Color color, bool isSolid=false)
 
void drawEllipseScreen (int x, int y, int xrad, int yrad, Color color, bool isSolid=false)
 
void drawEllipseScreen (Position p, int xrad, int yrad, Color color, bool isSolid=false)
 
virtual void drawDot (CoordinateType::Enum ctype, int x, int y, Color color)=0
 
void drawDotMap (int x, int y, Color color)
 
void drawDotMap (Position p, Color color)
 
void drawDotMouse (int x, int y, Color color)
 
void drawDotMouse (Position p, Color color)
 
void drawDotScreen (int x, int y, Color color)
 
void drawDotScreen (Position p, Color color)
 
virtual void drawLine (CoordinateType::Enum ctype, int x1, int y1, int x2, int y2, Color color)=0
 
void drawLineMap (int x1, int y1, int x2, int y2, Color color)
 
void drawLineMap (Position a, Position b, Color color)
 
void drawLineMouse (int x1, int y1, int x2, int y2, Color color)
 
void drawLineMouse (Position a, Position b, Color color)
 
void drawLineScreen (int x1, int y1, int x2, int y2, Color color)
 
void drawLineScreen (Position a, Position b, Color color)
 

Protected Member Functions

Gameoperator= (const Game &other)=delete
 
Gameoperator= (Game &&other)=delete
 

Detailed Description

The abstract 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.

Member Function Documentation

Game& BWAPI::Game::operator= ( const Game other)
protecteddelete
Game& BWAPI::Game::operator= ( Game &&  other)
protecteddelete
virtual const Forceset& BWAPI::Game::getForces ( ) const
pure virtual

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.
virtual const Playerset& BWAPI::Game::getPlayers ( ) const
pure virtual

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.
virtual const Unitset& BWAPI::Game::getAllUnits ( ) const
pure virtual

Retrieves the set of all accessible units.

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

Note
Units that are inside refineries are not included in this set.
Returns
Unitset containing all known units in the game.
virtual const Unitset& BWAPI::Game::getMinerals ( ) const
pure virtual

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

Returns
Unitset containing Mineral Fields
virtual const Unitset& BWAPI::Game::getGeysers ( ) const
pure virtual

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

Returns
Unitset containing Vespene Geysers
virtual const Unitset& BWAPI::Game::getNeutralUnits ( ) const
pure virtual

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.
virtual const Unitset& BWAPI::Game::getStaticMinerals ( ) const
pure virtual

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

Note
This set includes resources that have been mined out or are inaccessible.
Returns
Unitset containing static Mineral Fields
virtual const Unitset& BWAPI::Game::getStaticGeysers ( ) const
pure virtual

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

Note
This set includes resources that are inaccessible.
Returns
Unitset containing static Vespene Geysers
virtual const Unitset& BWAPI::Game::getStaticNeutralUnits ( ) const
pure virtual

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

Note
This set includes units that are inaccessible.
Returns
Unitset containing static neutral units
virtual const Bulletset& BWAPI::Game::getBullets ( ) const
pure virtual

Retrieves the set of all accessible bullets.

Returns
Bulletset containing all accessible Bullet objects.
virtual const Position::list& BWAPI::Game::getNukeDots ( ) const
pure virtual

Retrieves the set of all accessible Nuke dots.

Note
Nuke dots are the red dots painted by a Ghost when using the nuclear strike ability.
Returns
Set of Positions giving the coordinates of nuke locations.
virtual const std::list< Event >& BWAPI::Game::getEvents ( ) const
pure virtual

Retrieves the list of all unhandled game events.

Returns
std::list containing Event objects.
virtual Force BWAPI::Game::getForce ( int  forceID) const
pure virtual

Retrieves the Force interface object associated with a given identifier.

Parameters
forceIDThe identifier for the Force object.
Returns
Force interface object mapped to the given forceID.
Return values
nullptrif the given identifier is invalid.
virtual Player BWAPI::Game::getPlayer ( int  playerID) const
pure virtual

Retrieves the Player interface object associated with a given identifier.

Parameters
playerIDThe identifier for the Player object.
Returns
Player interface object mapped to the given playerID.
Return values
nullptrif the given identifier is invalid.
virtual Unit BWAPI::Game::getUnit ( int  unitID) const
pure virtual

Retrieves the Unit interface object associated with a given identifier.

Parameters
unitIDThe identifier for the Unit object.
Returns
Unit interface object mapped to the given unitID.
Return values
nullptrif the given identifier is invalid.
virtual Unit BWAPI::Game::indexToUnit ( int  unitIndex) const
pure virtual

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
unitIndexThe unitIndex to identify the Unit with. A valid index is 0 <= unitIndex & 0x7FF < 1700.
Returns
Unit interface object that matches the given unitIndex.
Return values
nullptrif the given index is invalid.
virtual Region BWAPI::Game::getRegion ( int  regionID) const
pure virtual

Retrieves the Region interface object associated with a given identifier.

Parameters
regionIDThe identifier for the Region object.
Returns
Region interface object mapped to the given regionID.
Return values
nullptrif the given ID is invalid.
virtual GameType BWAPI::Game::getGameType ( ) const
pure virtual

Retrieves the GameType of the current game.

Returns
GameType indicating the rules of the match.
See also
GameType
virtual int BWAPI::Game::getLatency ( ) const
pure virtual

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::Enum.
See also
Latency::Enum
virtual int BWAPI::Game::getFrameCount ( ) const
pure virtual

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.
virtual int BWAPI::Game::getReplayFrameCount ( ) const
pure virtual

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.
virtual int BWAPI::Game::getFPS ( ) const
pure virtual

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

Example:

BWAPI::Broodwar->setLocalSpeed(0);
// Log and display the best logical FPS seen in the game
static int bestFPS = 0;
bestFPS = std::max(bestFPS, BWAPI::Broodwar->getFPS());
BWAPI::Broodwar->drawTextScreen(BWAPI::Positions::Origin, "%cBest: %d GFPS\nCurrent: %d GFPS", BWAPI::Text::White, bestFPS, BWAPI::Broodwar->getFPS());
Returns
Logical frames per second that the game is currently running at as an integer.
See also
getAverageFPS
virtual double BWAPI::Game::getAverageFPS ( ) const
pure virtual

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.
See also
getFPS
virtual Position BWAPI::Game::getMousePosition ( ) const
pure virtual

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

Returns
Position indicating the location of the mouse.
Return values
Positions::Unknownif Flag::UserInput is disabled.
virtual bool BWAPI::Game::getMouseState ( MouseButton  button) const
pure virtual

Retrieves the state of the given mouse button.

Parameters
buttonA 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.
Return values
falsealways if Flag::UserInput is disabled.
See also
MouseButton
virtual bool BWAPI::Game::getKeyState ( Key  key) const
pure virtual

Retrieves the state of the given keyboard key.

Parameters
keyA Key enum member indicating which key on the keyboard to check.
Returns
A bool indicating the state of the given key. true if the key was pressed and false if it was not.
Return values
falsealways if Flag::UserInput is disabled.
See also
Key
virtual BWAPI::Position BWAPI::Game::getScreenPosition ( ) const
pure virtual

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.
Return values
Positions::Unknownalways if Flag::UserInput is disabled.
See also
setScreenPosition
virtual void BWAPI::Game::setScreenPosition ( int  x,
int  y 
)
pure virtual

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

Parameters
xThe x coordinate to move the screen to, in pixels.
yThe y coordinate to move the screen to, in pixels.
See also
getScreenPosition
void BWAPI::Game::setScreenPosition ( BWAPI::Position  p)

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

virtual void BWAPI::Game::pingMinimap ( int  x,
int  y 
)
pure virtual

Pings the minimap at the given position.

Minimap pings are visible to allied players.

Parameters
xThe x coordinate to ping at, in pixels, from the map's origin (left).
yThe y coordinate to ping at, in pixels, from the map's origin (top).
void BWAPI::Game::pingMinimap ( BWAPI::Position  p)

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

virtual bool BWAPI::Game::isFlagEnabled ( int  flag) const
pure virtual

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

Note
Flags may only be enabled at the start of the match during the AIModule::onStart callback.
Parameters
flagThe Flag::Enum entry describing the flag's effects on BWAPI.
Returns
true if the given flag is enabled, false if the flag is disabled.
See also
Flag::Enum
virtual void BWAPI::Game::enableFlag ( int  flag)
pure virtual

Enables the state of a given flag.

Note
Flags may only be enabled at the start of the match during the AIModule::onStart callback.
Parameters
flagThe Flag::Enum entry describing the flag's effects on BWAPI.
See also
Flag::Enum
Unitset BWAPI::Game::getUnitsOnTile ( int  tileX,
int  tileY,
const UnitFilter pred = nullptr 
) const

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

Parameters
tileXThe X position, in tiles.
tileYThe Y position, in tiles.
pred(optional) A function predicate that indicates which units are included in the returned set.
Returns
A Unitset object consisting of all the units that have any part of them on the given build tile.
Unitset BWAPI::Game::getUnitsOnTile ( BWAPI::TilePosition  tile,
const UnitFilter pred = nullptr 
) const

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

virtual Unitset BWAPI::Game::getUnitsInRectangle ( int  left,
int  top,
int  right,
int  bottom,
const UnitFilter pred = nullptr 
) const
pure virtual

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

Parameters
leftThe X coordinate of the left position of the bounding box, in pixels.
topThe Y coordinate of the top position of the bounding box, in pixels.
rightThe X coordinate of the right position of the bounding box, in pixels.
bottomThe Y coordinate of the bottom position of the bounding box, in pixels.
pred(optional) A function predicate that indicates which units are included in the returned set.
Returns
A Unitset object consisting of all the units that have any part of them within the given rectangle bounds.
Unitset BWAPI::Game::getUnitsInRectangle ( BWAPI::Position  topLeft,
BWAPI::Position  bottomRight,
const UnitFilter pred = nullptr 
) const

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

Unitset BWAPI::Game::getUnitsInRadius ( int  x,
int  y,
int  radius,
const UnitFilter pred = nullptr 
) const

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

Parameters
xThe x coordinate of the center, in pixels.
yThe y coordinate of the center, in pixels.
radiusThe radius from the center, in pixels, to include units.
pred(optional) A function predicate that indicates which units are included in the returned set.
Returns
A Unitset object consisting of all the units that have any part of them within the given radius from the center position.
Unitset BWAPI::Game::getUnitsInRadius ( BWAPI::Position  center,
int  radius,
const UnitFilter pred = nullptr 
) const

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

Unit BWAPI::Game::getClosestUnit ( Position  center,
const UnitFilter pred = nullptr,
int  radius = 999999 
) const

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

Parameters
centerThe position to start searching for the closest unit.
pred(optional) The UnitFilter predicate to determine which units should be included. This includes all units by default.
radius(optional) The radius to search in. If omitted, the entire map will be searched.
Returns
The desired unit that is closest to center.
Return values
nullptrIf a suitable unit was not found.
See also
getBestUnit, UnitFilter
virtual Unit BWAPI::Game::getClosestUnitInRectangle ( Position  center,
const UnitFilter pred = nullptr,
int  left = 0,
int  top = 0,
int  right = 999999,
int  bottom = 999999 
) const
pure virtual

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

Parameters
centerThe position to start searching for the closest unit.
pred(optional) The UnitFilter predicate to determine which units should be included. This includes all units by default.
left(optional) The left position of the rectangle. This value is 0 by default.
top(optional) The top position of the rectangle. This value is 0 by default.
right(optional) The right position of the rectangle. This value includes the entire map width by default.
bottom(optional) The bottom position of the rectangle. This value includes the entire map height by default.
See also
UnitFilter
virtual Unit BWAPI::Game::getBestUnit ( const BestUnitFilter best,
const UnitFilter pred,
Position  center = Positions::Origin,
int  radius = 999999 
) const
pure virtual

Compares all units with pred 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
bestA BestUnitFilter that determines which parameters should be considered when calculating which units are better than others.
predA UnitFilter that determines which units to include in calculations.
center(optional) The position to use in the search. If omitted, then the entire map is searched.
radius(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.
Return values
nullptrif a suitable unit was not found.
See also
getClosestUnit, BestUnitFilter, UnitFilter
virtual Error BWAPI::Game::getLastError ( ) const
pure virtual

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.
See also
setLastError, Errors
virtual bool BWAPI::Game::setLastError ( BWAPI::Error  e = Errors::None) const
pure virtual

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

Parameters
e(optional) The error code to set. If omitted, then the last error will be cleared.
Return values
trueIf the type passed was Errors::None, clearing the last error.
falseIf any other error type was passed.
See also
getLastError, Errors
virtual int BWAPI::Game::mapWidth ( ) const
pure virtual

Retrieves the width of the map in build tile units.

Returns
Width of the map in tiles.
See also
mapHeight
virtual int BWAPI::Game::mapHeight ( ) const
pure virtual

Retrieves the height of the map in build tile units.

Returns
Height of the map in tiles.
See also
mapHeight
virtual std::string BWAPI::Game::mapFileName ( ) const
pure virtual

Retrieves the file name of the currently loaded map.

Returns
Map file name as std::string object.
See also
mapPathName, mapName
virtual std::string BWAPI::Game::mapPathName ( ) const
pure virtual

Retrieves the full path name of the currently loaded map.

Returns
Map file name as std::string object.
See also
mapFileName, mapName
virtual std::string BWAPI::Game::mapName ( ) const
pure virtual

Retrieves the title of the currently loaded map.

Returns
Map title as std::string object.
See also
mapFileName, mapPathName
virtual std::string BWAPI::Game::mapHash ( ) const
pure virtual

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

Returns
std::string object containing SHA-1 hash.
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).
virtual bool BWAPI::Game::isWalkable ( int  walkX,
int  walkY 
) const
pure virtual

Checks if the given mini-tile position is walkable.

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 .
Parameters
walkXThe x coordinate of the mini-tile, in mini-tile units (8 pixels).
walkYThe 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.
bool BWAPI::Game::isWalkable ( BWAPI::WalkPosition  position) const

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

virtual int BWAPI::Game::getGroundHeight ( int  tileX,
int  tileY 
) const
pure virtual

Returns the ground height at the given tile position.

Parameters
tileXX position to query, in tiles
tileYY 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
int BWAPI::Game::getGroundHeight ( TilePosition  position) const

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

virtual bool BWAPI::Game::isBuildable ( int  tileX,
int  tileY,
bool  includeBuildings = false 
) const
pure virtual

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
tileXThe x value of the tile to check.
tileYThe y value of the tile to check.
includeBuildings(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.
bool BWAPI::Game::isBuildable ( TilePosition  position,
bool  includeBuildings = false 
) const

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

virtual bool BWAPI::Game::isVisible ( int  tileX,
int  tileY 
) const
pure virtual

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

Parameters
tileXThe x value of the tile to check.
tileYThe 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.
bool BWAPI::Game::isVisible ( TilePosition  position) const

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

virtual bool BWAPI::Game::isExplored ( int  tileX,
int  tileY 
) const
pure virtual

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
tileXThe x tile coordinate to check.
tileYThe y tile coordinate to check.
Return values
trueIf the player has explored the given tile position (partially revealed fog).
falseIf the tile position was never explored (completely black fog).
See also
isVisible
bool BWAPI::Game::isExplored ( TilePosition  position) const

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

virtual bool BWAPI::Game::hasCreep ( int  tileX,
int  tileY 
) const
pure virtual

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

Parameters
tileXThe x tile coordinate to check.
tileYThe y tile coordinate to check.
Return values
trueIf the given tile has creep on it.
falseIf the given tile does not have creep, or if it is concealed by the fog of war.
bool BWAPI::Game::hasCreep ( TilePosition  position) const

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

virtual bool BWAPI::Game::hasPowerPrecise ( int  x,
int  y,
UnitType  unitType = UnitTypes::None 
) const
pure virtual

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

Parameters
xThe x pixel coordinate to check.
yThe y pixel coordinate to check.
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.
Return values
trueif the type at the given position will have power.
falseif the type at the given position will be unpowered.
bool BWAPI::Game::hasPowerPrecise ( Position  position,
UnitType  unitType = UnitTypes::None 
) const

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

bool BWAPI::Game::hasPower ( int  tileX,
int  tileY,
UnitType  unitType = UnitTypes::None 
) const

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

Parameters
tileXThe x tile coordinate to check.
tileYThe y tile coordinate to check.
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.
Return values
trueif the type at the given tile position will receive power.
falseif the type will be unpowered at the given tile position.
bool BWAPI::Game::hasPower ( TilePosition  position,
UnitType  unitType = UnitTypes::None 
) const

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

bool BWAPI::Game::hasPower ( int  tileX,
int  tileY,
int  tileWidth,
int  tileHeight,
UnitType  unitType = UnitTypes::None 
) const

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

bool BWAPI::Game::hasPower ( TilePosition  position,
int  tileWidth,
int  tileHeight,
UnitType  unitType = UnitTypes::None 
) const

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

virtual bool BWAPI::Game::canBuildHere ( TilePosition  position,
UnitType  type,
Unit  builder = nullptr,
bool  checkExplored = false 
)
pure virtual

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.

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.
Parameters
positionIndicates the tile position that the top left corner of the structure is intended to go.
typeThe UnitType to check for.
builder(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(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.
virtual bool BWAPI::Game::canMake ( UnitType  type,
Unit  builder = nullptr 
) const
pure virtual

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
typeThe UnitType to check.
builder(optional) The Unit that will be used to build/train the provided unit type. If this value is nullptr 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.
virtual bool BWAPI::Game::canResearch ( TechType  type,
Unit  unit = nullptr,
bool  checkCanIssueCommandType = true 
)
pure virtual

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
typeThe TechType to check.
unit(optional) The Unit that will be used to research the provided technology type. If this value is nullptr or excluded, then the unit will be excluded in the check.
checkCanIssueCommandType(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.
virtual bool BWAPI::Game::canUpgrade ( UpgradeType  type,
Unit  unit = nullptr,
bool  checkCanIssueCommandType = true 
)
pure virtual

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
typeThe UpgradeType to check.
unit(optional) The Unit that will be used to upgrade the provided upgrade type. If this value is nullptr or excluded, then the unit will be excluded in the check.
checkCanIssueCommandType(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.
virtual const TilePosition::list& BWAPI::Game::getStartLocations ( ) const
pure virtual

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
A TilePosition::list containing all the TilePosition objects that indicate a start location.
See also
PlayerInterface::getStartLocation
void BWAPI::Game::printf ( const char *  format,
  ... 
)

Prints text to the screen as a notification.

This function allows text formatting using Text::Enum members. The behaviour of this function is the same as printf, located in header cstdio.

Note
That text printed through this function is not seen by other players or in replays.
Parameters
formatText formatting. See std::printf for more information. Refrain from passing non-constant strings directly in this parameter.
...The arguments that will be formatted using the given text formatting.
See also
Text::Enum, std::printf
virtual void BWAPI::Game::vPrintf ( const char *  format,
va_list  args 
)
pure virtual

Prints text to the screen as a notification.

This function allows text formatting using Text::Enum members. The behaviour of this function is the same as printf, located in header cstdio.

Note
That text printed through this function is not seen by other players or in replays.
Parameters
formatText formatting. See std::printf for more information. Refrain from passing non-constant strings directly in this parameter.
...The arguments that will be formatted using the given text formatting.
See also
Text::Enum, std::printf

This function is intended to forward an already-existing argument list.

Parameters
argsThe argument list that will be formatted.
See also
printf
void BWAPI::Game::sendText ( const char *  format,
  ... 
)

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

The behaviour of this function is the same as std::printf, located in header cstdio.

Note
In a single player game this function can be used to execute cheat codes.
Parameters
formatText formatting. See std::printf for more information. Refrain from passing non-constant strings directly in this parameter.
See also
sendTextEx, std::printf
void BWAPI::Game::vSendText ( const char *  format,
va_list  args 
)

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

The behaviour of this function is the same as std::printf, located in header cstdio.

Note
In a single player game this function can be used to execute cheat codes.
Parameters
formatText formatting. See std::printf for more information. Refrain from passing non-constant strings directly in this parameter.
See also
sendTextEx, std::printf

This function is intended to forward an already-existing argument list.

Parameters
argsThe argument list that will be formatted.
See also
sendText
void BWAPI::Game::sendTextEx ( bool  toAllies,
const char *  format,
  ... 
)

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

The behaviour of this function is the same as std::printf, located in header cstdio.

Parameters
toAlliesIf this parameter is set to true, then the message is only sent to allied players, otherwise it will be sent to all players.
formatText formatting. See std::printf for more information. Refrain from passing non-constant strings directly in this parameter.
See also
sendText, std::printf
virtual void BWAPI::Game::vSendTextEx ( bool  toAllies,
const char *  format,
va_list  args 
)
pure virtual

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

The behaviour of this function is the same as std::printf, located in header cstdio.

Parameters
toAlliesIf this parameter is set to true, then the message is only sent to allied players, otherwise it will be sent to all players.
formatText formatting. See std::printf for more information. Refrain from passing non-constant strings directly in this parameter.
See also
sendText, std::printf

This function is intended to forward an already-existing argument list.

Parameters
argsThe argument list that will be formatted.
See also
sendTextEx
virtual bool BWAPI::Game::isInGame ( ) const
pure virtual

Checks if the current client is inside a game.

Returns
true if the client is in a game, and false if it is not.
virtual bool BWAPI::Game::isMultiplayer ( ) const
pure virtual

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.
virtual bool BWAPI::Game::isBattleNet ( ) const
pure virtual

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.
virtual bool BWAPI::Game::isPaused ( ) const
pure virtual

Checks if the current game is paused.

While paused, AIModule::onFrame will still be called.

Returns
true if the game is paused and false otherwise
See also
pauseGame, resumeGame
virtual bool BWAPI::Game::isReplay ( ) const
pure virtual

Checks if the client is watching a replay.

Returns
true if the client is watching a replay and false otherwise
virtual void BWAPI::Game::pauseGame ( )
pure virtual

Pauses the game.

While paused, AIModule::onFrame will still be called.

See also
resumeGame
virtual void BWAPI::Game::resumeGame ( )
pure virtual

Resumes the game from a paused state.

See also
pauseGame
virtual void BWAPI::Game::leaveGame ( )
pure virtual

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

virtual void BWAPI::Game::restartGame ( )
pure virtual

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.

virtual void BWAPI::Game::setLocalSpeed ( int  speed)
pure virtual

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
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.
Parameters
speedThe 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.
See also
setFrameSkip, getFPS
virtual bool BWAPI::Game::issueCommand ( const Unitset units,
UnitCommand  command 
)
pure virtual

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
unitsA Unitset containing all the units to issue the command for.
commandA UnitCommand object containing relevant information about the command to be issued. The Unit interface object associated with the command will be ignored.
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.
virtual const Unitset& BWAPI::Game::getSelectedUnits ( ) const
pure virtual

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

This function requires that Flag::UserInput be enabled.

Returns
A Unitset containing the user's selected units. If Flag::UserInput is disabled, then this set is always empty.
See also
enableFlag
virtual Player BWAPI::Game::self ( ) const
pure virtual

Retrieves the player object that BWAPI is controlling.

Returns
Pointer to Player interface object representing the current player.
Return values
nullptrif the current game is a replay.

Example usage

void ExampleAIModule::onStart()
{
if ( BWAPI::Broodwar->self() )
BWAPI::Broodwar->sendText("Hello, my name is %s.", BWAPI::Broodwar->self()->getName().c_str());
}
virtual Player BWAPI::Game::enemy ( ) const
pure virtual

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.
Return values
nullptrIf there is no enemy or the current game is a replay.
See also
enemies
virtual Player BWAPI::Game::neutral ( ) const
pure virtual

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 interface indicating the neutral player.
virtual Playerset& BWAPI::Game::allies ( )
pure virtual

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

Returns
Playerset containing all allied players.
virtual Playerset& BWAPI::Game::enemies ( )
pure virtual

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

Returns
Playerset containing all enemy players.
virtual Playerset& BWAPI::Game::observers ( )
pure virtual

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
virtual void BWAPI::Game::setTextSize ( Text::Size::Enum  size = Text::Size::Default)
pure virtual

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

Parameters
size(optional) The size of the text. This value is one of Text::Size::Enum. If this value is omitted, then a default value of Text::Size::Default is used.

Example usage

void ExampleAIModule::onFrame()
{
// Centers the name of the player in the upper middle of the screen
BWAPI::Broodwar->drawTextScreen(BWAPI::Positions::Origin, "%c%c%s",
BWAPI::Broodwar->self()->getName().c_str() );
BWAPI::Broodwar->setTextSize(); // Set text size back to default
}
See also
Text::Size::Enum
virtual void BWAPI::Game::vDrawText ( CoordinateType::Enum  ctype,
int  x,
int  y,
const char *  format,
va_list  arg 
)
pure virtual

Draws text on the screen at the given coordinates.

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

Parameters
ctypeThe coordinate type. Indicates the relative position to draw the shape.
xThe x coordinate, in pixels, relative to ctype.
yThe y coordinate, in pixels, relative to ctype.
formatThe string formatting portion. This is the same as printf style formatting.
argArglist containing the intermediate list of arguments to format before finally sending the string to Broodwar.
void BWAPI::Game::drawText ( CoordinateType::Enum  ctype,
int  x,
int  y,
const char *  format,
  ... 
)

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

void BWAPI::Game::drawTextMap ( int  x,
int  y,
const char *  format,
  ... 
)

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

void BWAPI::Game::drawTextMap ( Position  p,
const char *  format,
  ... 
)

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

void BWAPI::Game::drawTextMouse ( int  x,
int  y,
const char *  format,
  ... 
)

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

void BWAPI::Game::drawTextMouse ( Position  p,
const char *  format,
  ... 
)

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

void BWAPI::Game::drawTextScreen ( int  x,
int  y,
const char *  format,
  ... 
)

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

void BWAPI::Game::drawTextScreen ( Position  p,
const char *  format,
  ... 
)

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

virtual void BWAPI::Game::drawBox ( CoordinateType::Enum  ctype,
int  left,
int  top,
int  right,
int  bottom,
Color  color,
bool  isSolid = false 
)
pure virtual

Draws a rectangle on the screen with the given color.

Parameters
ctypeThe coordinate type. Indicates the relative position to draw the shape.
leftThe x coordinate, in pixels, relative to ctype, of the left edge of the rectangle.
topThe y coordinate, in pixels, relative to ctype, of the top edge of the rectangle.
rightThe x coordinate, in pixels, relative to ctype, of the right edge of the rectangle.
bottomThe y coordinate, in pixels, relative to ctype, of the bottom edge of the rectangle.
colorThe color of the rectangle.
isSolid(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.
void BWAPI::Game::drawBoxMap ( int  left,
int  top,
int  right,
int  bottom,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawBoxMap ( Position  leftTop,
Position  rightBottom,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawBoxMouse ( int  left,
int  top,
int  right,
int  bottom,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawBoxMouse ( Position  leftTop,
Position  rightBottom,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawBoxScreen ( int  left,
int  top,
int  right,
int  bottom,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawBoxScreen ( Position  leftTop,
Position  rightBottom,
Color  color,
bool  isSolid = false 
)

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

virtual void BWAPI::Game::drawTriangle ( CoordinateType::Enum  ctype,
int  ax,
int  ay,
int  bx,
int  by,
int  cx,
int  cy,
Color  color,
bool  isSolid = false 
)
pure virtual

Draws a triangle on the screen with the given color.

Parameters
ctypeThe coordinate type. Indicates the relative position to draw the shape.
axThe x coordinate, in pixels, relative to ctype, of the first point.
ayThe y coordinate, in pixels, relative to ctype, of the first point.
bxThe x coordinate, in pixels, relative to ctype, of the second point.
byThe y coordinate, in pixels, relative to ctype, of the second point.
cxThe x coordinate, in pixels, relative to ctype, of the third point.
cyThe y coordinate, in pixels, relative to ctype, of the third point.
colorThe color of the triangle.
isSolid(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.
void BWAPI::Game::drawTriangleMap ( int  ax,
int  ay,
int  bx,
int  by,
int  cx,
int  cy,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawTriangleMap ( Position  a,
Position  b,
Position  c,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawTriangleMouse ( int  ax,
int  ay,
int  bx,
int  by,
int  cx,
int  cy,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawTriangleMouse ( Position  a,
Position  b,
Position  c,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawTriangleScreen ( int  ax,
int  ay,
int  bx,
int  by,
int  cx,
int  cy,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawTriangleScreen ( Position  a,
Position  b,
Position  c,
Color  color,
bool  isSolid = false 
)

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

virtual void BWAPI::Game::drawCircle ( CoordinateType::Enum  ctype,
int  x,
int  y,
int  radius,
Color  color,
bool  isSolid = false 
)
pure virtual

Draws a circle on the screen with the given color.

Parameters
ctypeThe coordinate type. Indicates the relative position to draw the shape.
xThe x coordinate, in pixels, relative to ctype.
yThe y coordinate, in pixels, relative to ctype.
radiusThe radius of the circle, in pixels.
colorThe color of the circle.
isSolid(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.
void BWAPI::Game::drawCircleMap ( int  x,
int  y,
int  radius,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawCircleMap ( Position  p,
int  radius,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawCircleMouse ( int  x,
int  y,
int  radius,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawCircleMouse ( Position  p,
int  radius,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawCircleScreen ( int  x,
int  y,
int  radius,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawCircleScreen ( Position  p,
int  radius,
Color  color,
bool  isSolid = false 
)

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

virtual void BWAPI::Game::drawEllipse ( CoordinateType::Enum  ctype,
int  x,
int  y,
int  xrad,
int  yrad,
Color  color,
bool  isSolid = false 
)
pure virtual

Draws an ellipse on the screen with the given color.

Parameters
ctypeThe coordinate type. Indicates the relative position to draw the shape.
xThe x coordinate, in pixels, relative to ctype.
yThe y coordinate, in pixels, relative to ctype.
xradThe x radius of the ellipse, in pixels.
yradThe y radius of the ellipse, in pixels.
colorThe color of the ellipse.
isSolid(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.
void BWAPI::Game::drawEllipseMap ( int  x,
int  y,
int  xrad,
int  yrad,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawEllipseMap ( Position  p,
int  xrad,
int  yrad,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawEllipseMouse ( int  x,
int  y,
int  xrad,
int  yrad,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawEllipseMouse ( Position  p,
int  xrad,
int  yrad,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawEllipseScreen ( int  x,
int  y,
int  xrad,
int  yrad,
Color  color,
bool  isSolid = false 
)

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

void BWAPI::Game::drawEllipseScreen ( Position  p,
int  xrad,
int  yrad,
Color  color,
bool  isSolid = false 
)

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

virtual void BWAPI::Game::drawDot ( CoordinateType::Enum  ctype,
int  x,
int  y,
Color  color 
)
pure virtual

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

Parameters
ctypeThe coordinate type. Indicates the relative position to draw the shape.
xThe x coordinate, in pixels, relative to ctype.
yThe y coordinate, in pixels, relative to ctype.
colorThe color of the dot.
void BWAPI::Game::drawDotMap ( int  x,
int  y,
Color  color 
)

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

void BWAPI::Game::drawDotMap ( Position  p,
Color  color 
)

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

void BWAPI::Game::drawDotMouse ( int  x,
int  y,
Color  color 
)

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

void BWAPI::Game::drawDotMouse ( Position  p,
Color  color 
)

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

void BWAPI::Game::drawDotScreen ( int  x,
int  y,
Color  color 
)

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

void BWAPI::Game::drawDotScreen ( Position  p,
Color  color 
)

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

virtual void BWAPI::Game::drawLine ( CoordinateType::Enum  ctype,
int  x1,
int  y1,
int  x2,
int  y2,
Color  color 
)
pure virtual

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

Parameters
ctypeThe coordinate type. Indicates the relative position to draw the shape.
x1The starting x coordinate, in pixels, relative to ctype.
y1The starting y coordinate, in pixels, relative to ctype.
x2The ending x coordinate, in pixels, relative to ctype.
y2The ending y coordinate, in pixels, relative to ctype.
colorThe color of the line.
void BWAPI::Game::drawLineMap ( int  x1,
int  y1,
int  x2,
int  y2,
Color  color 
)

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

void BWAPI::Game::drawLineMap ( Position  a,
Position  b,
Color  color 
)

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

void BWAPI::Game::drawLineMouse ( int  x1,
int  y1,
int  x2,
int  y2,
Color  color 
)

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

void BWAPI::Game::drawLineMouse ( Position  a,
Position  b,
Color  color 
)

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

void BWAPI::Game::drawLineScreen ( int  x1,
int  y1,
int  x2,
int  y2,
Color  color 
)

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

void BWAPI::Game::drawLineScreen ( Position  a,
Position  b,
Color  color 
)

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

virtual int BWAPI::Game::getLatencyFrames ( ) const
pure virtual

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

Note
In Broodwar, latency is used to keep the game synchronized between players without introducing lag.
Returns
Difference in frames between commands being sent and executed.
See also
getLatencyTime, getRemainingLatencyFrames
virtual int BWAPI::Game::getLatencyTime ( ) const
pure virtual

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.
See also
getLatencyFrames, getRemainingLatencyTime
virtual int BWAPI::Game::getRemainingLatencyFrames ( ) const
pure virtual

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.
See also
getRemainingLatencyTime, getLatencyFrames
virtual int BWAPI::Game::getRemainingLatencyTime ( ) const
pure virtual

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.
See also
getRemainingLatencyFrames, getLatencyTime
virtual int BWAPI::Game::getRevision ( ) const
pure virtual

Retrieves the current revision of BWAPI.

Returns
The revision number of the current BWAPI interface.
Note
This function is considered thread-safe.
virtual bool BWAPI::Game::isDebug ( ) const
pure virtual

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.
Note
This function is considered thread-safe.
virtual bool BWAPI::Game::isLatComEnabled ( ) const
pure virtual

Checks the state of latency compensation.

Returns
true if latency compensation is enabled, false if it is disabled.
See also
setLatCom
virtual void BWAPI::Game::setLatCom ( bool  isEnabled)
pure virtual

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
isEnabledSet whether the latency compensation feature will be enabled (true) or disabled (false).
See also
isLatComEnabled.
virtual bool BWAPI::Game::isGUIEnabled ( ) const
pure virtual

Checks if the GUI is enabled.

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

Return values
trueIf the GUI is enabled, and everything is visible
falseIf the GUI is disabled and drawing functions are rejected
See also
setGUI
virtual void BWAPI::Game::setGUI ( bool  enabled)
pure virtual

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
enabledA 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:

void ExampleAIModule::onStart()
{ // Make our bot run thousands of games as fast as possible!
Broodwar->setLocalSpeed(0);
Broodwar->setGUI(false);
}
See also
isGUIEnabled
virtual int BWAPI::Game::getInstanceNumber ( ) const
pure virtual

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.
Note
This function is considered thread-safe.
virtual int BWAPI::Game::getAPM ( bool  includeSelects = false) const
pure virtual

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

Parameters
includeSelects(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.
virtual bool BWAPI::Game::setMap ( const char *  mapFileName)
pure virtual

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
mapFileNameA string containing the path and file name to the desired map.
Return values
trueif the function succeeded and has changed the map.
falseif the function failed, does not have permission from the tournament module, failed to find the map specified, or received an invalid parameter.
bool BWAPI::Game::setMap ( const std::string mapFileName)

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

virtual void BWAPI::Game::setFrameSkip ( int  frameSkip)
pure virtual

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
frameSkipNumber of graphical frames per logical frame. If this value is 0 or less, then it will default to 1.
See also
setLocalSpeed
bool BWAPI::Game::hasPath ( Position  source,
Position  destination 
) const

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.

Parameters
sourceThe source position.
destinationThe destination position.
Return values
trueif there is a path between the two positions
falseif there is no path
virtual bool BWAPI::Game::setAlliance ( BWAPI::Player  player,
bool  allied = true,
bool  alliedVictory = true 
)
pure virtual

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

Parameters
playerThe target player to set alliance with.
allied(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(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.
virtual bool BWAPI::Game::setVision ( BWAPI::Player  player,
bool  enabled = true 
)
pure virtual

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

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

Parameters
playerThe target player to toggle vision.
enabled(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.
virtual int BWAPI::Game::elapsedTime ( ) const
pure virtual

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

Returns
Time, in seconds, that the game has elapsed as an integer.
virtual void BWAPI::Game::setCommandOptimizationLevel ( int  level)
pure virtual

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
levelAn integer representation of the aggressiveness for which commands are optimized. A lower level means less optimization, and a higher level means more optimization.

The values for level are as follows:

  • 0: No optimization.
  • 1: Some optimization.
    • Is not detected as a hack.
    • Does not alter behaviour.
    • Units performing the following actions are grouped and ordered 12 at a time:
      • Attack_Unit
      • Morph (Larva only)
      • Hold_Position
      • Stop
      • Follow
      • Gather
      • Return_Cargo
      • Repair
      • Burrow
      • Unburrow
      • Cloak
      • Decloak
      • Siege
      • Unsiege
      • Right_Click_Unit
      • Halt_Construction
      • Cancel_Train (Carrier and Reaver only)
      • Cancel_Train_Slot (Carrier and Reaver only)
      • Cancel_Morph (for non-buildings only)
      • Use_Tech
      • Use_Tech_Unit
    • The following order transformations are applied to allow better grouping:
      • Attack_Unit becomes Right_Click_Unit if the target is an enemy
      • Move becomes Right_Click_Position
      • Gather becomes Right_Click_Unit if the target contains resources
      • Set_Rally_Position becomes Right_Click_Position for buildings
      • Set_Rally_Unit becomes Right_Click_Unit for buildings
      • Use_Tech_Unit with Infestation becomes Right_Click_Unit if the target is valid
  • 2: More optimization by grouping structures.
    • Includes the optimizations made by all previous levels.
    • May be detected as a hack by some replay utilities.
    • Does not alter behaviour.
    • Units performing the following actions are grouped and ordered 12 at a time:
      • Attack_Unit (Turrets, Photon Cannons, Sunkens, Spores)
      • Train
      • Morph
      • Set_Rally_Unit
      • Lift
      • Cancel_Construction
      • Cancel_Addon
      • Cancel_Train
      • Cancel_Train_Slot
      • Cancel_Morph
      • Cancel_Research
      • Cancel_Upgrade
  • 3: Extensive optimization
    • Includes the optimizations made by all previous levels.
    • Units may behave or move differently than expected.
    • Units performing the following actions are grouped and ordered 12 at a time:
      • Attack_Move
      • Set_Rally_Position
      • Move
      • Patrol
      • Unload_All
      • Unload_All_Position
      • Right_Click_Position
      • Use_Tech_Position
  • 4: Aggressive optimization
    • Includes the optimizations made by all previous levels.
    • Positions used in commands will be rounded to multiples of 32.
    • High Templar and Dark Templar that merge into Archons will be grouped and may choose a different target to merge with. It will not merge with a target that wasn't included.
virtual int BWAPI::Game::countdownTimer ( ) const
pure virtual

Returns the remaining countdown time.

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

Example usage:

void ExampleAIModule::onStart()
{
// Register a callback that only occurs once when the countdown timer reaches 0
{
BWAPI::Broodwar->registerEvent([](BWAPI::Game*){ BWAPI::Broodwar->sendText("Try to find my flag!"); }, // action
[](BWAPI::Game*){ return BWAPI::Broodwar->countdownTimer() == 0; }, // condition
1); // times to run (once)
}
}
Returns
Integer containing the time (in game seconds) on the countdown timer.
virtual const Regionset& BWAPI::Game::getAllRegions ( ) const
pure virtual

Retrieves the set of all regions on the map.

Returns
Regionset containing all map regions.
virtual BWAPI::Region BWAPI::Game::getRegionAt ( int  x,
int  y 
) const
pure virtual

Retrieves the region at a given position.

Parameters
xThe x coordinate, in pixels.
yThe y coordinate, in pixels.
Returns
Pointer to the Region interface at the given position.
Return values
nullptrif the provided position is not valid (i.e. not within the map bounds).
Note
If the provided position is invalid, the error Errors::Invalid_Parameter is set.
See also
getAllRegions, getRegion
BWAPI::Region BWAPI::Game::getRegionAt ( BWAPI::Position  position) const

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

virtual int BWAPI::Game::getLastEventTime ( ) const
pure virtual

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.

Return values
0When called from an AI module.
Returns
Time in milliseconds spent in last AI module call.
virtual bool BWAPI::Game::setRevealAll ( bool  reveal = true)
pure virtual

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

Parameters
reveal(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.
TilePosition BWAPI::Game::getBuildLocation ( UnitType  type,
TilePosition  desiredPosition,
int  maxRange = 64,
bool  creep = false 
) const

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
typeA valid UnitType representing the unit type to accomodate space for.
desiredPositionA valid TilePosition containing the desired placement position.
maxRange(optional) The maximum distance (in tiles) to build from desiredPosition.
creep(optional) A special boolean value that changes the behaviour of Creep Colony placement.
Return values
TilePositions::InvalidIf a build location could not be found within maxRange.
Returns
A TilePosition containing the location that the structure should be constructed at.
int BWAPI::Game::getDamageFrom ( UnitType  fromType,
UnitType  toType,
Player  fromPlayer = nullptr,
Player  toPlayer = nullptr 
) const

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
fromTypeThe unit type that will be dealing the damage.
toTypeThe unit type that will be receiving the damage.
fromPlayer(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(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.
See also
getDamageTo
int BWAPI::Game::getDamageTo ( UnitType  toType,
UnitType  fromType,
Player  toPlayer = nullptr,
Player  fromPlayer = nullptr 
) const

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.

Note
This function is nearly the same as getDamageFrom. The only difference is that the last parameter is intended to default to Broodwar->self().
Parameters
toTypeThe unit type that will be receiving the damage.
fromTypeThe unit type that will be dealing the damage.
toPlayer(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(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.
See also
getDamageFrom