BWAPI::Game class

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

Contents

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

Public types

using ostream_manipulator = std::ostream&(*)(std::ostream&)
Definition of ostream_manipulator type for convenience.

Constructors, destructors, conversion operators

Game(Client& newClient)

Public functions

void addBullet(const BulletData& bulletData)
auto addEvent(const Event& e) -> const void
void addForce(const ForceData& forceData)
void addRegion(const RegionData& regionData)
void addUnit(const UnitData& unitdata)
auto allies() -> Playerset&
Retrieves a set of all the current player's remaining allies.
auto canBuildHere(TilePosition position, UnitType type, Unit builder = nullptr, bool checkExplored = false) const -> bool
Checks if the given unit type can be built at the given build tile position.
auto canMake(UnitType type, Unit builder = nullptr) const -> bool
Checks all the requirements in order to make a given unit type for the current player.
auto canResearch(TechType type, Unit unit = nullptr, bool checkCanIssueCommandType = true) const -> bool
Checks all the requirements in order to research a given technology type for the current player.
auto canUpgrade(UpgradeType type, Unit unit = nullptr, bool checkCanIssueCommandType = true) const -> bool
Checks all the requirements in order to upgrade a given upgrade type for the current player.
void clearEvents()
auto countdownTimer() const -> int
Returns the remaining countdown time.
auto elapsedTime() const -> int
Retrieves current amount of time in seconds that the game has elapsed.
auto enemies() -> Playerset&
Retrieves a set of all the current player's remaining enemies.
auto enemy() const -> Player
Retrieves the Player interface that represents the enemy player.
void flush()
Flushes the Broodwar stream, printing all text in the stream to the screen.
void flushCommandOptimizer()
auto getAllRegions() const -> const Regionset&
Retrieves the set of all regions on the map.
auto getAllUnits() const -> const Unitset&
Retrieves the set of all accessible units.
auto getAPM(bool includeSelects = false) const -> int
Retrieves the Actions Per Minute (APM) that the bot is producing.
auto getAverageFPS() const -> double
Retrieves the average logical frame rate of the game in frames per second (FPS).
auto getBestUnit(const BestUnitFilter& best, const UnitFilter& pred, Position center = Positions::Origin, int radius = 999999) const -> Unit
Compares all units with pred to determine which of them is the best.
auto getBuildLocation(UnitType type, TilePosition desiredPosition, int maxRange = 64, bool creep = false) const -> TilePosition
Retrieves a basic build position just as the default Computer AI would.
auto getBulletData(BulletID bullet) const -> const BulletData*
auto getBullets() const -> const Bulletset&
Retrieves the set of all accessible bullets.
auto getClientVersion() const -> int since v4.2.0
Retrieves the version that the BWAPI client is using for compatibility checks.
auto getClosestUnit(Position center, const UnitFilter& pred = nullptr, int radius = 999999) const -> Unit
Retrieves the closest unit to center that matches the criteria of the callback pred within an optional radius.
auto getClosestUnitInRectangle(Position center, const UnitFilter& pred = nullptr, int left = 0, int top = 0, int right = 999999, int bottom = 999999) const -> Unit
Retrieves the closest unit to center that matches the criteria of the callback pred within an optional rectangle.
auto getDamageFrom(UnitType fromType, UnitType toType, Player fromPlayer = nullptr, Player toPlayer = nullptr) -> int
Calculates the damage received for a given player.
auto getDamageTo(UnitType toType, UnitType fromType, Player toPlayer = nullptr, Player fromPlayer = nullptr) -> int
Calculates the damage dealt for a given player.
auto getEvents() const -> const std::list<Event>&
Retrieves the list of all unhandled game events.
auto getForce(ForceID forceID) const -> Force
Retrieves the Force interface object associated with a given identifier.
auto getForceData(ForceID force) const -> const ForceData*
auto getForces() const -> const Forceset&
Retrieves the set of all teams/forces.
auto getFPS() const -> int
Retrieves the logical frame rate of the game in frames per second (FPS).
auto getFrameCount() const -> int
Retrieves the number of logical frames since the beginning of the match.
auto getGameType() const -> GameType
Retrieves the GameType of the current game.
auto getGeysers() const -> const Unitset&
Retrieves the set of all accessible Vespene Geysers in the game.
auto getGroundHeight(int tileX, int tileY) const -> int
Returns the ground height at the given tile position.
auto getGroundHeight(TilePosition position) const -> int
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto getInitialData(UnitID unit) const -> const UnitData*
auto getInstanceNumber() const -> int
Retrieves the Starcraft instance number recorded by BWAPI to identify which Starcraft instance an AI module belongs to.
auto getKeyState(Key key) const -> bool
Retrieves the state of the given keyboard key.
auto getLastError() const -> Error
Returns the last error that was set using setLastError.
auto getLastEventTime() const -> int
Retrieves the amount of time (in milliseconds) that has elapsed when running the last AI module callback.
auto getLatencyFrames() const -> int
Retrieves the maximum delay, in number of frames, between a command being issued and the command being executed by Broodwar.
auto getLatencyTime() const -> int
Retrieves the maximum delay, in milliseconds, between a command being issued and the command being executed by Broodwar.
auto getMinerals() const -> const Unitset&
Retrieves the set of all accessible Mineral Fields in the game.
auto getMousePosition() const -> Position
Retrieves the position of the user's mouse on the screen, in Position coordinates.
auto getMouseState(MouseButton button) const -> bool
Retrieves the state of the given mouse button.
auto getNeutralUnits() const -> const Unitset&
Retrieves the set of all accessible neutral units in the game.
auto getNukeDots() const -> const Position::list&
Retrieves the set of all accessible Nuke dots.
auto getPlayer(PlayerID playerID) const -> Player
Retrieves the Player interface object associated with a given identifier.
auto getPlayerData(PlayerID player) const -> const PlayerData*
auto getPlayers() const -> const Playerset&
Retrieves the set of all players in the match.
auto getRandomSeed() const -> unsigned since v4.2.0
Retrieves the initial random seed that was used in this game's creation.
auto getRegion(int regionID) const -> Region
Retrieves the Region interface object associated with a given identifier.
auto getRegionAt(BWAPI::Position position) const -> BWAPI::Region
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto getRegionAt(int x, int y) const -> BWAPI::Region
Retrieves the region at a given position.
auto getRegionData(RegionID region) const -> const RegionData*
auto getRemainingLatencyFrames() const -> int
Retrieves the number of frames it will take before a command sent in the current frame will be executed by the game.
auto getRemainingLatencyTime() const -> int
Retrieves the number of milliseconds it will take before a command sent in the current frame will be executed by Broodwar.
auto getScreenPosition() const -> BWAPI::Position
Retrieves the top left position of the viewport from the top left corner of the map, in pixels.
auto getSelectedUnits() const -> const Unitset&
Retrieves the set of units that are currently selected by the user outside of BWAPI.
auto getStartLocations() const -> const TilePosition::list&
Retrieves the set of all starting locations for the current map.
auto getStaticGeysers() const -> const Unitset&
Retrieves the set of all Vespene Geysers that were available at the beginning of the game.
auto getStaticMinerals() const -> const Unitset&
Retrieves the set of all Mineral Fields that were available at the beginning of the game.
auto getStaticNeutralUnits() const -> const Unitset&
Retrieves the set of all units owned by the neutral player (resources, critters, etc.) that were available at the beginning of the game.
auto getUnit(UnitID unitID) const -> Unit
Retrieves the Unit interface object associated with a given identifier.
auto getUnitData(UnitID unit) const -> const UnitData*
auto getUnits(Player player) const -> const Unitset&
auto getUnitsInRadius(BWAPI::Position center, int radius, const UnitFilter& pred = nullptr) const -> Unitset
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto getUnitsInRadius(int x, int y, int radius, const UnitFilter& pred = nullptr) const -> Unitset
Retrieves the set of accessible units that are within a given radius of a position.
auto getUnitsInRectangle(BWAPI::Position topLeft, BWAPI::Position bottomRight, const UnitFilter& pred = nullptr) const -> Unitset
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto getUnitsInRectangle(int left, int top, int right, int bottom, const UnitFilter& pred = nullptr) const -> Unitset
Retrieves the set of accessible units that are in a given rectangle.
auto getUnitsOnTile(BWAPI::TilePosition tile, const UnitFilter& pred = nullptr) const -> Unitset
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto getUnitsOnTile(int tileX, int tileY, const UnitFilter& pred = nullptr) const -> Unitset
Retrieves the set of accessible units that are on a given build tile.
auto hasCreep(int tileX, int tileY) const -> bool
Checks if the given tile position has Zerg creep on it.
auto hasCreep(TilePosition position) const -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto hasPath(Position source, Position destination) const -> bool
Checks if there is a path from source to destination.
auto hasPower(int tileX, int tileY, int tileWidth, int tileHeight, UnitType unitType = UnitTypes::None) const -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto hasPower(int tileX, int tileY, UnitType unitType = UnitTypes::None) const -> bool
Checks if the given tile position if powered by an owned Protoss Pylon for an optional unit type.
auto hasPower(TilePosition position, int tileWidth, int tileHeight, UnitType unitType = UnitTypes::None) const -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto hasPower(TilePosition position, UnitType unitType = UnitTypes::None) const -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto hasPowerPrecise(int x, int y, UnitType unitType = UnitTypes::None) const -> bool
Checks if the given pixel position is powered by an owned Protoss Pylon for an optional unit type.
auto hasPowerPrecise(Position position, UnitType unitType = UnitTypes::None) const -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void initGameData()
Initializes the members of GameData.
auto isBattleNet() const -> bool
Checks if the client is in a game that was created through the Battle.net multiplayer gaming service.
auto isBuildable(int tileX, int tileY, bool includeBuildings = false) const -> bool
Checks if a given tile position is buildable.
auto isBuildable(TilePosition position, bool includeBuildings = false) const -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto isDebug() const -> bool
Retrieves the debug state of the BWAPI build.
auto isExplored(int tileX, int tileY) const -> bool
Checks if a given tile position has been explored by the player.
auto isExplored(TilePosition position) const -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto isFlagEnabled(int flag) const -> bool
Checks if the state of the given flag is enabled or not.
auto isGUIEnabled() const -> bool
Changes the state of latency compensation.
auto isInGame() const -> bool
Checks if the current client is inside a game.
auto isLatComEnabled() const -> bool
Checks the state of latency compensation.
auto isMultiplayer() const -> bool
Checks if the current client is inside a multiplayer game.
auto isPaused() const -> bool
Checks if the current game is paused.
auto isReplay() const -> bool
Checks if the client is watching a replay.
auto issueCommand(const Unitset& units, UnitCommand command) -> bool
Issues a given command to a set of units.
template<typename T, int Scale>
auto isValid(BWAPI::Point<T, Scale> pos) const -> bool
Checks if this point is within the game's map bounds.
auto isVisible(int tileX, int tileY) const -> bool
Checks if a given tile position is visible to the current player.
auto isVisible(TilePosition position) const -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto isWalkable(BWAPI::WalkPosition position) const -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
auto isWalkable(int walkX, int walkY) const -> bool
Checks if the given mini-tile position is walkable.
void leaveGame()
Leaves the current game by surrendering and enters the post-game statistics/score screen.
template<typename T, int Scale>
auto makeValid(BWAPI::Point<T, Scale>&& pos) const -> BWAPI::Point< T, Scale > -> auto
Checks if this point is within the game's map bounds, if not, then it will set the x and y values to be within map bounds.
template<typename T, int Scale>
auto makeValid(BWAPI::Point<T, Scale>& pos) const -> BWAPI::Point< T, Scale > & -> auto
Checks if this point is within the game's map bounds, if not, then it will set the x and y values to be within map bounds.
auto mapFileName() const -> std::string
Retrieves the file name of the currently loaded map.
auto mapHash() const -> std::string
Calculates the SHA-1 hash of the currently loaded map file.
auto mapHeight() const -> int
Retrieves the height of the map in build tile units.
auto mapName() const -> std::string
Retrieves the title of the currently loaded map.
auto mapPathName() const -> std::string
Retrieves the full path name of the currently loaded map.
auto mapWidth() const -> int
Retrieves the width of the map in build tile units.
auto neutral() const -> Player
Retrieves the Player interface object representing the neutral player.
auto observers() -> Playerset&
Retrieves a set of all players currently observing the game.
auto operator<<(ostream_manipulator fn) -> Game&
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<typename T>
auto operator<<(T const& in) -> Game&
Output stream operator for printing text to Broodwar.
auto operator=(Game&& other) -> Game& deleted
auto operator=(Game const& other) -> Game& deleted
void pauseGame()
Pauses the game.
void 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.
void pingMinimap(int x, int y)
Pings the minimap at the given position.
void printf(const char* format, ...)
Prints text to the screen as a notification.
auto restartGame() -> bool
Restarts the match.
void resumeGame()
Resumes the game from a paused state.
auto self() const -> Player
Retrieves the player object that BWAPI is controlling.
void sendText(const char* format, ...)
Sends a text message to all other players in the game.
void sendTextEx(bool toAllies, const char* format, ...)
An extended version of Game::sendText which allows messages to be forwarded to allies.
auto setAlliance(BWAPI::Player player, bool allied = true, bool alliedVictory = true) -> bool
Sets the alliance state of the current player with the target player.
void setCommandOptimizationLevel(int level)
Sets the command optimization level.
void setFrameSkip(int frameSkip)
Sets the number of graphical frames for every logical frame.
void setGUI(bool enabled)
Sets the rendering state of the Starcraft GUI.
auto setLastError(BWAPI::Error e = Errors::None) const -> bool
Sets the last error so that future calls to getLastError will return the value that was set.
void setLocalSpeed(int speed)
Sets the number of milliseconds Broodwar spends in each frame.
auto setMap(const std::string& mapFileName) -> bool
Changes the map to the one specified.
auto setRevealAll(bool reveal = true) -> bool
Sets the state of the fog of war when watching a replay.
void 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.
void setScreenPosition(int x, int y)
Moves the top left corner of the viewport to the provided position relative to the map's origin (top left (0,0)).
auto setVision(BWAPI::Player player, bool enabled = true) -> bool
In a game, this function sets the vision of the current BWAPI player with the target player.
void update()
void updatePlayer(const PlayerData& playerdata)
void vPrintf(const char* format, va_list args)
Prints text to the screen as a notification.
void vSendText(const char* format, va_list args)
Sends a text message to all other players in the game.
void vSendTextEx(bool toAllies, const char* format, va_list args)
An extended version of Game::sendText which allows messages to be forwarded to allies.

