BWAPI::Player class

The Player represents a unique controller in the game.

Contents

Each player in a match will have his or her own player instance. There is also a neutral player which owns all the neutral units (such as mineral patches and vespene geysers).

Base classes

template<typename Interface, typename Data>
struct InterfaceDataWrapper<Player, PlayerData>

Public functions

auto allUnitCount(UnitType unit = UnitTypes::AllUnits) const -> int
Retrieves the total number of units that the player has.
auto armor(UnitType unit) const -> int
Calculates the armor that a given unit type will have, including upgrades.
auto completedUnitCount(UnitType unit = UnitTypes::AllUnits) const -> int
Retrieves the number of completed units that the player has.
auto damage(WeaponType wpn) const -> int
Calculates the damage that a given weapon type can deal, including upgrades.
auto deadUnitCount(UnitType unit = UnitTypes::AllUnits) const -> int
Retrieves the number units that have died for this player.
auto gas() const -> int
Retrieves the current amount of vespene gas that this player has.
auto gatheredGas() const -> int
Retrieves the cumulative amount of vespene gas that this player has gathered since the beginning of the game, including the amount that the player starts the game with (if any).
auto gatheredMinerals() const -> int
Retrieves the cumulative amount of minerals/ore that this player has gathered since the beginning of the game, including the amount that the player starts the game with (if any).
auto getBuildingScore() const -> int
Retrieves the total building score, as seen in the end-game score screen.
auto getColor() const -> BWAPI::Color
Retrieves the color value of the current player.
auto getCustomScore() const -> int
Retrieves the player's custom score.
auto getForce() const -> Force
Retrieves the player's force.
auto getKillScore() const -> int
Retrieves the total kill score, as seen in the end-game score screen.
auto getMaxUpgradeLevel(UpgradeType upgrade) const -> int
Retrieves the maximum upgrades available specific to the player.
auto getName() const -> std::string_view
Retrieves the name of the player.
auto getRace() const -> Race constexpr
Retrieves the race of the player.
auto getRazingScore() const -> int
Retrieves the total razing score, as seen in the end-game score screen.
auto getStartLocation() const -> TilePosition
Retrieve's the player's starting location.
auto getTextColor() const -> char
Retrieves the control code character that changes the color of text messages to represent this player.
auto getType() const -> PlayerType constexpr
Retrieves the player's controller type.
auto getUnits() const -> const Unitset&
Retrieves the set of all units that the player owns.
auto getUnitScore() const -> int
Retrieves the total unit score, as seen in the end-game score screen.
auto getUpgradeLevel(UpgradeType upgrade) const -> int
Retrieves the current upgrade level that the player has attained for a given upgrade type.
auto hasResearched(TechType tech) const -> bool
Checks if the player has already researched a given technology.
auto hasUnitTypeRequirement(UnitType unit, int amount = 1) const -> bool since v4.1.2
Verifies that this player satisfies a unit type requirement.
auto incompleteUnitCount(UnitType unit = UnitTypes::AllUnits) const -> int
Retrieves the number of incomplete units that the player has.
auto isAlly(Player otherPlayer) const -> bool constexpr
Checks if this player is allied to the specified player.
auto isDefeated() const -> bool
Checks if the player has been defeated.
auto isEnemy(Player otherPlayer) const -> bool
Checks if this player is unallied to the specified player.
auto isNeutral() const -> bool
Checks if this player is the neutral player.
auto isObserver() const -> bool
Checks if the player is an observer player, typically in a Use Map Settings observer game.
auto isResearchAvailable(TechType tech) const -> bool
Checks if a technology can be researched by the player.
auto isResearching(TechType tech) const -> bool
Checks if the player is researching a given technology type.
auto isUnitAvailable(UnitType unit) const -> bool
Checks if a unit type can be created by the player.
auto isUpgrading(UpgradeType upgrade) const -> bool
Checks if the player is upgrading a given upgrade type.
auto isVictorious() const -> bool
Checks if the player has achieved victory.
auto killedUnitCount(UnitType unit = UnitTypes::AllUnits) const -> int
Retrieves the number units that the player has killed.
auto leftGame() const -> bool
Checks if the player has left the game.
auto maxEnergy(UnitType unit) const -> int
Retrieves the maximum amount of energy that a unit type will have, taking the player's energy upgrades into consideration.
auto minerals() const -> int
Retrieves the current amount of minerals/ore that this player has.
auto refundedGas() const -> int
Retrieves the cumulative amount of vespene gas that this player has gained from refunding (cancelling) units and structures.
auto refundedMinerals() const -> int
Retrieves the cumulative amount of minerals/ore that this player has gained from refunding (cancelling) units and structures.
auto repairedGas() const -> int
Retrieves the cumulative amount of vespene gas that this player has spent on repairing units since the beginning of the game.
auto repairedMinerals() const -> int
Retrieves the cumulative amount of minerals/ore that this player has spent on repairing units since the beginning of the game.
auto sightRange(UnitType unit) const -> int
Retrieves the sight range of a unit type, taking the player's sight range upgrades into consideration.
auto spentGas() const -> int
Retrieves the cumulative amount of vespene gas that this player has spent, excluding repairs.
auto spentMinerals() const -> int
Retrieves the cumulative amount of minerals/ore that this player has spent, excluding repairs.
auto supplyTotal(Race race = Races::None) const -> int
Retrieves the total amount of supply the player has available for unit control.
auto supplyUsed(Race race = Races::None) const -> int
Retrieves the current amount of supply that the player is using for unit control.
auto topSpeed(UnitType unit) const -> double
Retrieves the top speed of a unit type, taking the player's speed upgrades into consideration.
auto visibleUnitCount(UnitType unit = UnitTypes::AllUnits) const -> int
Retrieves the total number of strictly visible units that the player has, even if information on the player is unrestricted.
auto weaponDamageCooldown(UnitType unit) const -> int
Retrieves the ground weapon cooldown of a unit type, taking the player's attack speed upgrades into consideration.
auto weaponMaxRange(WeaponType weapon) const -> int
Retrieves the maximum weapon range of a weapon type, taking the player's weapon upgrades into consideration.

