Unitset¶

class BWAPI.Unitset¶

The Unitset is a container for a set of Unit objects.

It is typically used for groups of units instead of having to manage each Unit individually.

See also

Unit

Constructors

Unitset()¶: Default constructor.

Unitset(set)

Copy constructor.

Parameters:	set (BWAPI.Unitset) – The Unitset to copy.

Unitset(tbl)

Constructor to convert a Lua table to a set. Any values in the table that are of type Unit are added to the set.

Parameters:	tbl (table) – A table containing `Unit` objects.

Member Functions

issueCommand(command) → boolean¶

This function issues a command to the unit(s), 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) – A `UnitCommand` containing command parameters such as the type, position, target, etc.
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]) → boolean¶

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`. A Position or a Unit to designate as the target. If a Position is used, the unit will perform an Attack Move command. 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.

Note

A Medic will use Heal Move instead of attack.

build(type[, target = TilePositions.None]) → boolean¶

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) → boolean¶

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) → boolean¶

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.
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 Zerg_Hatchery, Zerg_Lair, or Zerg_Hive, then it will automatically pass the command to one of its Zerg_Larva.

morph(type) → boolean¶

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.

setRallyPoint(target) → boolean¶

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.

See also

getRallyPosition(), getRallyUnit(), canSetRallyPoint(), canSetRallyPosition(), canSetRallyUnit()

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

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.

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

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

holdPosition([shiftQueueCommand = false]) → boolean¶

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]) → boolean¶

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.

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

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]) → boolean¶

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]) → boolean¶

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]) → boolean¶

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

burrow() → boolean¶

Orders the unit to burrow.

Either the unit must be a Zerg_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.
Return type:	boolean

Note

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

See also

unburrow()

unburrow() → boolean¶

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

Note

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

See also

burrow()

cloak() → boolean¶

Orders the unit to cloak.

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

decloak()

decloak() → boolean¶

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

Note

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

See also

cloak()

siege() → boolean¶

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

Note

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

See also

unsiege()

unsiege() → boolean¶

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

Note

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

See also

siege()

lift() → boolean¶

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

Note

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

See also

Unit.land()

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

Orders the unit to load the target unit.

Only works if this unit is a Transport (Terran_Dropship, Protoss_Shuttle, Zerg_Overlord ) or Terran_Bunker type.

Parameters:	target (BWAPI.Unit) – The target unit to load into this Transport(`Terran_Dropship`, `Protoss_Shuttle`, `Zerg_Overlord` ) or `Terran_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.

See also

unload(), unloadAll(), getLoadedUnits()

unloadAll([shiftQueueCommand = false]) → boolean¶

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

Only works for Transports (Terran_Dropship, Protoss_Shuttle, Zerg_Overlord) and Terran_Bunker.

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

load(), getLoadedUnits()

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

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

Only works for Transports (Terran_Dropship, Protoss_Shuttle, Zerg_Overlord). 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.

See also

load(), getLoadedUnits()

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

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() → boolean¶

Orders a Terran_SCV to stop constructing a structure.

This leaves the structure in an incomplete state until it is either cancelled, razed, or completed by another Terran_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() → boolean¶

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() → boolean¶

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

Note

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

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

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

Important

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

Parameters:	slot (int) – (optional) Identifies the slot that will be cancelled. If the specified value is at least 1, then the unit in the corresponding slot will be cancelled. If the value 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

The value of slot is passed directly to Broodwar. Other negative values have no effect.

See also

train()

cancelMorph() → boolean¶

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.

See also

morph()

cancelResearch() → boolean¶

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() → boolean¶

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 = nil]) → boolean¶

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

See also

TechTypes

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

Retrieves the closest unit relative to the value of getPosition().

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). Defaults to `nil`, which means no filter. radius (int) – (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:	`BWAPI.Unit`

getInterceptors() → Unitset¶

Creates a single set containing all the Interceptors of all Carriers in this set.

Returns:	The set of all `Interceptors` .
Return type:	`BWAPI.Unitset`

See also

Unit.getInterceptors()

getLarva() → Unitset¶

Creates a single set containing all the Zerg_Larva of all Hatcheries, Lairs, and Hives in this set.

Returns:	The set of all `Zerg_Larva` .
Return type:	`BWAPI.Unitset`

See also

Unit.getLarva()

getLoadedUnits() → Unitset¶

Creates a single set containing all units that are loaded into units of this set.

Returns:	The set of all loaded units.
Return type:	`BWAPI.Unitset`

See also

Unit.getLoadedUnits()

getPosition() → Position¶

Calculates the average of all valid Unit positions in this set.

Returns:	Average Position of all units in the set.
Return type:	`BWAPI.Position`

See also

Unit.getPosition()

getUnitsInRadius(radius[, pred = nil]) → Unitset¶

Retrieves the set of all units in a given radius relative to the value of getPosition().

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 (int) – 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:	`BWAPI.Unitset`

iterator() → iteratorFunction¶

Returns an iterator function intended to be used in for loops (e.g. for item in set:iterator() do).

Returns:	An iterator function that will return the next value in the set with each successive call.
Return type:	function

asTable() → table¶

Returns the values of the set as an array-like Lua table.

Note

The ordering of the returned table is arbitrary (due to sets being unordered in the C++ implementation).

Returns:	An array-like Lua table containing each value in the set.
Return type:	table

count(val) → int¶: Searches the set for elements with a value of val and returns the number of elements found. Because sets do not allow for duplicate values, this means that the function will return either 1 or 0. Because of this, it’s recommended to use contains() instead.

See also

contains(), std::unordered_set::count

contains(val) → boolean¶

Checks if this set contains a specific value.

Returns:	`true` if the set contains the specified value, or `false` otherwise.
Return type:	boolean

size() → int¶

Returns:	The number of values in the set.
Return type:	int

Note

set:size() is exactly equivalent to #set

empty() → boolean¶

Returns:	`true` if the set is empty (`size() == 0`), or `false` otherwise.
Return type:	boolean

insert(val)¶: Inserts the value into the set.

Note

Sets cannot contain duplicate values. If the value already exists in the set, the set will not be modified.

erase(val) → numElementsErased¶

Removes val from the set if it exists.

Returns:	The number of elements removed. Because sets do not allow for duplicate values, this means that the function will return either `1` or `0`.
Return type:	int

clear()¶: Removes all elements from the set, leaving it with a size of 0.

eraseIf(pred)¶

Iterates the set and erases each element x where pred(x) returns true. The set is modified in place.

Parameters:	pred (function) – A predicate function that takes a value and returns `true` for values that should be erased and `false` otherwise.

erase_if(pred)¶: Alias of eraseIf()

filter(pred)¶

Iterates the set and erases each element x where pred(x) returns false. The set is modified in place.

Parameters:	pred (function) – A predicate function that takes a value and returns `true` for values that should be kept and `false` for elements that should be erased.

keepIf(pred)¶: Alias of filter()/keep_if()

keep_if(pred)¶: Alias of filter()/keepIf()