Public variables

Client& client
std::unique_ptr<GameData> gameData

Debugging Members

void setTextSize(Text::Size::Enum size = Text::Size::Default)
Sets the size of the text for all calls to drawText following this one.
void vDrawText(CoordinateType::Enum ctype, int x, int y, const char* format, va_list arg)
Draws text on the screen at the given coordinates.
void 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 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 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 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 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 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 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.
void drawBox(CoordinateType::Enum ctype, int left, int top, int right, int bottom, Color color, bool isSolid = false)
Draws a rectangle on the screen with the given color.
void 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 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 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 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 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 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.
void drawTriangle(CoordinateType::Enum ctype, int ax, int ay, int bx, int by, int cx, int cy, Color color, bool isSolid = false)
Draws a triangle on the screen with the given color.
void 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 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 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 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 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 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.
void drawCircle(CoordinateType::Enum ctype, int x, int y, int radius, Color color, bool isSolid = false)
Draws a circle on the screen with the given color.
void 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 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 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 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 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 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.
void drawEllipse(CoordinateType::Enum ctype, int x, int y, int xrad, int yrad, Color color, bool isSolid = false)
Draws an ellipse on the screen with the given color.
void 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 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 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 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 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 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.
void drawDot(CoordinateType::Enum ctype, int x, int y, Color color)
Draws a dot on the map or screen with a given color.
void 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 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 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 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 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 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.
void drawLine(CoordinateType::Enum ctype, int x1, int y1, int x2, int y2, Color color)
Draws a line on the map or screen with a given color.
void 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 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 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 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 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 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.
void createUnit(Player player, UnitType unitType, int x, int y, int count = 1)
(Single player only) Creates a unit instantly for the given player at any location on the map.
void createUnit(Player player, UnitType unitType, Position position, int count = 1)
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void killUnits(const Unitset& units)
(Single player only) Kills the given units immediately.
void killUnit(Unit unit)
(Single player only) Kills the given unit immediately.
void removeUnits(const Unitset& units)
(Single player only) Removes the given units from the game.
void removeUnit(Unit unit)
(Single player only) Removes the given unit from the game.