Function documentation

int BWAPI::Player::allUnitCount(UnitType unit = UnitTypes::AllUnits) const

Retrieves the total number of units that the player has.

Parameters
unit (optional) The unit type to query. UnitType macros are accepted. If this parameter is omitted, then it will use UnitTypes::AllUnits by default.
Returns The total number of units of the given type that the player owns.

If the information about the player is limited, then this function will only return the number of visible units.

int BWAPI::Player::armor(UnitType unit) const

Calculates the armor that a given unit type will have, including upgrades.

Parameters
unit The unit type to calculate armor for, using the current player's upgrades.
Returns The amount of armor that the unit will have with the player's upgrades.

int BWAPI::Player::completedUnitCount(UnitType unit = UnitTypes::AllUnits) const

Retrieves the number of completed units that the player has.

Parameters
unit (optional) The unit type to query. UnitType macros are accepted. If this parameter is omitted, then it will use UnitTypes::AllUnits by default.
Returns The number of completed units of the given type that the player owns.

If the information about the player is limited, then this function will only return the number of visible completed units.

Example usage:

bool obtainNextUpgrade(BWAPI::UpgradeType upgType)
{
  BWAPI::Player self = game.self();
  if (!self) return false;

  int maxLvl      = self.getMaxUpgradeLevel(upgType);
  int currentLvl  = self.getUpgradeLevel(upgType);
  if ( !self.isUpgrading(upgType) && currentLvl < maxLvl &&
        self.completedUnitCount(upgType.whatsRequired(currentLvl + 1)) > 0 &&
        self.completedUnitCount(upgType.whatUpgrades()) > 0 )
    return self.getUnits().upgrade(upgType);
  return false;
}

int BWAPI::Player::damage(WeaponType wpn) const

Calculates the damage that a given weapon type can deal, including upgrades.

Parameters
wpn The weapon type to calculate for.
Returns The amount of damage that the weapon deals with this player's upgrades.

int BWAPI::Player::deadUnitCount(UnitType unit = UnitTypes::AllUnits) const

Retrieves the number units that have died for this player.

Parameters
unit (optional) The unit type to query. UnitType macros are accepted. If this parameter is omitted, then it will use UnitTypes::AllUnits by default.
Returns The total number of units that have died throughout the game.

int BWAPI::Player::gas() const

Retrieves the current amount of vespene gas that this player has.

Returns Amount of gas that the player currently has for spending.

int BWAPI::Player::gatheredGas() const

Retrieves the cumulative amount of vespene gas that this player has gathered since the beginning of the game, including the amount that the player starts the game with (if any).

Returns Cumulative amount of gas that the player has gathered.

int BWAPI::Player::gatheredMinerals() const

Retrieves the cumulative amount of minerals/ore that this player has gathered since the beginning of the game, including the amount that the player starts the game with (if any).

Returns Cumulative amount of minerals that the player has gathered.

int BWAPI::Player::getBuildingScore() const

Retrieves the total building score, as seen in the end-game score screen.

Returns The player's building score.

BWAPI::Color BWAPI::Player::getColor() const

Retrieves the color value of the current player.

Returns Color object that represents the color of the current player.

int BWAPI::Player::getCustomScore() const

Retrieves the player's custom score.

Returns The player's custom score.

This score is used in Use Map Settings game types.

Force BWAPI::Player::getForce() const

Retrieves the player's force.

Returns The Force object that the player is part of.

A force is the team that the player is playing on.

int BWAPI::Player::getKillScore() const

Retrieves the total kill score, as seen in the end-game score screen.

Returns The player's kill score.

int BWAPI::Player::getMaxUpgradeLevel(UpgradeType upgrade) const

Retrieves the maximum upgrades available specific to the player.

Parameters
upgrade The UpgradeType to retrieve the maximum upgrade level for.
Returns Maximum upgrade level of the given upgrade type.

This value is only different from UpgradeType::maxRepeats in Use Map Settings games.

Example usage:

bool obtainNextUpgrade(BWAPI::UpgradeType upgType)
{
  BWAPI::Player self = game.self();
  if (!self) return false;

  int maxLvl      = self.getMaxUpgradeLevel(upgType);
  int currentLvl  = self.getUpgradeLevel(upgType);
  if ( !self.isUpgrading(upgType) && currentLvl < maxLvl &&
        self.completedUnitCount(upgType.whatsRequired(currentLvl + 1)) > 0 &&
        self.completedUnitCount(upgType.whatUpgrades()) > 0 )
    return self.getUnits().upgrade(upgType);
  return false;
}

std::string_view BWAPI::Player::getName() const

Retrieves the name of the player.

Returns A std::string object containing the player's name.

Example usage:

BWAPI::Player myEnemy = game.enemy();
if ( myEnemy )   // Make sure there is an enemy!
  game.sendText("Prepare to be crushed, %s!", myEnemy.getName().c_str());

Race BWAPI::Player::getRace() const constexpr

Retrieves the race of the player.

Returns The Race that the player is using.
None If the player chose Races::Random when the game started and they have not been seen.

This allows you to change strategies against different races, or generalize some commands for yourself.

Example usage:

if ( game.enemy() )
{
  BWAPI::Race enemyRace = game.enemy().getRace();
  if ( enemyRace == Races::Zerg )
    game.sendText("Do you really think you can beat me with a zergling rush?");
}

int BWAPI::Player::getRazingScore() const

Retrieves the total razing score, as seen in the end-game score screen.

Returns The player's razing score.

TilePosition BWAPI::Player::getStartLocation() const

Retrieve's the player's starting location.

Returns A TilePosition containing the position of the start location.
None if the player does not have a start location.
None if an error occured while trying to retrieve the start location.

char BWAPI::Player::getTextColor() const

Retrieves the control code character that changes the color of text messages to represent this player.

Returns character code to use for text in Broodwar.

PlayerType BWAPI::Player::getType() const constexpr

Retrieves the player's controller type.

Returns The PlayerType that identifies who is controlling a player.

This allows you to distinguish betweeen computer and human players.

if ( game.enemy() )
{
  if ( game.enemy()->getType() == PlayerTypes::Computer )
    game << "Looks like something I can abuse!" << std::endl;
}

const Unitset& BWAPI::Player::getUnits() const

Retrieves the set of all units that the player owns.

Returns Reference to a Unitset containing the units.

This also includes incomplete units.

Example usage:

for ( BWAPI::Unit u : game.self().getUnits() )
{
  // Do something with your units
}

int BWAPI::Player::getUnitScore() const

Retrieves the total unit score, as seen in the end-game score screen.

Returns The player's unit score.

int BWAPI::Player::getUpgradeLevel(UpgradeType upgrade) const

Retrieves the current upgrade level that the player has attained for a given upgrade type.

Parameters
upgrade The UpgradeType to query.
Returns The number of levels that the upgrade has been upgraded for this player.

Example usage:

bool obtainNextUpgrade(BWAPI::UpgradeType upgType)
{
  BWAPI::Player self = game.self();
  if (!self) return false;

  int maxLvl      = self.getMaxUpgradeLevel(upgType);
  int currentLvl  = self.getUpgradeLevel(upgType);
  if ( !self.isUpgrading(upgType) && currentLvl < maxLvl &&
        self.completedUnitCount(upgType.whatsRequired(currentLvl+1)) > 0 &&
        self.completedUnitCount(upgType.whatUpgrades()) > 0 )
    return self.getUnits().upgrade(upgType);
  return false;
}

bool BWAPI::Player::hasResearched(TechType tech) const

Checks if the player has already researched a given technology.

Parameters
tech The TechType to query.
Returns true if the player has obtained the given tech, or false if they have not

bool BWAPI::Player::hasUnitTypeRequirement(UnitType unit, int amount = 1) const since v4.1.2

Verifies that this player satisfies a unit type requirement.

Parameters
unit The UnitType to check.
amount (optional) The amount of units that are required.
Returns true if the unit type requirements are met, and false otherwise.

This verifies complex type requirements involving morphable Zerg structures. For example, if something requires a Spire, but the player has (or is in the process of morphing) a Greater Spire, this function will identify the requirement. It is simply a convenience function that performs all of the requirement checks.

int BWAPI::Player::incompleteUnitCount(UnitType unit = UnitTypes::AllUnits) const

Retrieves the number of incomplete units that the player has.

Parameters
unit (optional) The unit type to query. UnitType macros are accepted. If this parameter is omitted, then it will use UnitTypes::AllUnits by default.
Returns The number of incomplete units of the given type that the player owns.

If the information about the player is limited, then this function will only return the number of visible incomplete units.

bool BWAPI::Player::isAlly(Player otherPlayer) const constexpr

Checks if this player is allied to the specified player.

Parameters
otherPlayer The player to check alliance with.
Returns
true if this player is allied with player .
false if this player is not allied with player.

bool BWAPI::Player::isDefeated() const

Checks if the player has been defeated.

Returns true if the player is defeated, otherwise false

bool BWAPI::Player::isEnemy(Player otherPlayer) const

Checks if this player is unallied to the specified player.

Parameters
otherPlayer The player to check alliance with.
Returns
true if this player is allied with player .
false if this player is not allied with player .

bool BWAPI::Player::isNeutral() const

Checks if this player is the neutral player.

Returns
true if this player is the neutral player.
false if this player is any other player.

bool BWAPI::Player::isObserver() const

Checks if the player is an observer player, typically in a Use Map Settings observer game.

Returns true if the player is observing, or false if the player is capable of playing in the game.

An observer player does not participate in the game.

bool BWAPI::Player::isResearchAvailable(TechType tech) const

Checks if a technology can be researched by the player.

Parameters
tech The TechType to query.
Returns true if the tech type is available to the player for research.

Certain technologies may be disabled in Use Map Settings game types.

bool BWAPI::Player::isResearching(TechType tech) const

Checks if the player is researching a given technology type.

Parameters
tech The TechType to query.
Returns true if the player is currently researching the tech, or false otherwise

bool BWAPI::Player::isUnitAvailable(UnitType unit) const

Checks if a unit type can be created by the player.

Parameters
unit The UnitType to check.
Returns true if the unit type is available to the player.

Certain unit types may be disabled in Use Map Settings game types.

bool BWAPI::Player::isUpgrading(UpgradeType upgrade) const

Checks if the player is upgrading a given upgrade type.

Parameters
upgrade The upgrade type to query.
Returns true if the player is currently upgrading the given upgrade, false otherwise

Example usage:

bool obtainNextUpgrade(BWAPI::UpgradeType upgType)
{
  BWAPI::Player self = game.self();
  if (!self) return false;

  int maxLvl      = self.getMaxUpgradeLevel(upgType);
  int currentLvl  = self.getUpgradeLevel(upgType);
  if ( !self.isUpgrading(upgType) && currentLvl < maxLvl &&
        self.completedUnitCount(upgType.whatsRequired(currentLvl + 1)) > 0 &&
        self.completedUnitCount(upgType.whatUpgrades()) > 0 )
    return self.getUnits().upgrade(upgType);
  return false;
}

bool BWAPI::Player::isVictorious() const

Checks if the player has achieved victory.

Returns true if this player has achieved victory, otherwise false

