Inheritance diagram for BWAPI::PlayerInterface:

Public Member Functions
virtual int	allUnitCount (UnitType unit=UnitTypes::AllUnits) const =0
int	armor (UnitType unit) const
virtual int	completedUnitCount (UnitType unit=UnitTypes::AllUnits) const =0
int	damage (WeaponType wpn) const
virtual int	deadUnitCount (UnitType unit=UnitTypes::AllUnits) const =0
virtual int	gas () const =0
virtual int	gatheredGas () const =0
virtual int	gatheredMinerals () const =0
virtual int	getBuildingScore () const =0
virtual BWAPI::Color	getColor () const =0
virtual int	getCustomScore () const =0
virtual Force	getForce () const =0
virtual int	getID () const =0
virtual int	getKillScore () const =0
virtual int	getMaxUpgradeLevel (UpgradeType upgrade) const =0
virtual std::string	getName () const =0
virtual Race	getRace () const =0
virtual int	getRazingScore () const =0
virtual TilePosition	getStartLocation () const =0
char	getTextColor () const
virtual PlayerType	getType () const =0
virtual const Unitset &	getUnits () const =0
virtual int	getUnitScore () const =0
virtual int	getUpgradeLevel (UpgradeType upgrade) const =0
virtual bool	hasResearched (TechType tech) const =0
bool	hasUnitTypeRequirement (UnitType unit, int amount=1) const
int	incompleteUnitCount (UnitType unit=UnitTypes::AllUnits) const
virtual bool	isAlly (const Player player) const =0
virtual bool	isDefeated () const =0
virtual bool	isEnemy (const Player player) const =0
virtual bool	isNeutral () const =0
virtual bool	isObserver () const =0
virtual bool	isResearchAvailable (TechType tech) const =0
virtual bool	isResearching (TechType tech) const =0
virtual bool	isUnitAvailable (UnitType unit) const =0
virtual bool	isUpgrading (UpgradeType upgrade) const =0
virtual bool	isVictorious () const =0
virtual int	killedUnitCount (UnitType unit=UnitTypes::AllUnits) const =0
virtual bool	leftGame () const =0
int	maxEnergy (UnitType unit) const
virtual int	minerals () const =0
virtual int	refundedGas () const =0
virtual int	refundedMinerals () const =0
virtual int	repairedGas () const =0
virtual int	repairedMinerals () const =0
int	sightRange (UnitType unit) const
virtual int	spentGas () const =0
virtual int	spentMinerals () const =0
virtual int	supplyTotal (Race race=Races::None) const =0
virtual int	supplyUsed (Race race=Races::None) const =0
double	topSpeed (UnitType unit) const
virtual int	visibleUnitCount (UnitType unit=UnitTypes::AllUnits) const =0
int	weaponDamageCooldown (UnitType unit) const
int	weaponMaxRange (WeaponType weapon) const

Detailed Description

The Player represents a unique controller in the game.

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

See also: Playerset, PlayerType, Race

Member Function Documentation

virtual int BWAPI::PlayerInterface::getID () const pure virtual

Retrieves a unique ID that represents the player.

Returns: An integer representing the ID of the player.

virtual std::string BWAPI::PlayerInterface::getName () const pure virtual

Retrieves the name of the player.

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

Note: Don't forget to use std::string::c_str() when passing this parameter to Game::sendText and other variadic functions.

Example usage:

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

virtual const Unitset& BWAPI::PlayerInterface::getUnits () const pure virtual

Retrieves the set of all units that the player owns.

This also includes incomplete units.

Returns: Reference to a Unitset containing the units.

Note: This does not include units that are loaded into transports, Bunkers, Refineries, Assimilators, or Extractors.

Example usage:

Unitset myUnits = BWAPI::Broodwar->self()->getUnits();
for ( auto u = myUnits.begin(); u != myUnits.end(); ++u )
{
// Do something with your units
}

virtual Race BWAPI::PlayerInterface::getRace () const pure virtual

Retrieves the race of the player.

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

Return values

Races::Unknown If the player chose Races::Random when the game started and they have not been seen.

Returns: The Race that the player is using.

Example usage:

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

virtual PlayerType BWAPI::PlayerInterface::getType () const pure virtual

Retrieves the player's controller type.

This allows you to distinguish betweeen computer and human players.

Returns: The PlayerType that identifies who is controlling a player.

Note: Other players using BWAPI will be treated as a human player and return PlayerTypes::Player.

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

virtual Force BWAPI::PlayerInterface::getForce () const pure virtual

Retrieves the player's force.

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

Returns: The Force object that the player is part of.

