Unitset¶
-
class
BWAPI.
Unitset
¶ The
Unitset
is a container for a set ofUnit
objects.It is typically used for groups of units instead of having to manage each Unit individually.
See also
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
orBWAPI.Unit
) – Can be either aPosition
orUnit
. 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.See also
- target (
-
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.
- type (BWAPI.UnitType) – The
-
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 theUnitType
if it isZerg
.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
andScarabs
.Note
If you call this using a
Zerg_Hatchery
,Zerg_Lair
, orZerg_Hive
, then it will automatically pass the command to one of itsZerg_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.
See also
Game.getLastError()
,Unit.build()
,Unit.morph()
,Unit.canMorph()
-
setRallyPoint
(target) → boolean¶ Orders the unit to set its rally position to the specified position or unit.
Parameters: target ( BWAPI.Position
orBWAPI.Unit
) – Can be either aPosition
orUnit
. 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 aZerg
ground unit that is capable ofBurrowing
, andBurrow
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
() → 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
-
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
() → 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
-
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
() → 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
-
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
-
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
) orTerran_Bunker
type.Parameters: - target (BWAPI.Unit) – The target unit to load into this Transport(
Terran_Dropship
,Protoss_Shuttle
,Zerg_Overlord
) orTerran_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()
- target (BWAPI.Unit) – The target unit to load into this Transport(
-
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
) andTerran_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
-
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 toBunkers
.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
-
rightClick
(target[, shiftQueueCommand = false]) → boolean¶ Works like the right click in the GUI.
Parameters: - target (
BWAPI.Position
orBWAPI.Unit
) – Can be either aPosition
orUnit
. 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.
- target (
-
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
-
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
-
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
orBWAPI.Unit
) – (optional) Can be either aPosition
orUnit
. If specified, indicates the target location or unit to use the tech on. If unspecified, causes thetech
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
-
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 returnstrue
for units that satisfy the intended filter andfalse
otherwise (can be a BWAPI.Filter unary filter). Defaults tonil
, 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: - pred (function) – (optional) A predicate function that takes a
-
getInterceptors
() → Unitset¶ Creates a single set containing all the
Interceptors
of allCarriers
in this set.Returns: The set of all Interceptors
.Return type: BWAPI.Unitset
See also
-
getLarva
() → Unitset¶ Creates a single set containing all the
Zerg_Larva
of allHatcheries
,Lairs
, andHives
in this set.Returns: The set of all Zerg_Larva
.Return type: BWAPI.Unitset
See also
-
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
-
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
-
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 returnstrue
for units that satisfy the intended filter andfalse
otherwise (can be a BWAPI.Filter unary filter). Defaults tonil
, which means no filter.
Returns: A
Unitset
containing the set of units that match the given criteria.Return type:
-
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 either1
or0
. Because of this, it’s recommended to usecontains()
instead.See also
-
contains
(val) → boolean¶ Checks if this set contains a specific value.
Returns: true
if the set contains the specified value, orfalse
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
), orfalse
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
or0
.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 andfalse
otherwise.
-
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 andfalse
for elements that should be erased.
-