Inheritance diagram for BWAPI::Game:

Public Member Functions
virtual Playerset &	allies ()=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 Playerset &	enemies ()=0
virtual Player	enemy () const =0
virtual const Regionset &	getAllRegions () const =0
virtual const Unitset &	getAllUnits () 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 Bulletset &	getBullets () const =0
virtual int	getClientVersion () 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 Forceset &	getForces () const =0
virtual int	getFPS () const =0
virtual int	getFrameCount () const =0
virtual GameType	getGameType () const =0
virtual const Unitset &	getGeysers () 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 Unitset &	getMinerals () const =0
virtual Position	getMousePosition () const =0
virtual bool	getMouseState (MouseButton button) const =0
virtual const Unitset &	getNeutralUnits () const =0
virtual const Position::list &	getNukeDots () const =0
virtual Player	getPlayer (int playerID) const =0
virtual const Playerset &	getPlayers () const =0
virtual unsigned	getRandomSeed () 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 Unitset &	getSelectedUnits () const =0
virtual const TilePosition::list &	getStartLocations () const =0
virtual const Unitset &	getStaticGeysers () const =0
virtual const Unitset &	getStaticMinerals () const =0
virtual const Unitset &	getStaticNeutralUnits () 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 Playerset &	observers ()=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
Game &	operator= (const Game &other)=delete
Game &	operator= (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

forceID The identifier for the Force object.

Returns: Force interface object mapped to the given forceID.

Return values

nullptr if 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

playerID The identifier for the Player object.

Returns: Player interface object mapped to the given playerID.

Return values

nullptr if 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

unitID The identifier for the Unit object.

Returns: Unit interface object mapped to the given unitID.

Return values

nullptr if 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

unitIndex The 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

nullptr if 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

regionID The identifier for the Region object.

Returns: Region interface object mapped to the given regionID.

Return values

nullptr if 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
staticint 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::Unknown if Flag::UserInput is disabled.

virtual bool BWAPI::Game::getMouseState (MouseButton button) const pure virtual

Retrieves the state of the given mouse button.

Parameters

button 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.

Return values

false always 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

key	A 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

false always 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::Unknown always 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

x	The x coordinate to move the screen to, in pixels.
y	The 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

x	The x coordinate to ping at, in pixels, from the map's origin (left).
y	The 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

flag	The 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

flag	The 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

tileX	The X position, in tiles.
tileY	The 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

left	The X coordinate of the left position of the bounding box, in pixels.
top	The Y coordinate of the top position of the bounding box, in pixels.
right	The X coordinate of the right position of the bounding box, in pixels.
bottom	The 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

x	The x coordinate of the center, in pixels.
y	The y coordinate of the center, in pixels.
radius	The 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

center	The 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

nullptr If 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

center	The 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

best	A BestUnitFilter that determines which parameters should be considered when calculating which units are better than others.
pred	A 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

nullptr if 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

true	If the type passed was Errors::None, clearing the last error.
false	If 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

walkX	The x coordinate of the mini-tile, in mini-tile units (8 pixels).
walkY	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.

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

tileX	X position to query, in tiles
tileY	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

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

tileX	The x value of the tile to check.
tileY	The 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

tileX	The x value of the tile to check.
tileY	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.

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

tileX	The x tile coordinate to check.
tileY	The y tile coordinate to check.

Return values

true	If the player has explored the given tile position (partially revealed fog).
false	If 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

tileX	The x tile coordinate to check.
tileY	The y tile coordinate to check.

Return values

true	If the given tile has creep on it.
false	If 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

x	The x pixel coordinate to check.
y	The 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

true	if the type at the given position will have power.
false	if 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

tileX	The x tile coordinate to check.
tileY	The 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

true	if the type at the given tile position will receive power.
false	if 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.; If type is UnitTypes::Special_Start_Location, then the area for a resource depot (Command Center, Hatchery, Nexus) is checked as normal, but any potential obstructions (existing structures, creep, units, etc.) are ignored.

Parameters

position	Indicates the tile position that the top left corner of the structure is intended to go.
type	The 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

type	The 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

type	The 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

type	The 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

format	Text 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

format	Text 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

args	The 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

format Text 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

format Text 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

args	The 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

toAllies	If this parameter is set to true, then the message is only sent to allied players, otherwise it will be sent to all players.
format	Text 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

toAllies	If this parameter is set to true, then the message is only sent to allied players, otherwise it will be sent to all players.
format	Text 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

args	The 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

speed 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.

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

units	A Unitset containing all the units to issue the command for.
command	A 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

nullptr if 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

nullptr If 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->setTextSize(BWAPI::Text::Size::Large);
BWAPI::Broodwar->drawTextScreen(BWAPI::Positions::Origin, "%c%c%s",
BWAPI::Text::Align_Center,
BWAPI::Text::Green,
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

ctype	The coordinate type. Indicates the relative position to draw the shape.
x	The x coordinate, in pixels, relative to ctype.
y	The y coordinate, in pixels, relative to ctype.
format	The string formatting portion. This is the same as printf style formatting.
arg	Arglist 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

ctype	The coordinate type. Indicates the relative position to draw the shape.
left	The x coordinate, in pixels, relative to ctype, of the left edge of the rectangle.
top	The y coordinate, in pixels, relative to ctype, of the top edge of the rectangle.
right	The x coordinate, in pixels, relative to ctype, of the right edge of the rectangle.
bottom	The y coordinate, in pixels, relative to ctype, of the bottom edge of the rectangle.
color	The 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

ctype	The coordinate type. Indicates the relative position to draw the shape.
ax	The x coordinate, in pixels, relative to ctype, of the first point.
ay	The y coordinate, in pixels, relative to ctype, of the first point.
bx	The x coordinate, in pixels, relative to ctype, of the second point.
by	The y coordinate, in pixels, relative to ctype, of the second point.
cx	The x coordinate, in pixels, relative to ctype, of the third point.
cy	The y coordinate, in pixels, relative to ctype, of the third point.
color	The 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

ctype	The coordinate type. Indicates the relative position to draw the shape.
x	The x coordinate, in pixels, relative to ctype.
y	The y coordinate, in pixels, relative to ctype.
radius	The radius of the circle, in pixels.
color	The 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

ctype	The coordinate type. Indicates the relative position to draw the shape.
x	The x coordinate, in pixels, relative to ctype.
y	The y coordinate, in pixels, relative to ctype.
xrad	The x radius of the ellipse, in pixels.
yrad	The y radius of the ellipse, in pixels.
color	The 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

ctype	The coordinate type. Indicates the relative position to draw the shape.
x	The x coordinate, in pixels, relative to ctype.
y	The y coordinate, in pixels, relative to ctype.
color	The 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

ctype	The coordinate type. Indicates the relative position to draw the shape.
x1	The starting x coordinate, in pixels, relative to ctype.
y1	The starting y coordinate, in pixels, relative to ctype.
x2	The ending x coordinate, in pixels, relative to ctype.
y2	The ending y coordinate, in pixels, relative to ctype.
color	The 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 int BWAPI::Game::getClientVersion () const pure virtual

Retrieves the version that the BWAPI client is using for compatibility checks.

Returns: The version number for the BWAPI client.

Note: This function is considered thread-safe.

Since: 4.2.0

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

isEnabled Set 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

true	If the GUI is enabled, and everything is visible
false	If 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

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

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

mapFileName A string containing the path and file name to the desired map.

Return values

true	if the function succeeded and has changed the map.
false	if 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

frameSkip Number 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.

Note: If making queries on a unit, it's better to call UnitInterface::hasPath, since it is a more lenient version of this function that accounts for some edge cases.

Parameters

source	The source position.
destination	The destination position.

Returns: true if there is a path between the two positions, and false if there is not.

See also: UnitInterface::hasPath

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

player	The 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

player	The 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

level An 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
if ( BWAPI::Broodwar->getGameType() == BWAPI::GameTypes::Capture_The_Flag ||
BWAPI::Broodwar->getGameType() == BWAPI::GameTypes::Team_Capture_The_Flag )
 {
BWAPI::Broodwar->registerEvent([](BWAPI::Game*){ BWAPI::Broodwar->sendText("Try to find my flag!"); }, // action
 [](BWAPI::Game*){ returnBWAPI::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

x	The x coordinate, in pixels.
y	The y coordinate, in pixels.

Returns: Pointer to the Region interface at the given position.

Return values

nullptr if 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

0	When 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

type	A valid UnitType representing the unit type to accomodate space for.
desiredPosition	A 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::Invalid If 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

fromType	The unit type that will be dealing the damage.
toType	The 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

toType	The unit type that will be receiving the damage.
fromType	The 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

virtual unsigned BWAPI::Game::getRandomSeed () const pure virtual

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.

Since: 4.2.0

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation