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
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.
obj.clientInfo["test"] = 5 print(obj.clientInfo["test"]) -- prints "5"
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 useUnitTypes.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.
-
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 useUnitTypes.AllUnits
by default.Returns: The number of completed units of the given type that the player owns. Return type: int
-
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 useUnitTypes.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()
inUse 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 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. ReturnsRaces.Unknown
if the player choseRaces.Random
when the game started and they have not been seen.Return type: BWAPI.Race
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, orTilePositions.Unknown
if an error occured while trying to retrieve the start location.Return type: BWAPI.TilePosition
See also
-
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
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 returnPlayerTypes.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
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
, orExtractors
.
-
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
-
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 notReturn type: boolean See also
-
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 aSpire
, but the player has (or is in the process of morphing) aGreater 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
- unitType (BWAPI.UnitType) – The
-
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 useUnitTypes.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
-
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 withplayer
, orfalse
if this player is not allied withplayer
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
-
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 withplayer
, orfalse
if this player is not allied withplayer
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
-
isNeutral
() → boolean¶ Checks if this player is the neutral player.
Returns: Returns true
if this player is the neutral player, orfalse
if this player is any other playerReturn 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 otherwiseReturn type: boolean See also
-
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 otherwiseReturn type: boolean See also
-
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 useUnitTypes.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 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 anOverlord
will not give you 32 supply. It will instead give you 16Protoss
supply and 16Zerg
supply.See also
-
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
-
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 useUnitTypes.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
-
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.
-