Function documentation

Playerset& BWAPI::Game::allies()

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

Returns Playerset containing all allied players.

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

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

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.

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

bool BWAPI::Game::canMake(UnitType type, Unit builder = nullptr) const

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

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.

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

bool BWAPI::Game::canResearch(TechType type, Unit unit = nullptr, bool checkCanIssueCommandType = true) const

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

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.

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

bool BWAPI::Game::canUpgrade(UpgradeType type, Unit unit = nullptr, bool checkCanIssueCommandType = true) const

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

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.

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

int BWAPI::Game::countdownTimer() const

Returns the remaining countdown time.

Returns Integer containing the time (in game seconds) on the countdown timer.

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

Example usage:

if ( (game.getGameType() == BWAPI::GameTypes::Capture_The_Flag ||
      game.getGameType() == BWAPI::GameTypes::Team_Capture_The_Flag) &&
     game.countdownTimer() == 1 )
{
  game.sendText("Try to find my flag!");
}

int BWAPI::Game::elapsedTime() const

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

Returns Time, in seconds, that the game has elapsed as an integer.

Playerset& BWAPI::Game::enemies()

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

Returns Playerset containing all enemy players.

Player BWAPI::Game::enemy() const

Retrieves the Player interface that represents the enemy player.

Returns Player interface representing an enemy player.
nullptr If there is no enemy or the current game is a replay.

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.

const Regionset& BWAPI::Game::getAllRegions() const

Retrieves the set of all regions on the map.

Returns Regionset containing all map regions.

const Unitset& BWAPI::Game::getAllUnits() const

Retrieves the set of all accessible units.

Returns Unitset containing all known units in the game.

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

int BWAPI::Game::getAPM(bool includeSelects = false) const

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.

double BWAPI::Game::getAverageFPS() const

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.

Unit BWAPI::Game::getBestUnit(const BestUnitFilter& best, const UnitFilter& pred, Position center = Positions::Origin, int radius = 999999) const

Compares all units with pred to determine which of them is the best.

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.
nullptr if a suitable unit was not found.

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

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.

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.
Returns A TilePosition containing the location that the structure should be constructed at.
None If a build location could not be found within maxRange.

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

const Bulletset& BWAPI::Game::getBullets() const

Retrieves the set of all accessible bullets.

Returns Bulletset containing all accessible Bullet objects.

int BWAPI::Game::getClientVersion() const since v4.2.0

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

Returns The version number for the BWAPI client.

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.
nullptr If a suitable unit was not found.

Unit BWAPI::Game::getClosestUnitInRectangle(Position center, const UnitFilter& pred = nullptr, int left = 0, int top = 0, int right = 999999, int bottom = 999999) const

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.

int BWAPI::Game::getDamageFrom(UnitType fromType, UnitType toType, Player fromPlayer = nullptr, Player toPlayer = nullptr)

Calculates the damage received for a given player.

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.

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

int BWAPI::Game::getDamageTo(UnitType toType, UnitType fromType, Player toPlayer = nullptr, Player fromPlayer = nullptr)

Calculates the damage dealt for a given player.

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.

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

const std::list<Event>& BWAPI::Game::getEvents() const

Retrieves the list of all unhandled game events.

Returns std::list containing Event objects.

Force BWAPI::Game::getForce(ForceID forceID) const

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.
nullptr if the given identifier is invalid.

const Forceset& BWAPI::Game::getForces() const

Retrieves the set of all teams/forces.

Returns Forceset containing all forces in the game.

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.

int BWAPI::Game::getFPS() const

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

Returns Logical frames per second that the game is currently running at as an integer.

Example:

game.setLocalSpeed(0);

// Log and display the best logical FPS seen in the game
static int bestFPS = 0;
bestFPS = std::max(bestFPS, game.getFPS());
game.drawTextScreen(BWAPI::Positions::Origin, "%cBest: %d GFPS\nCurrent: %d GFPS", BWAPI::Text::White, bestFPS, BWAPI::Broodwar->getFPS());

int BWAPI::Game::getFrameCount() const

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

Returns Number of logical frames that have elapsed since the game started as an integer.

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

GameType BWAPI::Game::getGameType() const

Retrieves the GameType of the current game.

Returns GameType indicating the rules of the match.

const Unitset& BWAPI::Game::getGeysers() const

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

Returns Unitset containing Vespene Geysers

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

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::getInstanceNumber() const

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

Returns An integer value representing the instance number.

The very first instance should return 0.

bool BWAPI::Game::getKeyState(Key key) const

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.
false always if Flag::UserInput is disabled.

Error BWAPI::Game::getLastError() const

Returns the last error that was set using setLastError.

Returns Error type containing the reason for failure.

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

int BWAPI::Game::getLastEventTime() const

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

Returns Time in milliseconds spent in last AI module call.
0 When called from an AI module.

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

int BWAPI::Game::getLatencyFrames() const

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

Returns Difference in frames between commands being sent and executed.

int BWAPI::Game::getLatencyTime() const

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.

const Unitset& BWAPI::Game::getMinerals() const

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

Returns Unitset containing Mineral Fields

Position BWAPI::Game::getMousePosition() const

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

Returns Position indicating the location of the mouse.
None if Flag::UserInput is disabled.

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

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.
false always if Flag::UserInput is disabled.

const Unitset& BWAPI::Game::getNeutralUnits() const

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

Returns Unitset containing all neutral units.

This includes Mineral Fields, Vespene Geysers, and Critters.

const Position::list& BWAPI::Game::getNukeDots() const

Retrieves the set of all accessible Nuke dots.

Returns Set of Positions giving the coordinates of nuke locations.

Player BWAPI::Game::getPlayer(PlayerID playerID) const

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.
nullptr if the given identifier is invalid.

const Playerset& BWAPI::Game::getPlayers() const

Retrieves the set of all players in the match.

Returns Playerset containing all players in the game.

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

unsigned BWAPI::Game::getRandomSeed() const since v4.2.0

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

Returns This game's random seed.

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.

Region BWAPI::Game::getRegion(int regionID) const

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.
nullptr if the given ID is invalid.

BWAPI::Region BWAPI::Game::getRegionAt(int x, int y) const

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.
nullptr if the provided position is not valid (i.e. not within the map bounds).

int BWAPI::Game::getRemainingLatencyFrames() const

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.

int BWAPI::Game::getRemainingLatencyTime() const

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.

BWAPI::Position BWAPI::Game::getScreenPosition() const

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.
None always if Flag::UserInput is disabled.

const Unitset& BWAPI::Game::getSelectedUnits() const

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

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

This function requires that Flag::UserInput be enabled.

const TilePosition::list& BWAPI::Game::getStartLocations() const

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

Returns A TilePosition::list containing all the TilePosition objects that indicate a start location.

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

const Unitset& BWAPI::Game::getStaticGeysers() const

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

Returns Unitset containing static Vespene Geysers

const Unitset& BWAPI::Game::getStaticMinerals() const

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

Returns Unitset containing static Mineral Fields

const Unitset& BWAPI::Game::getStaticNeutralUnits() const

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

Returns Unitset containing static neutral units

Unit BWAPI::Game::getUnit(UnitID unitID) const

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.
nullptr if the given identifier is invalid.

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::getUnitsInRectangle(int left, int top, int right, int bottom, const UnitFilter& pred = nullptr) const

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

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

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.
Returns
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::hasPath(Position source, Position destination) const

Checks if there is a path from source to destination.

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.

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.

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.
Returns
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::hasPowerPrecise(int x, int y, UnitType unitType = UnitTypes::None) const

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

void BWAPI::Game::initGameData()

Initializes the members of GameData.

Prepares the Game object for the start of a new game.

bool BWAPI::Game::isBattleNet() const

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.

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

Checks if a given tile position is buildable.

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.

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

bool BWAPI::Game::isDebug() const

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.

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

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

Parameters
tileX The x tile coordinate to check.
tileY The y tile coordinate to check.
Returns
true If the player has explored the given tile position (partially revealed fog).
false If the tile position was never explored (completely black fog).

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.

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

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

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.

bool BWAPI::Game::isGUIEnabled() const

Changes the state of latency compensation.

Returns
true If the GUI is enabled, and everything is visible
false If the GUI is disabled and drawing functions are rejected

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.

Checks if the GUI is enabled.

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

bool BWAPI::Game::isInGame() const

Checks if the current client is inside a game.

Returns true if the client is in a game, and false if it is not.

bool BWAPI::Game::isLatComEnabled() const

Checks the state of latency compensation.

Returns true if latency compensation is enabled, false if it is disabled.

bool BWAPI::Game::isMultiplayer() const

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.

bool BWAPI::Game::isPaused() const

Checks if the current game is paused.

Returns true if the game is paused and false otherwise

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

bool BWAPI::Game::isReplay() const

Checks if the client is watching a replay.

Returns true if the client is watching a replay and false otherwise

bool BWAPI::Game::issueCommand(const Unitset& units, UnitCommand command)

Issues a given command to a set of units.

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.

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.

template<typename T, int Scale>
bool BWAPI::Game::isValid(BWAPI::Point<T, Scale> pos) const

Checks if this point is within the game's map bounds.

Returns
true If it is a valid position and on the map/playing field.
false If this is not a valid position.

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

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::isWalkable(int walkX, int walkY) const

Checks if the given mini-tile position is walkable.

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.

template<typename T, int Scale>
auto BWAPI::Game::makeValid(BWAPI::Point<T, Scale>&& pos) const -> BWAPI::Point< T, Scale >

Checks if this point is within the game's map bounds, if not, then it will set the x and y values to be within map bounds.

Returns A copy of the Position for convenience

For example, if x is less than 0, then x is set to 0.

template<typename T, int Scale>
auto BWAPI::Game::makeValid(BWAPI::Point<T, Scale>& pos) const -> BWAPI::Point< T, Scale > &

Checks if this point is within the game's map bounds, if not, then it will set the x and y values to be within map bounds.

Returns A reference to pos for convenience

For example, if x is less than 0, then x is set to 0.

std::string BWAPI::Game::mapFileName() const

Retrieves the file name of the currently loaded map.

Returns Map file name as std::string object.

std::string BWAPI::Game::mapHash() const

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

Returns std::string object containing SHA-1 hash.

int BWAPI::Game::mapHeight() const

Retrieves the height of the map in build tile units.

Returns Height of the map in tiles.

std::string BWAPI::Game::mapName() const

Retrieves the title of the currently loaded map.

Returns Map title as std::string object.

std::string BWAPI::Game::mapPathName() const

Retrieves the full path name of the currently loaded map.

Returns Map file name as std::string object.

int BWAPI::Game::mapWidth() const

Retrieves the width of the map in build tile units.

Returns Width of the map in tiles.

Player BWAPI::Game::neutral() const

Retrieves the Player interface object representing the neutral player.

Returns Player interface indicating the neutral player.

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

Playerset& BWAPI::Game::observers()

Retrieves a set of all players currently observing the game.

Returns Playerset containing all currently active observer players

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.

template<typename T>
Game& BWAPI::Game::operator<<(T const& in)

Output stream operator for printing text to Broodwar.

Using this operator invokes Game::printf when a newline character is encountered.

void BWAPI::Game::pauseGame()

Pauses the game.

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

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

Pings the minimap at the given position.

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

Minimap pings are visible to allied players.

void BWAPI::Game::printf(const char* format, ...)

Prints text to the screen as a notification.

Parameters
format Text formatting. See std::printf for more information. Refrain from passing non-constant strings directly in this parameter.

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

bool BWAPI::Game::restartGame()

Restarts the match.

Returns false if not in game, or if isMultiPlayer is true.

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

void BWAPI::Game::resumeGame()

Resumes the game from a paused state.

Player BWAPI::Game::self() const

Retrieves the player object that BWAPI is controlling.

Returns Pointer to Player interface object representing the current player.
nullptr if the current game is a replay.

Example usage

if ( game.self() )
  BWAPI::Broodwar->sendText("Hello, my name is %s.", game.self().getName().c_str());

void BWAPI::Game::sendText(const char* format, ...)

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

Parameters
format Text formatting. See std::printf for more information. Refrain from passing non-constant strings directly in this parameter.

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

void BWAPI::Game::sendTextEx(bool toAllies, const char* format, ...)

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

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.

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

bool BWAPI::Game::setAlliance(BWAPI::Player player, bool allied = true, bool alliedVictory = true)

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.

void BWAPI::Game::setCommandOptimizationLevel(int level)

Sets the command optimization level.

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.

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.

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.

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

Sets the number of graphical frames for every logical frame.

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

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

void BWAPI::Game::setGUI(bool enabled)

Sets the rendering state of the Starcraft GUI.

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.

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

Example Usage:

// Make our bot run thousands of games as fast as possible!
game.setLocalSpeed(0);
game.setGUI(false);

bool BWAPI::Game::setLastError(BWAPI::Error e = Errors::None) const

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

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

Sets the number of milliseconds Broodwar spends in each frame.

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.

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

bool BWAPI::Game::setMap(const std::string& mapFileName)

Changes the map to the one specified.

Parameters
mapFileName A string containing the path and file name to the desired map.
Returns
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.

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

bool BWAPI::Game::setRevealAll(bool reveal = true)

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.

void BWAPI::Game::setScreenPosition(int x, int y)

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

Parameters
x The x coordinate to move the screen to, in pixels.
y The y coordinate to move the screen to, in pixels.

bool BWAPI::Game::setVision(BWAPI::Player player, bool enabled = true)

In a game, this function sets the vision of the current BWAPI player with 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.

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

void BWAPI::Game::vPrintf(const char* format, va_list args)

Prints text to the screen as a notification.

Parameters
format Text formatting. See std::printf for more information. Refrain from passing non-constant strings directly in this parameter.
args The argument list that will be formatted.

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

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

void BWAPI::Game::vSendText(const char* format, va_list args)

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

Parameters
format Text formatting. See std::printf for more information. Refrain from passing non-constant strings directly in this parameter.
args The argument list that will be formatted.

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

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

void BWAPI::Game::vSendTextEx(bool toAllies, const char* format, va_list args)

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

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.
args The argument list that will be formatted.

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

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

void BWAPI::Game::setTextSize(Text::Size::Enum size = Text::Size::Default)

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
}

void BWAPI::Game::vDrawText(CoordinateType::Enum ctype, int x, int y, const char* format, va_list arg)

Draws text on the screen at the given coordinates.

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.

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

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

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::drawTriangle(CoordinateType::Enum ctype, int ax, int ay, int bx, int by, int cx, int cy, Color color, bool isSolid = false)

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::drawCircle(CoordinateType::Enum ctype, int x, int y, int radius, Color color, bool isSolid = false)

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::drawEllipse(CoordinateType::Enum ctype, int x, int y, int xrad, int yrad, Color color, bool isSolid = false)

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::drawDot(CoordinateType::Enum ctype, int x, int y, Color color)

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::drawLine(CoordinateType::Enum ctype, int x1, int y1, int x2, int y2, Color color)

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::createUnit(Player player, UnitType unitType, int x, int y, int count = 1)

(Single player only) Creates a unit instantly for the given player at any location on the map.

Parameters
player The player that will own the new unit.
unitType The type of unit to create.
x The x position to spawn the unit at.
y The y position to spawn the unit at.
count (Optional) The number of units to spawn. Default: 1

void BWAPI::Game::killUnits(const Unitset& units)

(Single player only) Kills the given units immediately.

Parameters
units The set of units that will instantly die. Can be owned by any player.

void BWAPI::Game::killUnit(Unit unit)

(Single player only) Kills the given unit immediately.

Parameters
unit The unit that will instantly die. Can be owned by any player.

void BWAPI::Game::removeUnits(const Unitset& units)

(Single player only) Removes the given units from the game.

Parameters
units The set of units that will instantly be erased from the game. Can be owned by any player.

void BWAPI::Game::removeUnit(Unit unit)

(Single player only) Removes the given unit from the game.

Parameters
unit The unit that will instantly be erased from the game. Can be owned by any player.