virtual bool BWAPI::PlayerInterface::isAlly (const Player player) const pure virtual

Checks if this player is allied to the specified player.

Parameters

player The player to check alliance with.

Return values

true	if this player is allied with `player` .
false	if this player is not allied with `player`.

Note: This function will also return false if this player is neutral or an observer, or if player is neutral or an observer.

See also: isEnemy

virtual bool BWAPI::PlayerInterface::isEnemy (const Player player) const pure virtual

Checks if this player is unallied to the specified player.

Parameters

player The player to check alliance with.

Return values

true	if this player is allied with `player` .
false	if this player is not allied with `player` .

Note: This function will also return false if this player is neutral or an observer, or if player is neutral or an observer.

See also: isAlly

virtual bool BWAPI::PlayerInterface::isNeutral () const pure virtual

Checks if this player is the neutral player.

Return values

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

virtual TilePosition BWAPI::PlayerInterface::getStartLocation () const pure virtual

Retrieve's the player's starting location.

Returns: A TilePosition containing the position of the start location.

Return values

TilePositions::None	if the player does not have a start location.
TilePositions::Unknown	if an error occured while trying to retrieve the start location.

See also: Game::getStartLocations, Game::getLastError

virtual bool BWAPI::PlayerInterface::isVictorious () const pure virtual

Checks if the player has achieved victory.

Returns: true if this player has achieved victory, otherwise false

virtual bool BWAPI::PlayerInterface::isDefeated () const pure virtual

Checks if the player has been defeated.

Returns: true if the player is defeated, otherwise false

virtual bool BWAPI::PlayerInterface::leftGame () const pure virtual

Checks if the player has left the game.

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

virtual int BWAPI::PlayerInterface::minerals () const pure virtual

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

Note: This function will return 0 if the player is inaccessible.

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

virtual int BWAPI::PlayerInterface::gas () const pure virtual

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

Note: This function will return 0 if the player is inaccessible.

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

virtual int BWAPI::PlayerInterface::gatheredMinerals () const pure virtual

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

Note: This function will return 0 if the player is inaccessible.

Returns: Cumulative amount of minerals that the player has gathered.

virtual int BWAPI::PlayerInterface::gatheredGas () const pure virtual

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

Note: This function will return 0 if the player is inaccessible.

Returns: Cumulative amount of gas that the player has gathered.

virtual int BWAPI::PlayerInterface::repairedMinerals () const pure virtual

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

This function only applies to Terran players.

Note: This function will return 0 if the player is inaccessible.

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

virtual int BWAPI::PlayerInterface::repairedGas () const pure virtual

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

This function only applies to Terran players.

Note: This function will return 0 if the player is inaccessible.

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

virtual int BWAPI::PlayerInterface::refundedMinerals () const pure virtual

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

Note: This function will return 0 if the player is inaccessible.

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

virtual int BWAPI::PlayerInterface::refundedGas () const pure virtual

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

Note: This function will return 0 if the player is inaccessible.

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

virtual int BWAPI::PlayerInterface::spentMinerals () const pure virtual

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

Note: This function will return 0 if the player is inaccessible.

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

virtual int BWAPI::PlayerInterface::spentGas () const pure virtual

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

Note: This function will return 0 if the player is inaccessible.

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

virtual int BWAPI::PlayerInterface::supplyTotal (Race race = Races::None) const pure virtual

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

Note: In Starcraft programming, the managed supply values are double than what they appear in the game. The reason for this is because Zerglings use 0.5 visible supply.; In Starcraft, the supply for each race is separate. Having a Pylon and an Overlord will not give you 32 supply. It will instead give you 16 Protoss supply and 16 Zerg supply.

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 ( BWAPI::Broodwar->self()->supplyUsed() + 8 >= BWAPI::Broodwar->self()->supplyTotal() )
{
// Construct pylons, supply depots, or overlords
}

See also: supplyUsed

virtual int BWAPI::PlayerInterface::supplyUsed (Race race = Races::None) const pure virtual

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.

See also: supplyTotal

virtual int BWAPI::PlayerInterface::allUnitCount (UnitType unit = UnitTypes::AllUnits) const pure virtual

Retrieves the total number of units that the player has.

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

Note: While in-progress Protoss and Terran units will be counted, in-progress Zerg units (i.e. inside of an egg) do not.

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.

See also: visibleUnitCount, completedUnitCount, incompleteUnitCount

virtual int BWAPI::PlayerInterface::visibleUnitCount (UnitType unit = UnitTypes::AllUnits) const pure virtual

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.

See also: allUnitCount, completedUnitCount, incompleteUnitCount

