Unit¶

class BWAPI.Unit¶

The Unit class is used to get information about individual units as well as issue orders to units.

Every Unit in the game is either accessible or inaccessible. To determine if an AI can access a particular unit, BWAPI checks to see if BWAPI.Flag.CompleteMapInformation is enabled. So there are two cases to consider - either the flag is enabled, or it is disabled:

If BWAPI.Flag.CompleteMapInformation is disabled, then a unit is accessible if and only if it is visible. If BWAPI.Flag.CompleteMapInformation is enabled, then all units that exist in the game are accessible, and Unit.exists() is accurate for all units. Similarly BWAPI.onUnitDestroy() messages are generated for all units that get destroyed, not just visible ones.

Note

Some properties of visible enemy units will not be made available to the AI (such as the contents of visible enemy dropships). If a unit is not visible, Unit.exists() will return false, regardless of whether or not the unit exists. This is because absolutely no state information on invisible enemy units is made available to the AI. To determine if an enemy unit has been destroyed, the AI must watch for BWAPI.onUnitDestroy() messages from BWAPI, which is only called for visible units which get destroyed.

If a Unit is not accessible, then only the getInitial* functions will be available to the AI. However for units that were owned by the player, Unit.getPlayer() and Unit.getType() will continue to work for units that have been destroyed.

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"

Member Functions

getID() → id¶

Retrieves a unique identifier for this unit.

Returns:	An integer containing the unit’s identifier.
Return type:	number

See also

getReplayID()

exists() → exists¶

Checks if the Unit exists in the view of the BWAPI player.

This is used primarily to check if BWAPI has access to a specific unit, or if the unit is alive. This function is more general and would be synonymous to an isAlive function if such a function were necessary.

In the event that this function returns false, there are two cases to consider:

You own the unit. This means the unit is dead.
Another player owns the unit. This could either mean that you don’t have access to the unit or that the unit has died. You can specifically identify dead units by polling onUnitDestroy.

Returns:	`true` if the unit exists on the map and is visible according to BWAPI or `false` if the unit is not accessible or the unit is dead.
Return type:	boolean

See also

isVisible(), isCompleted()

getReplayID() → id¶

Retrieves the unit identifier for this unit as seen in replay data.

Note

This is only available if BWAPI.Flag.CompleteMapInformation is enabled.

Returns:	An integer containing the replay unit identifier.

See also

getID()

getPlayer() → player¶

Retrieves the player that owns this unit.

Returns:	The owning `Player` or `Game.neutral()` if the unit is a neutral unit or inaccessible.
Return type:	`BWAPI.Player`

getType() → type¶

Retrieves the unit’s type.

Returns:	A `UnitType` representing the unit’s type or `Unknown` if this unit is inaccessible or cannot be determined.
Return type:	`BWAPI.UnitType`

See also

getInitialType()

getPosition() → position¶

Retrieves the unit’s position from the upper left corner of the map in pixels.

The position returned is roughly the center if the unit.

Returns:	Position object representing the unit’s current position or `Unknown` if this unit is inaccessible.
Return type:	`BWAPI.Position`

Note

The unit bounds are defined as this value plus/minus the values of UnitType.dimensionLeft(), UnitType.dimensionUp(), UnitType.dimensionRight(), and UnitType.dimensionDown(), which is conveniently expressed in getLeft(), getTop(), getRight(), and getBottom() respectively.

getTilePosition() → tilePosition¶

Retrieves the unit’s build position from the upper left corner of the map in tiles.

Returns:	TilePosition object representing the unit’s current tile position or `Unknown` if this unit is inaccessible.
Return type:	`BWAPI.TilePosition`

Note

This tile position is the tile that is at the top left corner of the structure.

getAngle() → angle¶

Retrieves the unit’s facing direction in radians.

Note

A value of 0.0 means the unit is facing east.

Returns:	A double with the angle measure in radians.
Return type:	number

getVelocityX() → velocityX¶

Retrieves the x component of the unit’s velocity, measured in pixels per frame.

Returns:	A double that represents the velocity’s x component.
Return type:	number

See also

getVelocityY()

getVelocityY() → velocityY¶

Retrieves the y component of the unit’s velocity, measured in pixels per frame.

Returns:	A double that represents the velocity’s y component.
Return type:	number

See also

getVelocityX()

getRegion() → region¶

Retrieves the Region that the center of the unit is in.

Returns:	The `Region` object that contains this unit or `nil` if the unit is inaccessible.
Return type:	`Region`

Example¶

local Broodwar = BWAPI.Broodwar
local myUnits = Broodwar:self():getUnits()
for u in myUnits:iterator() do
  if u:isFlying() and u:isUnderAttack() then -- implies exists and isCompleted
    local r = u:getRegion()
    if r then
      u:move(r:getClosestInaccessibleRegion()) -- Retreat to inaccessible region
    end
  end
end

Note

If this function returns a successful state, then the following functions will also return a successful state: exists()

getLeft() → left¶

Retrieves the X coordinate of the unit’s left boundary, measured in pixels from the left side of the map.

Returns:	An integer representing the position of the left side of the unit.
Return type:	number

See also

getTop(), getRight(), getBottom()

getTop() → top¶

Retrieves the Y coordinate of the unit’s top boundary, measured in pixels from the top of the map.

Returns:	An integer representing the position of the top side of the unit.
Return type:	number

getRight() → right¶

Retrieves the X coordinate of the unit’s right boundary, measured in pixels from the left side of the map.

Returns:	An integer representing the position of the right side of the unit.
Return type:	number

See also

getLeft(), getTop(), getBottom()

getBottom() → bottom¶

Retrieves the Y coordinate of the unit’s bottom boundary, measured in pixels from the top of the map.

Returns:	An integer representing the position of the bottom side of the unit.
Return type:	number

See also

getLeft(), getTop(), getRight()

getHitPoints() → hp¶

Retrieves the unit’s current Hit Points (HP) as seen in the game.

Returns:	An integer representing the amount of hit points a unit currently has.
Return type:	number

Note

In Starcraft, a unit usually dies when its HP reaches 0. It is possible however, to have abnormal HP values in the Use Map Settings game type and as the result of a hack over Battle.net. Such values include units that have 0 HP (can’t be killed conventionally) or even negative HP (death in one hit).

getShields() → shields¶

Retrieves the unit’s current Shield Points (Shields) as seen in the game.

Returns:	An integer representing the amount of shield points a unit currently has.
Return type:	number

getEnergy() → energy¶

Retrieves the unit’s current Energy Points (Energy) as seen in the game.

Returns:	An integer representing the amount of energy points a unit currently has.
Return type:	number

Note

Energy is required in order for units to use abilities.

See also

UnitType.maxEnergy()

getResources() → resources¶

Retrieves the resource amount from a resource container, such as a Mineral Field and Vespene Geyser.

If the unit is inaccessible, then the last known resource amount is returned.

Returns:	An integer representing the last known amount of resources remaining in this resource.
Return type:	number

See also

getInitialResources()

getResourceGroup() → int¶

Retrieves a grouping index from a resource container.

Other resource containers of the same value are considered part of one expansion location (group of resources that are close together).

Note

This grouping method is explicitly determined by Starcraft itself and is used only by the internal AI.

Returns:	An integer with an identifier between 0 and 250 that determine which resources are grouped together to form an expansion.

getDistance(target) → distance¶

Retrieves the distance between this unit and a target.

Note

Distance is calculated from the edge of this unit, using Starcraft’s own distance algorithm. Ignores collisions.

Parameters:	target (`BWAPI.Position` or `BWAPI.Unit`) – Can be either a `Position` or `Unit`. If it is a unit, then it will calculate the distance to the edge of the target unit.
Returns:	An integer representation of the number of pixels between this unit and the `target`.
Return type:	number

hasPath(target) → hasPath¶

Using data provided by Starcraft, checks if there is a path available from this unit to the given target.

Note

This function only takes into account the terrain data, and does not include buildings when determining if a path is available. However, the complexity of this function is constant ( O(1) ), and no extensive calculations are necessary.

Note

If the current unit is an air unit, then this function will always return true.

Note

If the unit somehow gets stuck in unwalkable terrain, then this function may still return true if one of the unit’s corners is on walkable terrain (i.e. if the unit is expected to return to the walkable terrain).

Parameters:	target (`BWAPI.Position` or `BWAPI.Unit`) – Can be either a `Position` or `Unit`. A Position or a Unit that is used to determine if this unit has a path to the target.
Returns:	`true` if there is a path between this unit and the target or `false` if the target is on a different piece of land than this one (such as an island).
Return type:	boolean

getLastCommandFrame() → frameNum¶

Retrieves the frame number that sent the last successful command.

Note

This value is comparable to Game.getFrameCount().

Returns:	The frame number that sent the last successfully processed command to BWAPI.
Return type:	number

getLastCommand() → command¶

Retrieves the last successful command that was sent to BWAPI.

Returns:	The last command that was processed.
Return type:	`UnitCommand`

See also

getLastCommandFrame()

getLastAttackingPlayer() → player¶

Retrieves the Player that last attacked this unit.

Returns:	Player that last attacked this unit or `nil` if this unit was not attacked.
Return type:	`Player`

Note

If this function returns a successful state, then the following function calls will also return a successful state: exists()

