Player

class BWAPI.Player

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

Constructors

This class is not constructable through Lua.

Member Variables

clientInfo

A Lua table that can be used to store arbitrary data associated with the current object.

Example usage

obj.clientInfo["test"] = 5
print(obj.clientInfo["test"]) -- prints "5"

See also

The differences between the C++ and Lua implementations

Member Functions

allUnitCount([unitType = UnitTypes.AllUnits]) → int

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:unitType (BWAPI.UnitType) – (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. Return type:int

Note

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

See also

visibleUnitCount(), completedUnitCount(), incompleteUnitCount()

armor(unitType) → int

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

Parameters:unitType (BWAPI.UnitType) – 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. Return type:int

completedUnitCount([unitType = UnitTypes.AllUnits]) → int

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:unitType (BWAPI.UnitType) – (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. Return type:int

See also

allUnitCount(), visibleUnitCount(), incompleteUnitCount()

damage(weaponType) → int

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

Parameters:weaponType (BWAPI.WeaponType) – The weapon type to calculate for. Returns:The amount of damage that the weapon deals with this player’s upgrades. Return type:int

deadUnitCount([unitType = UnitTypes.AllUnits]) → int

Retrieves the number units that have died for this player.

Parameters:unitType (BWAPI.UnitType) – (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. Return type:int

gas() → int

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

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

Note

This function will return 0 if the player is inaccessible.

gatheredGas() → 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).

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

Note

This function will return 0 if the player is inaccessible.

gatheredMinerals() → 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).

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

Note

This function will return 0 if the player is inaccessible.

getBuildingScore() → int

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

Returns:The player’s building score. Return type:int

getColor() → BWAPI.Color

Retrieves the color value of the current player.

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

getCustomScore() → int

Retrieves the player’s custom score.

This score is used in Use Map Settings game types.

Returns:The player’s custom score. Return type:int

getForce() → Force

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. Return type:BWAPI.Force

getID() → int

Retrieves a unique ID that represents the player.

Returns:An integer representing the ID of the player. Return type:int

getKillScore() → int

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

Returns:The player’s kill score. Return type:int

getMaxUpgradeLevel(upgrade) → int

Retrieves the maximum upgrades available specific to the player.

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

Parameters:upgrade (BWAPI.UpgradeType) – The UpgradeType to retrieve the maximum upgrade level for. Returns:Maximum upgrade level of the given upgrade type. Return type:int

getName() → string

Retrieves the name of the player.

Returns:A string containing the player’s name. Return type:string

Example usage

local myEnemy = BWAPI.Broodwar:enemy()
if myEnemy then   -- Make sure there is an enemy!
  BWAPI.Broodwar:sendText(string.format("Prepare to be crushed, %s!", myEnemy:getName()))
end

getRace() → Race

Retrieves the race of the player.

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

Returns:The Race that the player is using. Returns Races.Unknown if the player chose Races.Random when the game started and they have not been seen. Return type:BWAPI.Race

Example usage

if BWAPI.Broodwar:enemy() then
  local enemyRace = BWAPI.Broodwar:enemy():getRace()
  if enemyRace == BWAPI.Races.Zerg then
    BWAPI.Broodwar:sendText("Do you really think you can beat me with a zergling rush?")
  end
end

getRazingScore() → int

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

Returns:The player’s razing score. Return type:int

getStartLocation() → TilePosition

Retrieve’s the player’s starting location.

Returns:A TilePosition containing the position of the start location. Returns TilePositions.None if the player does not have a start location, or TilePositions.Unknown if an error occured while trying to retrieve the start location. Return type:BWAPI.TilePosition

See also

Game.getStartLocations(), Game.getLastError()

getTextColor() → string

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, encoded as a string. Return type:string

getType() → PlayerType

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. Return type:BWAPI.PlayerType

Example usage

if BWAPI.Broodwar:enemy() then
  if BWAPI.Broodwar:enemy():getType() == BWAPI.PlayerTypes.Computer then
    print("Looks like something I can abuse!")
  end
end

Note

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

getUnits() → Unitset

Retrieves the set of all units that the player owns.

This also includes incomplete units.

Returns:Reference to a Unitset containing the units. Return type:BWAPI.Unitset

Example usage

local myUnits = BWAPI.Broodwar:self():getUnits()
for u in myUnits:iterator() do
  -- Do something with your units
end

Note

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

getUnitScore() → int

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

Returns:The player’s unit score. Return type:int

getUpgradeLevel(upgrade) → int

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

Parameters:upgrade (BWAPI.UpgradeType) – The UpgradeType to query. Returns:The number of levels that the upgrade has been upgraded for this player. Return type:int

See also

Unit.upgrade(), getMaxUpgradeLevel()

hasResearched(tech) → boolean

Checks if the player has already researched a given technology.

Parameters:tech (BWAPI.TechType) – The TechType to query. Returns:true if the player has obtained the given tech, or false if they have not Return type:boolean

See also

isResearching(), Unit.research(), isResearchAvailable()

hasUnitTypeRequirement(unitType[, amount = 1]) → boolean

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:

• unitType (BWAPI.UnitType) – The UnitType to check.
• amount (int) – (optional) The amount of units that are required.

Returns:

true if the unit type requirements are met, and false otherwise.

Return type:

boolean

incompleteUnitCount([unitType = UnitTypes.AllUnits]) → int

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.

Parameters:unitType (BWAPI.UnitType) – (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. Return type:int

Note

This function is a macro for allUnitCount() - completedUnitCount().

Note

Incomplete Zerg units inside of eggs are not counted.

See also

allUnitCount(), visibleUnitCount(), completedUnitCount()

isAlly(player) → boolean

Checks if this player is allied to the specified player.

Parameters:player (BWAPI.Player) – The player to check alliance with. Returns:Returns true if this player is allied with player , or false if this player is not allied with player Return type:boolean

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

isDefeated() → boolean

Checks if the player has been defeated.

Returns:true if the player is defeated, otherwise false Return type:boolean

isEnemy(player) → boolean

Checks if this player is unallied to the specified player.

Parameters:player (BWAPI.Player) – The player to check alliance with. Returns:Returns true if this player is allied with player , or false if this player is not allied with player Return type:boolean

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

isNeutral() → boolean

Checks if this player is the neutral player.

Returns:Returns true if this player is the neutral player, or false if this player is any other player Return type:boolean

isObserver() → boolean

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. Return type:boolean

isResearchAvailable(tech) → boolean

Checks if a technology can be researched by the player.

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

Parameters:tech (BWAPI.TechType) – The TechType to query. Returns:true if the tech type is available to the player for research. Return type:boolean

isResearching(tech) → boolean

Checks if the player is researching a given technology type.

Parameters:tech (BWAPI.TechType) – The TechType to query. Returns:true if the player is currently researching the tech, or false otherwise Return type:boolean

See also

Unit.research(), hasResearched()

isUnitAvailable(unitType) → boolean

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

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

Parameters:unitType (BWAPI.UnitType) – The UnitType to check. Returns:true if the unitType is available to the player. Return type:boolean

isUpgrading(upgrade) → boolean

Checks if the player is upgrading a given upgrade type.

Parameters:upgrade (BWAPI.UpgradeType) – The upgrade type to query. Returns:true if the player is currently upgrading the given upgrade, false otherwise Return type:boolean

See also

Unit.upgrade()

isVictorious() → boolean

Checks if the player has achieved victory.

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

killedUnitCount([unit = UnitTypes.AllUnits]) → int

Retrieves the number units that the player has killed.

Parameters:unit (BWAPI.UnitType) – (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. Return type:int

leftGame() → boolean

Checks if the player has left the game.

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

maxEnergy(unitType) → int

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

Parameters:unitType (BWAPI.UnitType) – The UnitType to retrieve the maximum energy for. Returns:Maximum amount of energy that the given unit type can have. Return type:int

minerals() → int

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

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

Note

This function will return 0 if the player is inaccessible.

refundedGas() → int

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. Return type:int

Note

This function will return 0 if the player is inaccessible.

refundedMinerals() → int

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. Return type:int

Note

This function will return 0 if the player is inaccessible.

repairedGas() → int

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.

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

Note

This function will return 0 if the player is inaccessible.

repairedMinerals() → int

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.

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

Note

This function will return 0 if the player is inaccessible.

sightRange(unitType) → int

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

Parameters:unitType (BWAPI.UnitType) – The UnitType to retrieve the sight range for. Returns:Sight range of the provided unit type for this player. Return type:int

spentGas() → int

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

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

Note

This function will return 0 if the player is inaccessible.

spentMinerals() → int

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

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

Note

This function will return 0 if the player is inaccessible.

supplyTotal([race = Races.None]) → int

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

Parameters:race (BWAPI.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. Return type:int

Example usage

if BWAPI.Broodwar:self():supplyUsed() + 8 >= BWAPI.Broodwar:self():supplyTotal() then
  -- Construct pylons, supply depots, or overlords
end

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.

Note

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.

See also

supplyUsed()

supplyUsed([race = Races.None]) → int

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

Parameters:race (BWAPI.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. Return type:int

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.

See also

supplyTotal()

topSpeed(unit) → double

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

Parameters:unit (BWAPI.UnitType) – The UnitType to retrieve the top speed for. Returns:Top speed of the provided unit type for this player. Return type:double

visibleUnitCount([unitType = UnitTypes.AllUnits]) → int

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

Parameters:unitType (BWAPI.UnitType) – (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. Return type:int

See also

allUnitCount(), completedUnitCount(), incompleteUnitCount()

weaponDamageCooldown(unitType) → int

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

Parameters:unitType (BWAPI.UnitType) – The UnitType to retrieve the damage cooldown for. Returns:Weapon cooldown of the provided unit type for this player. Return type:int

weaponMaxRange(weapon) → int

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

Parameters:weapon (BWAPI.WeaponType) – The WeaponType to retrieve the maximum range for. Returns:Maximum range of the given weapon type for units owned by this player. Return type:int

registerEvent(action[, condition = nil][, timesToRun = -1][, framesToCheck = 0])

Registers an event and associates it with the current object.

Events can be used to automate tasks (like train X Marines until Y of them have been created by the given Barracks) or to create user-defined callbacks.

Parameters:

• action (function) – The callback to be executed when the event conditions are true.
• condition (function) – (optional) The condition callback which will return true if the action is intended to be executed. The condition will always be true if omitted.
• timesToRun (int) – (optional) The number of times to execute the action before the event is removed. If the value is negative, then the event will never be removed. The value will be -1 if omitted, causing the event to execute until the game ends.
• framesToCheck (int) – (optional) The number of frames to skip between checks. If this value is 0, then a condition check is made once per frame. If this value is 1, then the condition for this event is only checked every other frame. This value is 0 by default, meaning the event’s condition is checked every frame.