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

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 UnitsetgetUnits () 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::UnknownIf 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() )
{
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
playerThe player to check alliance with.
Return values
trueif this player is allied with player .
falseif 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
playerThe player to check alliance with.
Return values
trueif this player is allied with player .
falseif 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
trueif this player is the neutral player.
falseif 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::Noneif the player does not have a start location.
TilePositions::Unknownif 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.

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)
{
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;
}
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().
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
upgradeThe UpgradeType to query.
Returns
The number of levels that the upgrade has been upgraded for this player.

Example usage:

bool obtainNextUpgrade(BWAPI::UpgradeType upgType)
{
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;
}
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
techThe 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
techThe 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
upgradeThe upgrade type to query.
Returns
true if the player is currently upgrading the given upgrade, false otherwise

Example usage:

bool obtainNextUpgrade(BWAPI::UpgradeType upgType)
{
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;
}
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
unitThe 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
unitThe 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
weaponThe 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
unitThe 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
unitThe 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
unitThe 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
wpnThe 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
upgradeThe UpgradeType to retrieve the maximum upgrade level for.
Returns
Maximum upgrade level of the given upgrade type.

Example usage:

bool obtainNextUpgrade(BWAPI::UpgradeType upgType)
{
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;
}
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
techThe 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
unitThe 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
unitThe 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