getInitialType() → type¶

Retrieves the initial type of the unit.

This is the type that the unit starts as in the beginning of the game. This is used to access the types of static neutral units such as mineral fields when they are not visible.

Returns:	`UnitType` of this unit as it was when it was created or `Unknown` if this unit was not a static neutral unit in the beginning of the game.
Return type:	`UnitType`

getInitialPosition() → position¶

Retrieves the initial position of this unit.

This is the position that the unit starts at in the beginning of the game. This is used to access the positions of static neutral units such as mineral fields when they are not visible.

Returns:	Position indicating the unit’s initial position when it was created or `Unknown` if this unit was not a static neutral unit in the beginning of the game.
Return type:	`Position`

getInitialTilePosition() → tilePosition¶

Retrieves the initial build tile position of this unit.

This is the tile position that the unit starts at in the beginning of the game. This is used to access the tile positions of static neutral units such as mineral fields when they are not visible. The build tile position corresponds to the upper left corner of the unit.

Returns:	TilePosition indicating the unit’s initial tile position when it was created or `Unknown` if this unit was not a static neutral unit in the beginning of the game.
Return type:	`TilePosition`

getInitialHitPoints() → hp¶

Retrieves the amount of hit points that this unit started off with at the beginning of the game.

The unit must be neutral.

Returns:	Number of hit points that this unit started with or `0` if this unit was not a neutral unit at the beginning of the game.
Return type:	number

Note

It is possible for the unit’s initial hit points to differ from the maximum hit points.

See also

Game.getStaticNeutralUnits()

getInitialResources() → resources¶

Retrieves the amount of resources contained in the unit at the beginning of the game.

The unit must be a neutral resource container.

Returns:	Amount of resources that this unit started with or `0` if this unit was not a neutral unit at the beginning of the game, or if this unit does not contain resources. It is possible that the unit simply contains 0 resources.

See also

Game.getStaticNeutralUnits()

getKillCount() → kills¶

Retrieves the number of units that this unit has killed in total.

Note

The maximum amount of recorded kills per unit is 255.

Returns:	integer indicating this unit’s kill count.
Return type:	number

getAcidSporeCount() → count¶

Retrieves the number of acid spores that this unit is inflicted with.

Returns:	Number of acid spores on this unit.
Return type:	number

getInterceptorCount() → count¶

Retrieves the number of interceptors that this unit manages.

This function is only for the Carrier and its hero.

Returns:	Number of interceptors in this unit.
Return type:	number

Note

This number may differ from the number of units returned from getInterceptors(). This occurs for cases in which you can see the number of enemy interceptors in the Carrier HUD, but don’t actually have access to the individual interceptors.

See also

getInterceptors()

getScarabCount() → count¶

Retrieves the number of scarabs that this unit has for use.

This function is only for the Reaver.

Returns:	Number of scarabs this unit has ready.
Return type:	number

getSpiderMineCount() → count¶

Retrieves the amount of Spider Mines this unit has available.

This function is only for the Vulture <BWAPI.UnitTypes.Terran_Vulture.

Returns:	Number of spider mines available for placement.
Return type:	number

getGroundWeaponCooldown() → framesLeft¶

Retrieves the unit’s ground weapon cooldown.

This value decreases every frame, until it reaches 0. When the value is 0, this indicates that the unit is capable of using its ground weapon, otherwise it must wait until it reaches 0.

Note

This value will vary, because Starcraft adds an additional random value between (-1) and (+2) to the unit’s weapon cooldown.

Returns:	Number of frames needed for the unit’s ground weapon to become available again.
Return type:	number

getAirWeaponCooldown() → framesLeft¶

Retrieves the unit’s air weapon cooldown.

This value decreases every frame, until it reaches 0. When the value is 0, this indicates that the unit is capable of using its air weapon, otherwise it must wait until it reaches 0.

Note

This value will vary, because Starcraft adds an additional random value between (-1) and (+2) to the unit’s weapon cooldown.

Returns:	Number of frames needed for the unit’s air weapon to become available again.
Return type:	number

getSpellCooldown() → framesLeft¶

Retrieves the unit’s ability cooldown.

This value decreases every frame, until it reaches 0. When the value is 0, this indicates that the unit is capable of using one of its special abilities, otherwise it must wait until it reaches 0.

Note

This value will vary, because Starcraft adds an additional random value between (-1) and (+2) to the unit’s ability cooldown.

Returns:	Number of frames needed for the unit’s abilities to become available again.
Return type:	number

getDefenseMatrixPoints() → hp¶

Retrieves the amount of hit points remaining on the Defensive Matrix created by a Science Vessel.

The Defensive Matrix ability starts with 250 hit points when it is used.

Returns:	Number of hit points remaining on this unit’s `Defensive Matrix`.
Return type:	number

getDefenseMatrixTimer() → framesLeft¶

Retrieves the time, in frames, that the Defensive Matrix will remain active on the current unit.

Returns:	Number of frames remaining until the effect is removed.
Return type:	number

getEnsnareTimer() → framesLeft¶

Retrieves the time, in frames, that Ensnare will remain active on the current unit.

Returns:	Number of frames remaining until the effect is removed.
Return type:	number

See also

isEnsnared()

getIrradiateTimer() → framesLeft¶

Retrieves the time, in frames, that Irradiate will remain active on the current unit.

Returns:	Number of frames remaining until the effect is removed.
Return type:	number

See also

isIrradiated()

getLockdownTimer() → framesLeft¶

Retrieves the time, in frames, that Lockdown will remain active on the current unit.

Returns:	Number of frames remaining until the effect is removed.
Return type:	number

See also

isLockdowned()

getMaelstromTimer() → framesLeft¶

Retrieves the time, in frames, that Maelstrom will remain active on the current unit.

Returns:	Number of frames remaining until the effect is removed.
Return type:	number

See also

isMaelstrommed()

getOrderTimer() → framesLeft¶

Retrieves an internal timer used for the primary order.

Its use is specific to the order type that is currently assigned to the unit.

Returns:	A value used as a timer for the primary order.
Return type:	number

See also

getOrder()

getPlagueTimer() → framesLeft¶

Retrieves the time, in frames, that Plague will remain active on the current unit.

Returns:	Number of frames remaining until the effect is removed.
Return type:	number

See also

isPlagued()

getRemoveTimer() → framesLeft¶

Retrieves the time, in frames, until this temporary unit is destroyed or removed. Once this value reaches 0, the unit is destroyed.

This is used to determine the remaining time for the following units that were created by abilities:

Returns:	Number of frames remaining until the unit is destroyed or removed.
Return type:	number

getStasisTimer() → framesLeft¶

Retrieves the time, in frames, that Stasis Field will remain active on the current unit.

Returns:	Number of frames remaining until the effect is removed.
Return type:	number

See also

isStasised()

getStimTimer() → framesLeft¶

Retrieves the time, in frames, that Stim Packs will remain active on the current unit.

Returns:	Number of frames remaining until the effect is removed.
Return type:	number

See also

isStimmed()

getBuildType() → type¶

Retrieves the building type that a worker (SCV, Probe, Drone) is about to construct.

If the unit is morphing or is an incomplete structure, then this returns the UnitType that it will become when it has completed morphing/constructing.

Returns:	`UnitType` indicating the type that a worker (`SCV`, `Probe`, `Drone`) is about to construct, or the type that an incomplete unit will be when completed.
Return type:	`UnitType`

getTrainingQueue() → queue¶

Retrieves the list of units queued up to be trained.

Important

See the differences between the C++ and Lua implementations of this function for more information

Returns:	An array-like table containing all of the `UnitType`‘s that are in this building’s training queue.
Return type:	table of the format {1 = `UnitType`, 2 = `UnitType`, ...}

getTech() → tech¶

Retrieves the technology that this unit is currently researching.

Returns:	`TechType` indicating the technology being researched by this unit, or `None` if this unit is not researching anything.
Return type:	`TechType`

getUpgrade() → upgrade¶

Retrieves the upgrade that this unit is currently upgrading.

Returns:	`UpgradeType` indicating the upgrade in progress by this unit, or `None` if this unit is not upgrading anything.
Return type:	`UpgradeType`

getRemainingBuildTime() → framesLeft¶

Retrieves the remaining build time for a unit or structure that is being trained or constructed.

Returns:	Number of frames remaining until the unit’s completion.
Return type:	number

getRemainingResearchTime() → framesLeft¶

Retrieves the amount of time until the unit is done researching its currently assigned TechType.

Returns:	The remaining research time, in frames, for the current technology being researched by this unit, or `0` if the unit is not researching anything.
Return type:	number

getRemainingTrainTime() → framesLeft¶

Retrieves the remaining time, in frames, of the unit that is currently being trained.

Note

If the unit is a Hatchery, Lair, or Hive, this retrieves the amount of time until the next larva spawns.

Returns:	Number of frames remaining until the current training unit becomes completed, or the number of frames remaining until the next larva spawns, or `0` if the unit is not training or has three larvae.
Return type:	number

See also

train(), getTrainingQueue()

getRemainingUpgradeTime() → framesLeft¶

Retrieves the amount of time until the unit is done upgrading its current upgrade.

Returns:	The remaining upgrade time, in frames, for the current upgrade, or `0` if the unit is not upgrading anything.
Return type:	number