virtual int BWAPI::PlayerInterface::completedUnitCount (UnitType unit = UnitTypes::AllUnits) const pure virtual

Retrieves the number of completed units that the player has.

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

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.

Example usage:

bool obtainNextUpgrade(BWAPI::UpgradeType upgType)
{
BWAPI::Playerself = BWAPI::Broodwar->self();
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 )
returnself->getUnits().upgrade(upgType);
returnfalse;
}

See also: allUnitCount, visibleUnitCount, incompleteUnitCount

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

Retrieves the number of incomplete units that the player has.

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

Note: This function is a macro for allUnitCount() - completedUnitCount().; Incomplete Zerg units inside of eggs are not counted.

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.

See also: allUnitCount, visibleUnitCount, completedUnitCount

virtual int BWAPI::PlayerInterface::deadUnitCount (UnitType unit = UnitTypes::AllUnits) const pure virtual

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.

virtual int BWAPI::PlayerInterface::killedUnitCount (UnitType unit = UnitTypes::AllUnits) const pure virtual

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.

virtual int BWAPI::PlayerInterface::getUpgradeLevel (UpgradeType upgrade) const pure virtual

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::Playerself = BWAPI::Broodwar->self();
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 )
returnself->getUnits().upgrade(upgType);
returnfalse;
}

See also: UnitInterface::upgrade, getMaxUpgradeLevel

virtual bool BWAPI::PlayerInterface::hasResearched (TechType tech) const pure virtual

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

See also: isResearching, UnitInterface::research, isResearchAvailable

virtual bool BWAPI::PlayerInterface::isResearching (TechType tech) const pure virtual

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

See also: UnitInterface::research, hasResearched

virtual bool BWAPI::PlayerInterface::isUpgrading (UpgradeType upgrade) const pure virtual

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::Playerself = BWAPI::Broodwar->self();
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 )
returnself->getUnits().upgrade(upgType);
returnfalse;
}

See also: UnitInterface::upgrade

virtual BWAPI::Color BWAPI::PlayerInterface::getColor () const pure virtual

Retrieves the color value of the current player.

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

char BWAPI::PlayerInterface::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.

int BWAPI::PlayerInterface::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.

double BWAPI::PlayerInterface::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::PlayerInterface::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.

int BWAPI::PlayerInterface::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::PlayerInterface::weaponDamageCooldown (UnitType unit) const

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

Parameters

unit	The UnitType to retrieve the damage cooldown for.

Returns: Weapon cooldown of the provided unit type for this player.

int BWAPI::PlayerInterface::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::PlayerInterface::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.

virtual int BWAPI::PlayerInterface::getUnitScore () const pure virtual

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

Returns: The player's unit score.

virtual int BWAPI::PlayerInterface::getKillScore () const pure virtual

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

Returns: The player's kill score.

virtual int BWAPI::PlayerInterface::getBuildingScore () const pure virtual

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

Returns: The player's building score.

virtual int BWAPI::PlayerInterface::getRazingScore () const pure virtual

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

Returns: The player's razing score.

virtual int BWAPI::PlayerInterface::getCustomScore () const pure virtual

Retrieves the player's custom score.

This score is used in Use Map Settings game types.

Returns: The player's custom score.

virtual bool BWAPI::PlayerInterface::isObserver () const pure virtual

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

An observer player does not participate in the game.

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

virtual int BWAPI::PlayerInterface::getMaxUpgradeLevel (UpgradeType upgrade) const pure virtual

Retrieves the maximum upgrades available specific to the player.

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

Parameters

upgrade The UpgradeType to retrieve the maximum upgrade level for.

Returns: Maximum upgrade level of the given upgrade type.

Example usage:

bool obtainNextUpgrade(BWAPI::UpgradeType upgType)
{
BWAPI::Playerself = BWAPI::Broodwar->self();
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 )
returnself->getUnits().upgrade(upgType);
returnfalse;
}

virtual bool BWAPI::PlayerInterface::isResearchAvailable (TechType tech) const pure virtual

Checks if a technology can be researched by the player.

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

Parameters

tech	The TechType to query.

Returns: true if the tech type is available to the player for research.

virtual bool BWAPI::PlayerInterface::isUnitAvailable (UnitType unit) const pure virtual

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

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

Parameters

unit	The UnitType to check.

Returns: true if the unit type is available to the player.

bool BWAPI::PlayerInterface::hasUnitTypeRequirement (UnitType unit, int amount = 1 ) const

Verifies that this player satisfies a unit type requirement.

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.

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.

Since: 4.1.2

Public Member Functions

Detailed Description

Member Function Documentation