int BWAPI::Player::killedUnitCount(UnitType unit = UnitTypes::AllUnits) const

Retrieves the number units that the player has killed.

Parameters
unit (optional) The unit type to query. UnitType macros are accepted. If this parameter is omitted, then it will use UnitTypes::AllUnits by default.
Returns The total number of units that the player has killed throughout the game.

bool BWAPI::Player::leftGame() const

Checks if the player has left the game.

Returns true if the player has left the game, otherwise false

int BWAPI::Player::maxEnergy(UnitType unit) const

Retrieves the maximum amount of energy that a unit type will have, taking the player's energy upgrades into consideration.

Parameters
unit The UnitType to retrieve the maximum energy for.
Returns Maximum amount of energy that the given unit type can have.

int BWAPI::Player::minerals() const

Retrieves the current amount of minerals/ore that this player has.

Returns Amount of minerals that the player currently has for spending.

int BWAPI::Player::refundedGas() const

Retrieves the cumulative amount of vespene gas that this player has gained from refunding (cancelling) units and structures.

Returns Cumulative amount of gas that the player has received from refunds.

int BWAPI::Player::refundedMinerals() const

Retrieves the cumulative amount of minerals/ore that this player has gained from refunding (cancelling) units and structures.

Returns Cumulative amount of minerals that the player has received from refunds.

int BWAPI::Player::repairedGas() const

Retrieves the cumulative amount of vespene gas that this player has spent on repairing units since the beginning of the game.

Returns Cumulative amount of gas that the player has spent repairing.

This function only applies to Terran players.

int BWAPI::Player::repairedMinerals() const

Retrieves the cumulative amount of minerals/ore that this player has spent on repairing units since the beginning of the game.

Returns Cumulative amount of minerals that the player has spent repairing.

This function only applies to Terran players.

int BWAPI::Player::sightRange(UnitType unit) const

Retrieves the sight range of a unit type, taking the player's sight range upgrades into consideration.

Parameters
unit The UnitType to retrieve the sight range for.
Returns Sight range of the provided unit type for this player.

int BWAPI::Player::spentGas() const

Retrieves the cumulative amount of vespene gas that this player has spent, excluding repairs.

Returns Cumulative amount of gas that the player has spent.

int BWAPI::Player::spentMinerals() const

Retrieves the cumulative amount of minerals/ore that this player has spent, excluding repairs.

Returns Cumulative amount of minerals that the player has spent.

int BWAPI::Player::supplyTotal(Race race = Races::None) const

Retrieves the total amount of supply the player has available for unit control.

Parameters
race (optional) The race to query the total supply for. If this is omitted, then the player's current race will be used.
Returns The total supply available for this player and the given race.

Example usage:

if ( game.self().supplyUsed() + 8 >= game.self().supplyTotal() )
{
  // Construct pylons, supply depots, or overlords
}

int BWAPI::Player::supplyUsed(Race race = Races::None) const

Retrieves the current amount of supply that the player is using for unit control.

Parameters
race (optional) The race to query the used supply for. If this is omitted, then the player's current race will be used.
Returns The supply that is in use for this player and the given race.

double BWAPI::Player::topSpeed(UnitType unit) const

Retrieves the top speed of a unit type, taking the player's speed upgrades into consideration.

Parameters
unit The UnitType to retrieve the top speed for.
Returns Top speed of the provided unit type for this player.

int BWAPI::Player::visibleUnitCount(UnitType unit = UnitTypes::AllUnits) const

Retrieves the total number of strictly visible units that the player has, even if information on the player is unrestricted.

Parameters
unit (optional) The unit type to query. UnitType macros are accepted. If this parameter is omitted, then it will use UnitTypes::AllUnits by default.
Returns The total number of units of the given type that the player owns, and is visible to the BWAPI player.

int BWAPI::Player::weaponDamageCooldown(UnitType unit) const

Retrieves the ground weapon cooldown of a unit type, taking the player's attack speed upgrades into consideration.

Parameters
unit The UnitType to retrieve the ground damage cooldown for.
Returns Ground weapon cooldown of the provided unit type for this player.

int BWAPI::Player::weaponMaxRange(WeaponType weapon) const

Retrieves the maximum weapon range of a weapon type, taking the player's weapon upgrades into consideration.

Parameters
weapon The WeaponType to retrieve the maximum range for.
Returns Maximum range of the given weapon type for units owned by this player.