getBuildUnit() → unit¶

Retrieves the unit currently being trained, or the corresponding paired unit for SCVs and Terran structures, depending on the context.

For example, if this unit is a Factory under construction, this function will return the SCV that is constructing it. If this unit is a SCV, then it will return the structure it is currently constructing. If this unit is a Nexus, and it is training a Probe, then the probe will be returned.

Warning

This will return an incorrect unit when called on Reavers.

Returns:	Paired build unit that is either constructing this unit or being constructed by this unit, structure being constructed by this unit, the unit that is being trained by this structure, or `nil` if there is no unit constructing this one or this unit is not constructing another unit.
Return type:	`Unit`

getTarget() → unit¶

Generally returns the appropriate target unit after issuing an order that accepts a target unit (i.e. attack, repair, gather, etc.).

To get a target that has been acquired automatically without issuing an order, use getOrderTarget().

Returns:	Unit that is currently being targeted by this unit.
Return type:	`Unit`

See also

getOrderTarget()

getTargetPosition() → position¶

Retrieves the target position the unit is moving to, provided a valid path to the target position exists.

Returns:	Target position of a movement action.
Return type:	`Position`

getOrder() → order¶

Retrieves the primary Order that the unit is assigned.

Primary orders are distinct actions such as AttackUnit and PlayerGuard.

Returns:	The primary `Order` that the unit is executing.
Return type:	`Order`

getSecondaryOrder() → order¶

Retrieves the secondary Order that the unit is assigned.

Secondary orders are run in the background as a sub-order. An example would be TrainFighter, because a Carrier can move and train fighters at the same time.

Returns:	The secondary `Order` that the unit is executing.
Return type:	`Order`

getOrderTarget() → unit¶

Retrieves the unit’s primary order target.

This is usually set when the low level unit AI acquires a new target automatically. For example if an enemy Probe comes in range of your Marine, the Marine will start attacking it, and getOrderTarget will be set in this case, but not getTarget.

Returns:	The Unit that this unit is currently targetting.
Return type:	`Unit`

See also

getTarget(), getOrder()

getOrderTargetPosition() → position¶

Retrieves the target position for the unit’s order.

For example, when Move is assigned, getTargetPosition() returns the end of the unit’s path, but this returns the location that the unit is trying to move to.

Returns:	Position that this unit is currently targetting.
Return type:	`Position`

See also

getTargetPosition(), getOrder()

getRallyPosition() → position¶

Retrieves the position the structure is rallying units to once they are completed.

Returns:	Position that a completed unit coming from this structure will travel to, or `None` if this building does not produce units.
Return type:	`Position`

Note

If getRallyUnit() is valid, then this value is ignored.

See also

setRallyPoint(), getRallyUnit()

getRallyUnit() → unit¶

Retrieves the unit the structure is rallying units to once they are completed.

Units will then follow the targetted unit.

Returns:	Unit that a completed unit coming from this structure will travel to, or `nil` if the structure is not rallied to a unit or it does not produce units.
Return type:	`Unit`

Note

A rallied unit takes precedence over a rallied position. That is if the return value is valid (non-nil), then getRallyPosition() is ignored.

See also

setRallyPoint(), getRallyPosition()

getAddon() → unit¶

Retrieves the add-on that is attached to this unit.

Returns:	Unit interface that represents the add-on that is attached to this unit, or `nil` if this unit does not have an add-on.
Return type:	`Unit`

getNydusExit() → unit¶

Retrieves the Nydus Canal that is attached to this one.

Every Nydus Canal can place a “Nydus Exit” which, when connected, can be travelled through by Zerg units.

Returns:	Unit interface representing the `Nydus Canal` connected to this one, or `nil` if the unit is not a `Nydus Canal`, is not owned, or has not placed a Nydus Exit.
Return type:	`Unit`

getPowerUp() → unit¶

Retrieves the power-up that the worker unit is holding.

Power-ups are special units such as the Flag in the Capture The Flag game type, which can be picked up by worker units.

Returns:	The Unit interface object that represents the power-up, or `nil` if the unit is not carrying anything.
Return type:	`Unit`

Example¶

local myUnits = BWAPI.Broodwar:self():getUnits()
for u in myUnits:iterator() do
  -- If we are carrying a flag
  if u:getPowerUp() u:getPowerUp():getType() == BWAPI.UnitTypes.Powerup_Flag then
    local pred = function(x)
      return BWAPI.Filter.IsFlagBeacon(x) and BWAPI.Filter.IsOwned(x)
    end
    -- return it to our flag beacon to score
    u:move( u:getClosestUnit(pred) )
  end
end

Note

If your bot is strictly melee/1v1, then this method is not necessary.

Note

If this function returns a successful state, then the following function calls will also return a successful state: getType():isWorker(), isCompleted()

getTransport() → unit¶

Retrieves the transport unit (Dropship, Shuttle, Overlord ) or Bunker unit that has this unit loaded inside of it.

Returns:	The unit that this unit is loaded inside of, or `nil` if the unit is not loaded inside of a unit.
Return type:	`Unit`

getLoadedUnits() → units¶

Retrieves the set of units that are contained within this Bunker, Dropship, Shuttle, or Overlord.

Returns:	A `Unitset` containing all of the units that are loaded inside of the current unit.
Return type:	`Unitset`

getSpaceRemaining() → spaceRemaining¶

Retrieves the remaining unit-space available for Bunkers and transports (Dropships, Shuttles, Overlords ).

Returns:	The number of spots available to transport a unit.
Return type:	number

See also

getLoadedUnits()

getCarrier() → unit¶

Retrieves the parent Carrier that owns this Interceptor.

Returns:	The parent `Carrier` unit that has ownership of this one, or `nil` if the current unit is not an `Interceptor`.
Return type:	`Unit`

getInterceptors() → units¶

Retrieves the set of Interceptors controlled by this unit.

This is intended for Carriers and its hero.

Returns:	`Unitset` containing `Interceptor` units owned by this carrier.
Return type:	`Unitset`

See also

getInterceptorCount()

getHatchery() → unit¶

Retrieves the parent Hatchery, Lair, or Hive that owns this particular unit.

This is intended for Larvae.

Returns:	Hatchery unit that has ownership of this larva, or `nil` if the current unit is not a `Larva` or has no parent.
Return type:	`Unit`

See also

getLarva()

getLarva() → units¶

Retrieves the set of Larvae that were spawned by this unit.

Only Hatcheries, Lairs, and Hives are capable of spawning Larvae. This is like clicking the “Select Larva” button and getting the selection of Larvae.

Returns:	`Unitset` containing `Larva` units owned by this unit. The set will be empty if there are none.
Return type:	`Unitset`

See also

getHatchery()

getUnitsInRadius(radius[, pred]) → units¶

Retrieves the set of all units in a given radius of the current unit.

Takes into account this unit’s dimensions. Can optionally specify a filter to include only specific units (such as only ground units, etc.)

Parameters:	radius (number) – The radius, in pixels, to search for units. pred (function) – (optional) A predicate function that takes a `Unit` and returns `true` for units that satisfy the intended filter and `false` otherwise (can be a BWAPI.Filter unary filter). Defaults to `nil`, which means no filter.
Returns:	A `Unitset` containing the set of units that match the given criteria.
Return type:	`Unitset`

Example usage¶

-- Get main building closest to start location.
local isResourceDepotPred = function(x) return BWAPI.Filter.IsResourceDepot(x) end
local main = BWAPI.Broodwar:getClosestUnit( BWAPI.Broodwar:self():getStartLocation(), isResourceDepotPred )
if main then -- check if main is valid
  -- Get sets of resources and workers
  local myResources = main:getUnitsInRadius(1024, BWAPI.Filter.IsMineralField);
  if not myResources:empty() then -- check if we have resources nearby
    local workerPred = function(x)
      BWAPI.Filter.IsWorker(x) and BWAPI.Filter.IsIdle(x) and BWAPI.Filter.IsOwned(x)
    end
    local myWorkers = main:getUnitsInRadius(512, workerPred)
    local myResourcesArray = myResources:asTable()
    for worker in myWorkers:iterator() do
      local randomResource = myResourcesArray[math.random(#myResourcesArray)]
      worker:gather(randomResource)
    end
  end
end

getUnitsInWeaponRange(weapon[, pred]) → units¶

Obtains the set of units within weapon range of this unit.

Parameters:	weapon (BWAPI.WeaponType) – The weapon type to use as a filter for distance and units that can be hit by it. pred (function) – (optional) A predicate function that takes a `Unit` and returns `true` for units that satisfy the intended filter and `false` otherwise (can be a BWAPI.Filter unary filter). If omitted, no additional filter is used.
Returns:	The set of units within weapon range of this unit.
Return type:	`Unitset`

getClosestUnit([pred][, radius = 999999]) → unit¶

Retrieves the closest unit to this one.

Parameters:	pred (function) – (optional) A predicate function that takes a `Unit` and returns `true` for units that satisfy the intended filter and `false` otherwise (can be a BWAPI.Filter unary filter). If `pred` is omitted or `nil`, then the closest unit owned by any player will be returned. radius (number) – (optional) The maximum radius to check for the closest unit. For performance reasons, a developer can limit the radius that is checked. If omitted, then the entire map is checked.
Returns:	The closest unit that matches the predicate, or `nil` if no matching unit is found.
Return type:	`Unit`

hasNuke() → bool¶

Checks if the current unit is housing a Nuke.

This is only available for Nuclear Silos.

Returns:	`true` if this unit has a `Nuke` ready, and `false` if there is no `Nuke`.
Return type:	boolean

isAccelerating() → bool¶

Checks if the current unit is accelerating.

Returns:	`true` if this unit is accelerating, and `false` otherwise
Return type:	boolean

isAttacking() → bool¶

Checks if this unit is currently attacking something.

Returns:	`true` if this unit is attacking another unit, and `false` if it is not.
Return type:	boolean

isAttackFrame() → bool¶

Checks if this unit is currently playing an attack animation.

Issuing commands while this returns true may interrupt the unit’s next attack sequence.

Returns:	`true` if this unit is currently running an attack frame, and `false` if interrupting the unit is feasible.
Return type:	boolean

Note

This function is only available to some unit types, specifically those that play special animations when they attack.

isBeingConstructed() → bool¶

Checks if the current unit is being constructed.

This is mostly applicable to Terran structures which require an SCV to be constructing a structure.

Returns:	`true` if this is either a Protoss structure, Zerg structure, or Terran structure being constructed by an attached SCV, and `false` if this is either completed, not a structure, or has no SCV constructing it.
Return type:	boolean

isBeingGathered() → bool¶

Checks this Mineral Field or Refinery is currently being gathered from.

Returns:	`true` if this unit is a resource container and being harvested by a worker, and `false` otherwise
Return type:	boolean

isBeingHealed() → bool¶

Checks if this unit is currently being healed by a Medic or repaired by a SCV.

Returns:	`true` if this unit is being healed, and `false` otherwise.
Return type:	boolean

isBlind() → bool¶

Checks if this unit is currently blinded by a Medic ‘s Optical Flare ability.

Blinded units have reduced sight range and cannot detect other units.

Returns:	`true` if this unit is blind, and `false` otherwise
Return type:	boolean

isBraking() → bool¶

Checks if the current unit is slowing down to come to a stop.

Returns:	`true` if this unit is breaking, `false` if it has stopped or is still moving at full speed.
Return type:	boolean

isBurrowed() → bool¶

Checks if the current unit is burrowed, either using the Burrow ability, or is an armed Spider Mine.

Returns:	`true` if this unit is burrowed, and `false` otherwise
Return type:	boolean

See also

burrow(), unburrow()

isCarryingGas() → bool¶

Checks if this worker unit is carrying some vespene gas.

Returns:	`true` if this is a worker unit carrying vespene gas, and `false` if it is either not a worker, or not carrying gas.
Return type:	boolean

Example¶

local myUnits = BWAPI.Broodwar:self():getUnits()
for u in myUnits:iterator() do
  if u:isIdle() and (u:isCarryingGas() or u:isCarryingMinerals()) then
    u:returnCargo()
  end
end

Note

If this function returns a successful state, then the following function calls will also return a successful state: isCompleted(), getType():isWorker()

isCarryingMinerals() → bool¶

Checks if this worker unit is carrying some minerals.

Returns:	`true` if this is a worker unit carrying minerals, and `false` if it is either not a worker, or not carrying minerals.
Return type:	boolean

Example¶

local myUnits = BWAPI.Broodwar:self():getUnits()
for u in myUnits:iterator() do
  if u:isIdle() and (u:isCarryingGas() or u:isCarryingMinerals()) then
    u:returnCargo()
  end
end

Note

If this function returns a successful state, then the following function calls will also return a successful state: isCompleted(), getType():isWorker()

isCloaked() → bool¶

Checks if this unit is currently cloaked.

Returns:	`true` if this unit is cloaked, and `false` if it is visible.
Return type:	boolean

See also

cloak(), decloak()

isCompleted() → bool¶

Checks if this unit has finished being constructed, trained, morphed, or warped in, and can now receive orders.

Returns:	`true` if this unit is completed, and `false` if it is under construction or inaccessible.
Return type:	boolean

isConstructing() → bool¶

Checks if a unit is either constructing something or moving to construct something.

Returns:	`true` when a unit has been issued an order to build a structure and is moving to the build location, or is currently constructing something.
Return type:	boolean

isDefenseMatrixed() → bool¶

Checks if this unit has the Defensive Matrix effect.

Returns:	`true` if the `Defensive Matrix` ability was used on this unit, and `false` otherwise.
Return type:	boolean

isDetected() → bool¶

Checks if this unit is visible or revealed by a detector unit.

If this is false and isVisible is true, then the unit is only partially visible and requires a detector in order to be targetted.

Returns:	`true` if this unit is detected, and `false` if it needs a detector unit nearby in order to see it.
Return type:	boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: isVisible()

isEnsnared() → bool¶

Checks if the Queen ability Ensnare has been used on this unit.

Returns:	`true` if the unit is ensnared, and `false` if it is not
Return type:	boolean

isFlying() → bool¶

This macro function checks if this unit is in the air.

That is, the unit is either a flyer or a flying building.

Returns:	`true` if this unit is in the air, and `false` if it is on the ground
Return type:	boolean

See also

UnitType.isFlyer(), isLifted()

isFollowing() → bool¶

Checks if this unit is following another unit.

When a unit is following another unit, it simply moves where the other unit does, and does not attack enemies when it is following.

Returns:	`true` if this unit is following another unit, and `false` if it is not
Return type:	boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: isCompleted()

See also

follow(), getTarget()

isGatheringGas() → bool¶

Checks if this unit is currently gathering gas.

That is, the unit is either moving to a refinery, waiting to enter a refinery, harvesting from the refinery, or returning gas to a resource depot.

Returns:	`true` if this unit is harvesting gas, and `false` if it is not
Return type:	boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: isCompleted(), getType():isWorker()

See also

isCarryingGas()

isGatheringMinerals() → bool¶

Checks if this unit is currently harvesting minerals.

That is, the unit is either moving to a Mineral Field, waiting to mine, mining minerals, or returning minerals to a resource depot.

Returns:	`true` if this unit is gathering minerals, and `false` if it is not
Return type:	boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: isCompleted(), getType():isWorker()

See also

isCarryingMinerals()

isHallucination() → bool¶

Checks if this unit is a hallucination.

Hallucinations are created by the High Templar using the Hallucination ability. Enemy hallucinations are unknown if BWAPI.Flag.CompleteMapInformation is disabled. Hallucinations have a time limit until they are destroyed (see getRemoveTimer()).

Returns:	`true` if the unit is a hallucination and `false` otherwise.
Return type:	boolean

See also

getRemoveTimer()

isHoldingPosition() → bool¶

Checks if the unit is currently holding position.

A unit that is holding position will attack other units, but will not chase after them.

Returns:	`true` if this unit is holding position, and `false` if it is not.
Return type:	boolean

See also

holdPosition()

isIdle() → bool¶

Checks if this unit is running an idle order.

This function is particularly useful when checking for units that aren’t doing any tasks that you assigned.

A unit is considered idle if it is not doing any of the following:

Training
Constructing
Morphing
Researching
Upgrading

In addition to running one of the following orders:

PlayerGuard: Player unit idle.
Guard: Generic unit idle.
Stop
PickupIdle
Nothing: Structure/generic idle.
Medic: Medic idle.
Carrier: Carrier idle.
Reaver: Reaver idle.
Critter: Critter idle.
Neutral: Neutral unit idle.
TowerGuard: Turret structure idle.
Burrowed: Burrowed unit idle.
NukeTrain
Larva: Larva idle.

Example¶

local myUnits = BWAPI.Broodwar:self():getUnits()
for u in myUnits:iterator() do
  -- Order idle worker to gather from closest mineral field
  if u:getType():isWorker() and u:isIdle() then
    u:gather( u:getClosestUnit( BWAPI.Filter.IsMineralField ) )
  end
end

Returns:	`true` if this unit is idle, and `false` if this unit is performing any action, such as moving or attacking
Return type:	boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: isCompleted()

See also

stop()

isInterruptible() → bool¶

Checks if the unit can be interrupted.

Returns:	`true` if this unit can be interrupted, or `false` if this unit is uninterruptable
Return type:	boolean

isInvincible() → bool¶

Checks the invincibility state for this unit.

Returns:	`true` if this unit is currently invulnerable, and `false` if it is vulnerable
Return type:	boolean

isInWeaponRange(target) → bool¶

Checks if the target unit can immediately be attacked by this unit in the current frame.

Parameters:	target (BWAPI.Unit) – The target unit to use in this check.
Returns:	`true` if `target` is within weapon range of this unit’s appropriate weapon, and `false` if `target` is invalid, inaccessible, too close, too far, or this unit does not have a weapon that can attack `target`.
Return type:	boolean

isIrradiated() → bool¶

Checks if this unit is irradiated by a Science Vessel ‘s Irradiate ability.

Example¶

local myUnits = BWAPI.Broodwar:self():getUnits()
for u in myUnits:iterator() do
  if u:isIrradiated() and u:getIrradiateTimer > 50 and BWAPI.Broodwar:self():hasResearched(BWAPI.TechTypes.Restoration) then
    local medicPred = function(x)
      return BWAPI.Filter.GetType(x) == BWAPI.UnitTypes.Terran_Medic and BWAPI.Filter.Energy(x) >= BWAPI.TechTypes.Restoration:energyCost()
    end
    local medic = u:getClosestUnit( medicPred )
    if medic then
      medic:useTech(BWAPI.TechTypes.Restoration, u)
    end
  end
end

Returns:	`true` if this unit is irradiated, and `false` otherwise
Return type:	boolean

See also

getIrradiateTimer()

isLifted() → bool¶

Checks if this unit is a Terran building and lifted off the ground.

This function generally implies getType():isBuilding() and isCompleted() both return true.

Returns:	`true` if this unit is a `Terran` structure lifted off the ground.
Return type:	boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: isCompleted(), getType():isFlyingBuilding()

See also

isFlying()

isLoaded() → bool¶

Checks if this unit is currently loaded into another unit such as a Transport (Dropship, Shuttle, Overlord ).

Returns:	`true` if this unit is loaded in another one, and `false` otherwise
Return type:	boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: isCompleted()

See also

load(), unload(), unloadAll()

isLockedDown() → bool¶

Checks if this unit is currently locked by a Ghost.

Returns:	`true` if this unit is locked down, and `false` otherwise
Return type:	boolean

See also

getLockdownTimer()

isMaelstrommed() → bool¶

Checks if this unit has been maelstrommed by a Dark Archon.

Returns:	`true` if this unit is maelstrommed, and `false` otherwise
Return type:	boolean

See also

getMaelstromTimer()

isMorphing() → bool¶

Finds out if the current unit is morphing or not.

Zerg units and structures often have the ability to morph into different types of units. This function allows you to identify when this process is occurring.

Returns:	`true` if the unit is currently morphing, and `false` if the unit is not morphing.
Return type:	boolean

isMoving() → bool¶

Checks if this unit is currently moving.

Returns:	`true` if this unit is moving, and `false` if it is not
Return type:	boolean

See also

stop()

isParasited() → bool¶

Checks if this unit has been parasited by some other player.

Returns:	`true` if this unit is inflicted with `Parasite`, and `false` if it is clean
Return type:	boolean

isPatrolling() → bool¶

Checks if this unit is patrolling between two positions.

Returns:	`true` if this unit is patrolling and `false` if it is not
Return type:	boolean

See also

patrol()

isPlagued() → bool¶

Checks if this unit has been been plagued by a Defiler.

Returns:	`true` if this unit is inflicted with `Plague` and is taking damage, and `false` if it is clean
Return type:	boolean

See also

getPlagueTimer()

isRepairing() → bool¶

Checks if this unit is repairing or moving to repair another unit.

This is only applicable to SCVs.

Returns:	`true` if this unit is currently repairing or moving to `repair` another unit, and `false` if it is not
Return type:	boolean

isResearching() → bool¶

Checks if this unit is a structure that is currently researching a technology.

See TechTypes for a complete list of technologies in Broodwar.

Returns:	`true` if this structure is researching a technology, `false` otherwise
Return type:	boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: exists(), isCompleted(), getType():isBuilding()

isSelected() → bool¶

Checks if this unit has been selected in the user interface.

This function is only available if the flag BWAPI.Flag.UserInput is enabled.

Returns:	`true` if this unit is currently selected, and `false` if this unit is not selected
Return type:	boolean

See also

Game.getSelectedUnits()

isSieged() → bool¶

Checks if this unit is currently sieged.

This is only applicable to Siege Tanks.

Returns:	`true` if the unit is in siege mode, and `false` if it is either not in siege mode or not a `Siege Tank`
Return type:	boolean

See also

siege(), unsiege()

isStartingAttack() → bool¶

Checks if the unit is starting to attack.

Returns:	`true` if this unit is starting an attack.
Return type:	boolean

isStasised() → bool¶

Checks if this unit is inflicted with Stasis Field by an Arbiter.

Returns:	`true` if this unit is locked in a `Stasis Field` and is unable to move, and `false` if it is free.
Return type:	boolean

Note

This function does not necessarily imply that the unit is invincible, since there is a feature in the Use Map Settings game type that allows stasised units to be vulnerable.

See also

getStasisTimer()

isStimmed() → bool¶

Checks if this unit is currently under the influence of a Stim Packs.

Returns:	`true` if this unit has used a stim pack, `false` otherwise
Return type:	boolean

See also

getStimTimer()

isStuck() → bool¶

Checks if this unit is currently trying to resolve a collision by randomly moving around.

Returns:	`true` if this unit is currently stuck and trying to resolve a collision, and `false` if this unit is free
Return type:	boolean

isTraining() → bool¶

Checks if this unit is training a new unit.

For example, a Barracks training a Marine.

Note

It is possible for a unit to remain in the training queue with no progress. In that case, this function will return false because of supply or unit count limitations.

Returns:	`true` if this unit is currently training another unit, and `false` otherwise.

isUnderAttack() → bool¶

Checks if the current unit is being attacked.

Has a small delay before this returns false again when the unit is no longer being attacked.

Returns:	`true` if this unit has been attacked within the past few frames, and `false` if it has not
Return type:	boolean

isUnderDarkSwarm() → bool¶

Checks if this unit is under the cover of a Dark Swarm.

Returns:	`true` if this unit is protected by a `Dark Swarm`, and `false` if it is not
Return type:	boolean

isUnderDisruptionWeb() → bool¶

Checks if this unit is currently being affected by a Disruption Web.

Returns:	`true` if this unit is under the effects of `Disruption Web`.
Return type:	boolean

isUnderStorm() → bool¶

Checks if this unit is currently taking damage from a Psionic Storm.

Returns:	`true` if this unit is losing hit points from a `Psionic Storm`, and `false` otherwise.
Return type:	boolean

isPowered() → bool¶

Checks if this unit has power.

Most structures are powered by default, but Protoss structures require a Pylon to be powered and functional.

Returns:	`true` if this unit has power or is inaccessible, and `false` if this unit is unpowered.
Return type:	boolean

isUpgrading() → bool¶

Checks if this unit is a structure that is currently upgrading an upgrade.

See BWAPI.UpgradeTypes for a full list of upgrades in Broodwar.

Returns:	`true` if this structure is upgrading, `false` otherwise
Return type:	boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: exists(), isCompleted(), getType():isBuilding()

isVisible([player]) → bool¶

Checks if this unit is visible.

Parameters:	player (BWAPI.Player) – (optional) The player to check visibility for. If this parameter is omitted, then the BWAPI player obtained from `Game.self()` will be used.
Returns:	`true` if this unit is visible to the specified `player`, and `false` if it is not.
Return type:	boolean

Note

If the BWAPI.Flag.CompleteMapInformation flag is enabled, existing units hidden by the fog of war will be accessible, but isVisible() will still return false.

See also

exists()

isTargetable() → bool¶

Performs some cheap checks to attempt to quickly detect whether the unit is unable to be targetted as the target unit of an unspecified command.

Returns:	`true` if BWAPI was unable to determine whether the unit can be a target, and `false` if an error occurred and the unit can not be a target.
Return type:	boolean

issueCommand(command) → wasIssued¶

This function issues a command to the unit, however it is used for interfacing only, and is recommended to use one of the more specific command functions when writing an AI.

Parameters:	command (BWAPI.UnitCommand) – The command to be issued
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

attack(target[, shiftQueueCommand = false]) → wasIssued¶

Orders the unit(s) to attack move to the specified position or attack the specified unit.

Parameters:	target (`BWAPI.Position` or `BWAPI.Unit`) – Can be either a `Position` or `Unit`. If a Position is used, the unit will perform an Attack Move command. shiftQueueCommand (bool) – (optional) If this value is true, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

A Medic will use Heal Move instead of attack.

build(type[, target]) → wasIssued¶

Orders the worker unit(s) to construct a structure at a target position.

Parameters:	type (BWAPI.UnitType) – The `UnitType` to build. target (BWAPI.TilePosition) – A TilePosition to specify the build location, specifically the upper-left corner of the location. If the target is not specified, then the function call will be redirected to the train command.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

Note

You must have sufficient resources and meet the necessary requirements in order to build a structure.

buildAddon(type) → wasIssued¶

Orders the Terran structure(s) to construct an add-on.

Parameters:	type (BWAPI.UnitType) – The add-on `UnitType` to construct.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

Note

You must have sufficient resources and meet the necessary requirements in order to build a structure.

train([type]) → wasIssued¶

Orders the unit(s) to add a UnitType to its training queue, or morphs into the UnitType if it is Zerg.

Parameters:	type (BWAPI.UnitType) – The `UnitType` to train. If the type is not specified, then this function will have no effect unless this unit is a Carrier or Reaver, in which case the type will default to `Interceptors` or `Scarabs`.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

Note

You must have sufficient resources, supply, and meet the necessary requirements in order to train a unit.

Note

This command is also used for training Interceptors and Scarabs.

Note

If you call this using a Hatchery, Lair, or Hive, then it will automatically pass the command to one of its Larvae.

morph(type) → wasIssued¶

Orders the unit(s) to morph into a different UnitType.

Parameters:	type (BWAPI.UnitType) – The `UnitType` to morph into.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

research(tech) → wasIssued¶

Orders the unit to research the given tech type.

Parameters:	tech (BWAPI.TechType) – The `TechType` to research.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

upgrade(upgrade) → wasIssued¶

Orders the unit to upgrade the given upgrade type.

Parameters:	upgrade (BWAPI.UpgradeType) – The `UpgradeType` to upgrade.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

setRallyPoint(target) → wasIssued¶

Orders the unit to set its rally position to the specified position or unit.

Parameters:	target (`BWAPI.Position` or `BWAPI.Unit`) – Can be either a `Position` or `Unit`. The target position or target unit that this structure will rally to.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

move(target[, shiftQueueCommand = false]) → wasIssued¶

Orders the unit to move from its current position to the specified position.

Parameters:	target (BWAPI.Position) – The target position to move to. shiftQueueCommand (boolean) – (optional) If this value is `true`, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

See also

isMoving(), canMove()

patrol(target[, shiftQueueCommand = false]) → wasIssued¶

Orders the unit to patrol between its current position and the specified position.

While patrolling, units will attack and chase enemy units that they encounter, and then return to its patrol route. Medics will automatically heal units and then return to their patrol route.

Parameters:	target (BWAPI.Position) – The target position to patrol to. shiftQueueCommand (boolean) – (optional) If this value is `true`, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

See also

isPatrolling(), canPatrol()

holdPosition([shiftQueueCommand = false]) → wasIssued¶

Orders the unit to hold its position.

Parameters:	shiftQueueCommand (boolean) – (optional) If this value is true, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

stop([shiftQueueCommand = false]) → wasIssued¶

Orders the unit to stop.

Parameters:	shiftQueueCommand (boolean) – (optional) If this value is true, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

See also

canStop(), isIdle()

follow(target[, shiftQueueCommand = false]) → wasIssued¶

Orders the unit to follow the specified unit.

Units that are following other units will not perform any other actions such as attacking. They will ignore attackers.

Parameters:	target (BWAPI.Unit) – The target unit to start following. shiftQueueCommand (boolean) – (optional) If this value is true, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

gather(target[, shiftQueueCommand = false]) → wasIssued¶

Orders the unit to gather the specified unit (must be mineral or refinery type).

Parameters:	target (BWAPI.Unit) – The target unit to gather from. shiftQueueCommand (boolean) – (optional) If this value is true, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

returnCargo([shiftQueueCommand = false]) → wasIssued¶

Orders the unit to return its cargo to a nearby resource depot such as a Command Center.

Only workers that are carrying minerals or gas can be ordered to return cargo.

Parameters:	shiftQueueCommand (boolean) – (optional) If this value is true, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

repair(target[, shiftQueueCommand = false]) → wasIssued¶

Orders the unit to repair the specified unit.

Only Terran SCVs can be ordered to repair, and the target must be a mechanical Terran unit or building.

Parameters:	target (BWAPI.Unit) – The target unit to repair. shiftQueueCommand (boolean) – (optional) If this value is true, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

See also

isRepairing(), canRepair()

burrow() → wasIssued¶

Orders the unit to burrow.

Either the unit must be a Lurker, or the unit must be a Zerg ground unit that is capable of Burrowing, and Burrow technology must be researched.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

unburrow() → wasIssued¶

Orders a burrowed unit to unburrow.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

cloak() → wasIssued¶

Orders the unit to cloak.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

decloak() → wasIssued¶

Orders a cloaked unit to decloak.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

siege() → wasIssued¶

Orders the unit to siege.

Only works for Siege Tanks.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

See also

unsiege(), isSieged(), canSiege()

unsiege() → wasIssued¶

Orders the unit to unsiege.

Only works for sieged Siege Tanks.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

See also

siege(), isSieged(), canUnsiege()

lift() → wasIssued¶

Orders the unit to lift.

Only works for liftable Terran structures.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

See also

land(), isLifted(), canLift()

land(target) → wasIssued¶

Orders the unit to land.

Only works for Terran structures that are currently lifted.

Parameters:	target`` (BWAPI.TilePosition) – The tile position to land this structure at.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

See also

lift(), isLifted(), canLand()

load(target[, shiftQueueCommand = false]) → wasIssued¶

Orders the unit to load the target unit.

Only works if this unit is a Transport (Dropship, Shuttle, Overlord ) or Bunker type.

Parameters:	target (BWAPI.Unit) – The target unit to load into this Transport (`Dropship`, `Shuttle`, `Overlord` ) or `Bunker`. shiftQueueCommand (boolean) – (optional) If this value is true, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

unload(target) → wasIssued¶

Orders the unit to unload the target unit.

Only works for Transports (Dropships, Shuttles, Overlords ) and Bunkers.

Parameters:	target (BWAPI.Unit) – Unloads the target unit from this Transport(`Dropship`, `Shuttle`, `Overlord` ) or `Bunker`.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

unloadAll([shiftQueueCommand = false]) → wasIssued¶

Orders the unit to unload all loaded units at the unit’s current position.

Only works for Transports (Dropships, Shuttles, Overlords ) and Bunkers.

Parameters:	shiftQueueCommand (boolean) – (optional) If this value is true, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

unloadAll(target[, shiftQueueCommand = false]) → wasIssued

Orders the unit to unload all loaded units at the specified location.

Only works for Transports (Dropships, Shuttles, Overlords )

Important

Not applicable to Bunkers.

Parameters:	target (BWAPI.Position) – The target position to unload the units at. shiftQueueCommand (boolean) – (optional) If this value is true, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

rightClick(target[, shiftQueueCommand = false]) → wasIssued¶

Works like the right click in the GUI.

Parameters:	target (`BWAPI.Position` or `BWAPI.Unit`) – Can be either a `Position` or `Unit`. The target position or target unit to right click. shiftQueueCommand (boolean) – (optional) If this value is true, then the order will be queued instead of immediately executed. If this value is omitted, then the order will be executed immediately by default.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

haltConstruction() → wasIssued¶

Orders a SCV to stop constructing a structure.

This leaves the structure in an incomplete state until it is either cancelled, razed, or completed by another SCV.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

cancelConstruction() → wasIssued¶

Orders this unit to cancel and refund itself from begin constructed.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

cancelAddon() → wasIssued¶

Orders this unit to cancel and refund an add-on that is being constructed.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

See also

canCancelAddon(), buildAddon()

cancelTrain([slot = -2]) → wasIssued¶

Orders the unit to remove the specified unit from its training queue.

Important

The first slot has an index of 1. See the differences between the C++ and Lua implementations of this function for more information.

Parameters:	slot (number) – (optional) Identifies the slot that will be cancelled. If the specified value is at least 1, then the unit in the corresponding slot from the list provided by `getTrainingQueue()` will be cancelled. If the slot is either omitted or `-2`, then the last slot is cancelled.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

Zero and negative values other than -2 have no effect.

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

cancelMorph() → wasIssued¶

Orders this unit to cancel and refund a unit that is morphing.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

cancelResearch() → wasIssued¶

Orders this unit to cancel and refund a research that is in progress.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

cancelUpgrade() → wasIssued¶

Orders this unit to cancel and refund an upgrade that is in progress.

Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

useTech([tech][, target]) → wasIssued¶

Orders the unit to use a technology.

Parameters:	tech (BWAPI.TechType) – The technology type to use. target (`BWAPI.Position` or `BWAPI.Unit`) – (optional) Can be either a `Position` or `Unit`. If specified, indicates the target location or unit to use the tech on. If unspecified, causes the `tech` to be used without a target (i.e. `Stim Packs`).
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

placeCOP(target) → bool¶

Moves a Flag Beacon to a different location.

This is only used for Capture The Flag or Use Map Settings game types.

Parameters:	target (BWAPI.TilePosition) – The target tile position to place the `Flag Beacon`.
Returns:	`true` if the command was passed to Broodwar, and `false` if BWAPI determined that the command would fail.
Return type:	boolean

Note

There is a small chance for a command to fail after it has been passed to Broodwar.

Note

This command is only available for the first 10 minutes of the game, as in Broodwar.

See also

canPlaceCOP

canIssueCommand(command[, checkCanUseTechPositionOnPositions = true, checkCanUseTechUnitOnUnits = true, checkCanBuildUnitType = true, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool¶

Checks whether the unit is able to execute the given command.

If you are calling this function repeatedly (e.g. to generate a collection of valid commands), you can avoid repeating the same kinds of checks by specifying false for some of the optional boolean arguments. Make sure that the state hasn’t changed since the check was done though (eg a new frame/event, or a command issued). Also see the more specific functions.

Parameters:	command (BWAPI.UnitCommand) – A `UnitCommand` to check. checkCanUseTechPositionOnPositions (boolean) – Only used if the command type is `BWAPI.UnitCommandTypes.Use_Tech_Position`. A boolean for whether to perform cheap checks for whether the unit is unable to target any positions using the command’s `TechType` (i.e. regardless of what the other command parameters are). You can set this to `false` if you know this check has already just been performed. checkCanUseTechUnitOnUnits (boolean) – Only used if the command type is `BWAPI.UnitCommandTypes.Use_Tech_Unit`. A boolean for whether to perform cheap checks for whether the unit is unable to target any units using the command’s `TechType` (i.e. regardless of what the other command parameters are). You can set this to `false` if you know this check has already just been performed. checkCanBuildUnitType (boolean) – Only used if the command type is `BWAPI.UnitCommandTypes.Build`. A boolean for whether to perform cheap checks for whether the unit is unable to build the specified `UnitType` (i.e. regardless of what the other command parameters are). You can set this to `false` if you know this check has already just been performed. checkCanTargetUnit (boolean) – Only used for command types that can target a unit. A boolean for whether to perform `canTargetUnit()` as a check. You can set this to `false` if you know this check has already just been performed. checkCanIssueCommandType (boolean) – A boolean for whether to perform `Unit.canIssueCommandType()` as a check. You can set this to `false` if you know this check has already just been performed. checkCommandibility (boolean) – A boolean for whether to perform `canCommand()` as a check. You can set this to `false` if you know this check has already just been performed.
Returns:	`true` if BWAPI determined that the command is valid, or `false` if an error occurred and the command is invalid
Return type:	boolean

canIssueCommandGrouped(command[, checkCanUseTechPositionOnPositions = true, checkCanUseTechUnitOnUnits = true, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibilityGrouped = true, checkCommandibility = true]) → bool¶

Checks whether the unit is able to execute the given command as part of a Unitset (even if none of the units in the Unitset are able to execute the command individually).

The reason this function exists is because some commands are valid for an individual unit but not for those individuals as a group (e.g. buildings, critters) and some commands are only valid for a unit if it is commanded as part of a unit group, e.g.:

attackMove/attackUnit for a Unitset, some of which can’t attack, e.g. High Templar. This is supported simply for consistency with BW’s behaviour - you could issue move command(s) individually instead.
attackMove/move/patrol/rightClickPosition for air unit(s) + e.g. Larva, as part of the air stacking technique. This is supported simply for consistency with BW’s behaviour - you could issue move/patrol/rightClickPosition command(s) for them individually instead.

Note

BWAPI allows the following special cases to command a unit individually (rather than only allowing it to be commanded as part of a Unitset). These commands are not available to a user in BW when commanding units individually, but BWAPI allows them for convenience:

attackMove for Medic, which is equivalent to Heal Move.
holdPosition for burrowed Lurker, for ambushes.
stop for Larva, to move it to a different side of the Hatchery / Lair / Hive (e.g. so that Drones morphed later morph nearer to minerals/gas).

canCommand() → bool¶

Performs some cheap checks to attempt to quickly detect whether the unit is unable to execute any commands (eg the unit is stasised).

Returns:	`true` if BWAPI was unable to determine whether the unit can be commanded, or `false` if an error occurred and the unit can not be commanded.
Return type:	boolean

canCommandGrouped([checkCommandibility = true]) → bool¶

Performs some cheap checks to attempt to quickly detect whether the unit is unable to execute any commands as part of a Unitset (eg buildings, critters).

Returns:	`true` if BWAPI was unable to determine whether the unit can be commanded grouped, or `false` if an error occurred and the unit can not be commanded grouped.
Return type:	boolean

canIssueCommandType(commandType[, checkCommandibility = true]) → bool¶

Performs some cheap checks to attempt to quickly detect whether the unit is unable to execute the given command type (i.e. regardless of what other possible command parameters could be).

Parameters:	commandType (BWAPI.UnitCommandType) – A `UnitCommandType`. checkCommandibility (boolean) – A boolean for whether to perform `canCommand()` as a check. You can set this to `false` if you know this check has already just been performed.
Returns:	`true` if BWAPI was unable to determine whether the command type is invalid, or `false` if an error occurred and the command type is invalid.
Return type:	boolean

canIssueCommandTypeGrouped(commandType[, checkCommandibilityGrouped = true, checkCommandibility = true]) → bool¶

Performs some cheap checks to attempt to quickly detect whether the unit is unable to execute the given command type (i.e.

regardless of what other possible command parameters could be) as part of a Unitset.

Parameters:

commandType (BWAPI.UnitCommandType) – A UnitCommandType.
checkCommandibilityGrouped (boolean) – A boolean for whether to perform canCommandGrouped() as a check. You can set this to false if you know this check has already just been performed.
checkCommandibility (boolean) – A boolean for whether to perform canCommand() as a check. You can set this to false if you know this check has already just been performed.

Returns:

true if BWAPI was unable to determine whether the command type is invalid, or false if an error occurred and the command type is invalid.

canTargetUnit(targetUnit[, checkCommandibility = true]) → bool¶

Performs some cheap checks to attempt to quickly detect whether the unit is unable to use the given unit as the target unit of an unspecified command.

Parameters:	targetUnit (BWAPI.Unit) – A target unit for an unspecified command. checkCommandibility (boolean) – A boolean for whether to perform `canCommand()` as a check. You can set this to `false` if you know this check has already just been performed.
Returns:	`true` if BWAPI was unable to determine whether the unit can target the given unit, or `false` if an error occurred and the unit can not target the given unit.

canAttack([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute an attack command to attack-move or attack a unit.

See also

Game.getLastError(), Unit.canIssueCommand(), attack(), canAttackMove(), canAttackUnit()

canAttack(target[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute an attack command to attack-move or attack a (non-null) unit.

Parameters:	target (`BWAPI.Position` or `BWAPI.Unit`) – Can be either a `Position` or `Unit`.

canAttackGrouped([checkCommandibilityGrouped = true, checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute an attack command to attack-move or attack a unit, as part of a Unitset.

See also

Game.getLastError(), Unit.canIssueCommandGrouped(), canAttack()

canAttackGrouped(target[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibilityGrouped = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute an attack command to attack-move or attack a (non-null) unit, as part of a Unitset.

Parameters:	target (`BWAPI.Position` or `BWAPI.Unit`) – Can be either a `Position` or `Unit`.

canAttackMove([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute an attack command to attack-move.

See also

Game.getLastError(), Unit.canIssueCommand(), attack()

canAttackMoveGrouped([checkCommandibilityGrouped = true, checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute an attack command to attack-move, as part of a Unitset.

See also

Game.getLastError(), Unit.canIssueCommandGrouped(), canAttackMove()

canAttackUnit([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute an attack command to attack a unit.

See also

Game.getLastError(), Unit.canIssueCommand(), attack()

canAttackUnit(targetUnit[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute an attack command to attack a unit.

Parameters:	targetUnit (BWAPI.Unit) –

canAttackUnitGrouped([checkCommandibilityGrouped = true, checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute an attack command to attack a unit, as part of a Unitset.

See also

Game.getLastError(), Unit.canIssueCommandGrouped(), canAttackUnit()

canAttackUnitGrouped(targetUnit[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibilityGrouped = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute an attack command to attack a unit, as part of a Unitset.

Parameters:	targetUnit (BWAPI.Unit) –

canBuild([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a build command.

See also

Game.getLastError(), Unit.canIssueCommand(), build()

canBuild(unitType[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Cheap checks for whether the unit is able to execute a build command for the given UnitType.

Parameters:	unitType (BWAPI.UnitType) –

canBuild(unitType, tilePos[, checkTargetUnitType = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a build command.

Parameters:	unitType (BWAPI.UnitType) – tilePos (BWAPI.TilePosition) –

canBuildAddon([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a buildAddon command.

See also

Game.getLastError(), Unit.canIssueCommand(), buildAddon()

canBuildAddon(unitType[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a buildAddon command.

Parameters:	unitType (BWAPI.UnitType) –

canTrain([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a train command.

See also

Game.getLastError(), Unit.canIssueCommand(), train()

canTrain(unitType[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a train command.

Parameters:	unitType (BWAPI.UnitType) –

canMorph([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a morph command.

See also

Game.getLastError(), Unit.canIssueCommand(), morph()

canMorph(unitType[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a morph command.

Parameters:	unitType (BWAPI.UnitType) –

canResearch([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a research command.

See also

Game.getLastError(), Unit.canIssueCommand(), research()

canResearch(type[, checkCanIssueCommandType = true]) → bool

Checks whether the unit is able to execute a research command.

Parameters:	type (BWAPI.TechType) –

canUpgrade([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute an upgrade command.

See also

Game.getLastError(), Unit.canIssueCommand(), upgrade()

canUpgrade(type[, checkCanIssueCommandType = true]) → bool

Checks whether the unit is able to execute an upgrade command.

Parameters:	type (BWAPI.UpgradeType) –

canSetRallyPoint([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a setRallyPoint command to a position or unit.

See also

Game.getLastError(), Unit.canIssueCommand(), setRallyPoint(), canSetRallyPosition(), canSetRallyUnit().

canSetRallyPoint(target[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a setRallyPoint command to a position or (non-null) unit.

Parameters:	target (`BWAPI.Position` or `BWAPI.Unit`) – Can be either a `Position` or `Unit`.

canSetRallyPosition([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a setRallyPoint command to a position.

See also

Game.getLastError(), Unit.canIssueCommand(), setRallyPoint()

canSetRallyUnit([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a setRallyPoint command to a unit.

See also

Game.getLastError(), Unit.canIssueCommand(), setRallyPoint()

canSetRallyUnit(targetUnit[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a setRallyPoint command to a unit.

Parameters:	targetUnit (BWAPI.Unit) –

canMove([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a move command.

See also

Game.getLastError(), Unit.canIssueCommand(), move()

canMoveGrouped([checkCommandibilityGrouped = true, checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a move command, as part of a Unitset.

See also

Game.getLastError(), Unit.canIssueCommandGrouped(), canMove()

canPatrol([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a patrol command.

See also

Game.getLastError(), Unit.canIssueCommand(), patrol()

canPatrolGrouped([checkCommandibilityGrouped = true, checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a patrol command, as part of a Unitset.

See also

Game.getLastError(), Unit.canIssueCommandGrouped(), canPatrol()

canFollow([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a follow command.

See also

Game.getLastError(), Unit.canIssueCommand(), follow()

canFollow(targetUnit[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a follow command.

Parameters:	targetUnit (BWAPI.Unit) –

canGather([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a gather command.

See also

Game.getLastError(), Unit.canIssueCommand(), gather()

canGather(targetUnit[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a gather command.

Parameters:	targetUnit (BWAPI.Unit) –

canReturnCargo([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a returnCargo command.

See also

Game.getLastError(), Unit.canIssueCommand(), returnCargo()

canHoldPosition([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a holdPosition command.

See also

Game.getLastError(), Unit.canIssueCommand(), holdPosition()

canStop([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a stop command.

See also

Game.getLastError(), Unit.canIssueCommand(), stop()

canRepair([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a repair command.

See also

Game.getLastError(), Unit.canIssueCommand(), repair()

canRepair(targetUnit[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a repair command.

Parameters:	targetUnit (BWAPI.Unit) –

canBurrow([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a burrow command.

See also

Game.getLastError(), Unit.canIssueCommand(), burrow()

canUnburrow([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute an unburrow command.

See also

Game.getLastError(), Unit.canIssueCommand(), unburrow()

canCloak([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a cloak command.

See also

Game.getLastError(), Unit.canIssueCommand(), cloak()

canDecloak([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a decloak command.

See also

Game.getLastError(), Unit.canIssueCommand(), decloak()

canSiege([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a siege command.

See also

Game.getLastError(), Unit.canIssueCommand(), siege()

canUnsiege([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute an unsiege command.

See also

Game.getLastError(), Unit.canIssueCommand(), unsiege()

canLift([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a lift command.

See also

Game.getLastError(), Unit.canIssueCommand(), lift()

canLand([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a land command.

See also

Game.getLastError(), Unit.canIssueCommand(), land()

canLand(target[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a land command.

Parameters:	target (BWAPI.TilePosition) –

canLoad(checkCommandibility = true) → bool¶: Cheap checks for whether the unit is able to execute a load command.

See also

Game.getLastError(), Unit.canIssueCommand(), load()

canLoad(targetUnit[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a load command.

Parameters:	targetUnit (BWAPI.Unit) –

canUnloadWithOrWithoutTarget([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute an unload command or unloadAll at current position command or unloadAll at a different position command.

See also

Game.getLastError(), Unit.canIssueCommand(), unload(), unloadAll()

canUnloadAtPosition(target[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool¶

Cheap checks for whether the unit is able to execute an unload command or unloadAll at current position command or unloadAll at a different position command, for a given position.

Parameters:	target (BWAPI.Position) –

canUnload([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute an unload command.

See also

Game.getLastError(), Unit.canIssueCommand(), unload()

canUnload(targetUnit[, checkCanTargetUnit = true, checkPosition = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute an unload command.

Parameters:	targetUnit (BWAPI.Unit) –

canUnloadAll([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute an unloadAll command for the current position.

See also

Game.getLastError(), Unit.canIssueCommand(), unloadAll()

canUnloadAllPosition([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute an unloadAll command for a different position.

See also

Game.getLastError(), Unit.canIssueCommand(), unloadAll()

canUnloadAllPosition(target[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute an unloadAll command for a different position.

Parameters:	target (BWAPI.Position) –

canRightClick([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a rightClick command to a position or unit.

See also

Game.getLastError(), Unit.canIssueCommand(), rightClick(), canRightClickPosition(), canRightClickUnit().

canRightClick(target[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a rightClick command to a position or (non-null) unit.

Parameters:	target (`BWAPI.Position` or `BWAPI.Unit`) – Can be either a `Position` or `Unit`.

canRightClickGrouped([checkCommandibilityGrouped = true, checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a rightClick command to a position or unit, as part of a Unitset.

See also

Game.getLastError(), Unit.canIssueCommandGrouped(), canRightClickUnit()

canRightClickGrouped(target[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibilityGrouped = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a rightClick command to a position or (non-null) unit, as part of a Unitset.

Parameters:	target (`BWAPI.Position` or `BWAPI.Unit`) – Can be either a `Position` or `Unit`.

canRightClickPosition([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a rightClick command for a position.

See also

Game.getLastError(), Unit.canIssueCommand(), rightClick()

canRightClickPositionGrouped([checkCommandibilityGrouped = true, checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a rightClick command for a position, as part of a Unitset.

See also

Game.getLastError(), Unit.canIssueCommandGrouped(), canRightClick()

canRightClickUnit([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a rightClick command to a unit.

See also

Game.getLastError(), Unit.canIssueCommand(), rightClick()

canRightClickUnit(targetUnit[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a rightClick command to a unit.

Parameters:	targetUnit (BWAPI.Unit) –

canRightClickUnitGrouped([checkCommandibilityGrouped = true, checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a rightClick command to a unit, as part of a Unitset.

See also

Game.getLastError(), Unit.canIssueCommandGrouped(), canRightClickUnit()

canRightClickUnitGrouped(targetUnit[, checkCanTargetUnit = true, checkCanIssueCommandType = true, checkCommandibilityGrouped = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a rightClick command to a unit, as part of a Unitset.

Parameters:	targetUnit (BWAPI.Unit) –

canHaltConstruction([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a haltConstruction command.

See also

Game.getLastError(), Unit.canIssueCommand(), haltConstruction()

canCancelConstruction([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a cancelConstruction command.

See also

Game.getLastError(), Unit.canIssueCommand(), cancelConstruction()

canCancelAddon([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a cancelAddon command.

See also

Game.getLastError(), Unit.canIssueCommand(), cancelAddon()

canCancelTrain([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a cancelTrain command for any slot.

See also

Game.getLastError(), Unit.canIssueCommand(), cancelTrain()

canCancelTrainSlot([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a cancelTrain command for an unspecified slot.

See also

Game.getLastError(), Unit.canIssueCommand(), cancelTrain()

canCancelTrainSlot(slot[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a cancelTrain command for a specified slot.

Parameters:	slot (number) –

Important

The first slot has an index of 1. See cancelTrain() and the differences between the C++ and Lua implementations of this function for more information.

canCancelMorph([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a cancelMorph command.

See also

Game.getLastError(), Unit.canIssueCommand(), cancelMorph()

canCancelResearch([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a cancelResearch command.

See also

Game.getLastError(), Unit.canIssueCommand(), cancelResearch()

canCancelUpgrade([checkCommandibility = true]) → bool¶: Checks whether the unit is able to execute a cancelUpgrade command.

See also

Game.getLastError(), Unit.canIssueCommand(), cancelUpgrade()

canUseTechWithOrWithoutTarget([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a useTech command without a target or or a useTech command with a target position or a useTech command with a target unit.

See also

Game.getLastError(), Unit.canIssueCommand(), useTech()

canUseTechWithOrWithoutTarget(tech[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Cheap checks for whether the unit is able to execute a useTech command without a target or or a useTech command with a target position or a useTech command with a target unit, for a given TechType.

Parameters:	tech (BWAPI.TechType) –

canUseTech(tech[, target, checkCanTargetUnit = true, checkTargetsType = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool¶

Checks whether the unit is able to execute a useTech command for a specified position or unit (only specify nullptr if the TechType does not target another position/unit).

Parameters:	tech (BWAPI.TechType) – target (`BWAPI.Position` or `BWAPI.Unit`) – Can be either a `Position` or `Unit`.

canUseTechWithoutTarget(tech[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool¶

Checks whether the unit is able to execute a useTech command without a target.

Parameters:	tech (BWAPI.TechType) –

canUseTechUnit(tech[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool¶

Cheap checks for whether the unit is able to execute a useTech command with an unspecified target unit.

Parameters:	tech (BWAPI.TechType) –

canUseTechUnit(tech, targetUnit[, checkCanTargetUnit = true, checkTargetsUnits = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a useTech command with a target unit.

Parameters:	tech (BWAPI.TechType) – targetUnit (BWAPI.Unit) –

canUseTechPosition(tech[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool¶

Checks whether the unit is able to execute a useTech command with an unspecified target position.

Parameters:	tech (BWAPI.TechType) –

canUseTechPosition(tech, target[, checkTargetsPositions = true, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a useTech command with a target position.

Parameters:	tech (BWAPI.TechType) – target (BWAPI.Position) –

canPlaceCOP([checkCommandibility = true]) → bool¶: Cheap checks for whether the unit is able to execute a placeCOP command.

See also

Game.getLastError(), Unit.canIssueCommand(), placeCOP()

canPlaceCOP(target[, checkCanIssueCommandType = true, checkCommandibility = true]) → bool

Checks whether the unit is able to execute a placeCOP command.

Parameters:	target (BWAPI.TilePosition) –

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.