BWAPI  4.1.2
An API for interacting with Starcraft: Broodwar (1.16.1)
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Modules
Public Member Functions | Static Public Attributes | List of all members
BWAPI::Unitset Class Reference
Inheritance diagram for BWAPI::Unitset:
Inheritance graph

Public Member Functions

Unit getClosestUnit (const UnitFilter &pred=nullptr, int radius=999999) const
 
Unitset getInterceptors () const
 
Unitset getLarva () const
 
Unitset getLoadedUnits () const
 
Position getPosition () const
 
Unitset getUnitsInRadius (int radius, const UnitFilter &pred=nullptr) const
 
void setClientInfo (void *clientInfo=nullptr, int index=0) const
 
void setClientInfo (int clientInfo=0, int index=0) const
 
Unit Commands
bool issueCommand (UnitCommand command) const
 
bool attack (PositionOrUnit target, bool shiftQueueCommand=false) const
 
bool build (UnitType type, TilePosition target=TilePositions::None) const
 
bool buildAddon (UnitType type) const
 
bool train (UnitType type) const
 
bool morph (UnitType type) const
 
bool setRallyPoint (PositionOrUnit target) const
 
bool move (Position target, bool shiftQueueCommand=false) const
 
bool patrol (Position target, bool shiftQueueCommand=false) const
 
bool holdPosition (bool shiftQueueCommand=false) const
 
bool stop (bool shiftQueueCommand=false) const
 
bool follow (Unit target, bool shiftQueueCommand=false) const
 
bool gather (Unit target, bool shiftQueueCommand=false) const
 
bool returnCargo (bool shiftQueueCommand=false) const
 
bool repair (Unit target, bool shiftQueueCommand=false) const
 
bool burrow () const
 
bool unburrow () const
 
bool cloak () const
 
bool decloak () const
 
bool siege () const
 
bool unsiege () const
 
bool lift () const
 
bool load (Unit target, bool shiftQueueCommand=false) const
 
bool unloadAll (bool shiftQueueCommand=false) const
 
bool unloadAll (Position target, bool shiftQueueCommand=false) const
 
bool rightClick (PositionOrUnit target, bool shiftQueueCommand=false) const
 
bool haltConstruction () const
 
bool cancelConstruction () const
 
bool cancelAddon () const
 
bool cancelTrain (int slot=-2) const
 
bool cancelMorph () const
 
bool cancelResearch () const
 
bool cancelUpgrade () const
 
bool useTech (TechType tech, PositionOrUnit target=nullptr) const
 
- Public Member Functions inherited from std::unordered_set< K >
unordered_set (T...args)
 
begin (T...args)
 
begin(int) (T...args)
 
bucket (T...args)
 
bucket_count (T...args)
 
bucket_size (T...args)
 
cbegin (T...args)
 
cbegin(int) (T...args)
 
cend (T...args)
 
cend(int) (T...args)
 
clear (T...args)
 
count (T...args)
 
emplace (T...args)
 
emplace_hint (T...args)
 
empty (T...args)
 
end (T...args)
 
end(int) (T...args)
 
equal_range (T...args)
 
erase (T...args)
 
find (T...args)
 
get_allocator (T...args)
 
hash_function (T...args)
 
insert (T...args)
 
key_eq (T...args)
 
load_factor (T...args)
 
max_bucket_count (T...args)
 
max_load_factor (T...args)
 
max_size (T...args)
 
operator= (T...args)
 
rehash (T...args)
 
reserve (T...args)
 
size (T...args)
 
swap (T...args)
 

Static Public Attributes

static const Unitset none
 

Additional Inherited Members

- Public Attributes inherited from std::unordered_set< K >
keys
 

Detailed Description

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

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

See also
Unit

Member Function Documentation

Position BWAPI::Unitset::getPosition ( ) const

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

Returns
Average Position of all units in the set.
See also
UnitInterface::getPosition
Unitset BWAPI::Unitset::getLoadedUnits ( ) const

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

Returns
The set of all loaded units.
See also
UnitInterface::getLoadedUnits
Unitset BWAPI::Unitset::getInterceptors ( ) const

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

Returns
The set of all Interceptors .
See also
UnitInterface::getInterceptors
Unitset BWAPI::Unitset::getLarva ( ) const

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

Returns
The set of all Larvae .
See also
UnitInterface::getLarva
void BWAPI::Unitset::setClientInfo ( void *  clientInfo = nullptr,
int  index = 0 
) const

Sets the client info for every unit in this set.

Parameters
clientInfo(optional) A pointer to client information, managed by the AI module, or nullptr if client information is to be cleared.
index(optional) An key value for the client info mapping so that more than one piece of data can be mapped to the same unit.
See also
UnitInterface::setClientInfo
void BWAPI::Unitset::setClientInfo ( int  clientInfo = 0,
int  index = 0 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Unitset BWAPI::Unitset::getUnitsInRadius ( int  radius,
const UnitFilter pred = nullptr 
) const

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 that is composed using BWAPI Filter semantics to include only specific units (such as only ground units, etc.)

Parameters
radiusThe radius, in pixels, to search for units.
pred(optional) The composed function predicate to include only specific (desired) units in the set. Defaults to nullptr, which means no filter.
Returns
A Unitset containing the set of units that match the given criteria.

Example usage:

// Get main building closest to start location.
BWAPI::Unit pMain = BWAPI::Broodwar->getClosestUnit( BWAPI::Broodwar->self()->getStartLocation(), BWAPI::Filter::IsResourceDepot );
if ( pMain ) // check if pMain is valid
{
// Get sets of resources and workers
if ( !myResources.empty() ) // check if we have resources nearby
{
while ( !myWorkers.empty() ) // make sure we command all nearby idle workers, if any
{
for ( auto u = myResources.begin(); u != myResources.end() && !myWorkers.empty(); ++u )
{
myWorkers.back()->gather(*u);
myWorkers.pop_back();
}
}
} // myResources not empty
} // pMain != nullptr
See also
getClosestUnit, getUnitsInWeaponRange, Game::getUnitsInRadius, Game::getUnitsInRectangle
Unit BWAPI::Unitset::getClosestUnit ( const UnitFilter pred = nullptr,
int  radius = 999999 
) const

Retrieves the closest unit to this one.

Parameters
pred(optional) A function predicate used to identify which conditions must be matched for a unit to be considered. If omitted, then the closest unit owned by any player will be returned.
radius(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.
See also
getUnitsInRadius, Game::getUnitsInRadius, Game::getUnitsInRectangle
bool BWAPI::Unitset::issueCommand ( UnitCommand  command) const

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
commandA 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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
UnitCommandTypes, Game::getLastError, UnitInterface::canIssueCommand
bool BWAPI::Unitset::attack ( PositionOrUnit  target,
bool  shiftQueueCommand = false 
) const

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

Parameters
targetA Position or a Unit to designate as the target. If a Position is used, the unit will perform an Attack Move command.
shiftQueueCommand(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.
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.
See also
Game::getLastError, UnitInterface::canAttack
bool BWAPI::Unitset::build ( UnitType  type,
TilePosition  target = TilePositions::None 
) const

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

Parameters
typeThe UnitType to build.
targetA 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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
You must have sufficient resources and meet the necessary requirements in order to build a structure.
See also
Game::getLastError, UnitInterface::train, UnitInterface::cancelConstruction, UnitInterface::canBuild
bool BWAPI::Unitset::buildAddon ( UnitType  type) const

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

Parameters
typeThe add-on UnitType to construct.
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.
You must have sufficient resources and meet the necessary requirements in order to build a structure.
See also
Game::getLastError, UnitInterface::build, UnitInterface::cancelAddon, UnitInterface::canBuildAddon
bool BWAPI::Unitset::train ( UnitType  type) const

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

Parameters
typeThe UnitType to train.
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.
You must have sufficient resources, supply, and meet the necessary requirements in order to train a unit.
This command is also used for training Interceptors and Scarabs.
If you call this using a Hatchery, Lair, or Hive, then it will automatically pass the command to one of its Larvae.
See also
Game::getLastError, UnitInterface::build, UnitInterface::morph, UnitInterface::cancelTrain, UnitInterface::isTraining, UnitInterface::canTrain
bool BWAPI::Unitset::morph ( UnitType  type) const

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

Parameters
typeThe UnitType to morph into.
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
Game::getLastError, UnitInterface::build, UnitInterface::morph, UnitInterface::canMorph
bool BWAPI::Unitset::setRallyPoint ( PositionOrUnit  target) const

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

Parameters
targetThe 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.
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
bool BWAPI::Unitset::move ( Position  target,
bool  shiftQueueCommand = false 
) const

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

Parameters
targetThe target position to move to.
shiftQueueCommand(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
isMoving, canMove
bool BWAPI::Unitset::patrol ( Position  target,
bool  shiftQueueCommand = false 
) const

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
targetThe position to patrol to.
shiftQueueCommand(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
isPatrolling, canPatrol
bool BWAPI::Unitset::holdPosition ( bool  shiftQueueCommand = false) const

Orders the unit to hold its position.

Parameters
shiftQueueCommand(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
canHoldPosition, isHoldingPosition
bool BWAPI::Unitset::stop ( bool  shiftQueueCommand = false) const

Orders the unit to stop.

Parameters
shiftQueueCommand(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
canStop, isIdle
bool BWAPI::Unitset::follow ( Unit  target,
bool  shiftQueueCommand = false 
) const

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
targetThe target unit to start following.
shiftQueueCommand(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
isFollowing, canFollow, getOrderTarget
bool BWAPI::Unitset::gather ( Unit  target,
bool  shiftQueueCommand = false 
) const

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

Parameters
targetThe target unit to gather from.
shiftQueueCommand(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
isGatheringGas, isGatheringMinerals, canGather
bool BWAPI::Unitset::returnCargo ( bool  shiftQueueCommand = false) const

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(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
isCarryingGas, isCarryingMinerals, canReturnCargo
bool BWAPI::Unitset::repair ( Unit  target,
bool  shiftQueueCommand = false 
) const

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
targetThe unit to repair.
shiftQueueCommand(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
isRepairing, canRepair
bool BWAPI::Unitset::burrow ( ) const

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.
See also
unburrow, isBurrowed, canBurrow
bool BWAPI::Unitset::unburrow ( ) const

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.
See also
burrow, isBurrowed, canUnburrow
bool BWAPI::Unitset::cloak ( ) const

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.
See also
decloak, isCloaked, canCloak
bool BWAPI::Unitset::decloak ( ) const

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.
See also
cloak, isCloaked, canDecloak
bool BWAPI::Unitset::siege ( ) const

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
bool BWAPI::Unitset::unsiege ( ) const

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
bool BWAPI::Unitset::lift ( ) const

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
bool BWAPI::Unitset::load ( Unit  target,
bool  shiftQueueCommand = false 
) const

Orders the unit to load the target unit.

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

Parameters
targetThe target unit to load into this Transport(Dropship, Shuttle, Overlord ) or Bunker.
shiftQueueCommand(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
unload, unloadAll, getLoadedUnits, isLoaded
bool BWAPI::Unitset::unloadAll ( bool  shiftQueueCommand = false) const

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(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
load, unload, getLoadedUnits, isLoaded, canUnloadAll, canUnloadAtPosition
bool BWAPI::Unitset::unloadAll ( Position  target,
bool  shiftQueueCommand = false 
) const

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

Only works for Transports(Dropships, Shuttles, Overlords ). Not applicable to Bunkers.

Parameters
targetThe target position to unload the units at.
shiftQueueCommand(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
load, unload, getLoadedUnits, isLoaded, canUnloadAllPosition, canUnloadAtPosition
bool BWAPI::Unitset::rightClick ( PositionOrUnit  target,
bool  shiftQueueCommand = false 
) const

Works like the right click in the GUI.

Parameters
targetThe target position or target unit to right click.
shiftQueueCommand(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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
canRightClick, canRightClickPosition, canRightClickUnit
bool BWAPI::Unitset::haltConstruction ( ) const

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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
isConstructing, canHaltConstruction
bool BWAPI::Unitset::cancelConstruction ( ) const

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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
isBeingConstructed, build, canCancelConstruction
bool BWAPI::Unitset::cancelAddon ( ) const

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
bool BWAPI::Unitset::cancelTrain ( int  slot = -2) const

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

Parameters
slot(optional) Identifies the slot that will be cancelled. If the specified value is at least 0, then the unit in the corresponding slot from the list provided by getTrainingQueue will be cancelled. If the value is either omitted or -2, then the last slot is cancelled.
Note
The value of slot is passed directly to Broodwar. Other negative values have no effect.
See also
train, cancelTrain, isTraining, getTrainingQueue, canCancelTrain, canCancelTrainSlot
bool BWAPI::Unitset::cancelMorph ( ) const

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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
morph, isMorphing, canCancelMorph
bool BWAPI::Unitset::cancelResearch ( ) const

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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
research, isResearching, getTech, canCancelResearch
bool BWAPI::Unitset::cancelUpgrade ( ) const

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.
Note
There is a small chance for a command to fail after it has been passed to Broodwar.
See also
upgrade, isUpgrading, getUpgrade, canCancelUpgrade
bool BWAPI::Unitset::useTech ( TechType  tech,
PositionOrUnit  target = nullptr 
) const

Orders the unit to use a technology.

Parameters
techThe technology type to use.
target(optional) 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.
See also
canUseTechWithOrWithoutTarget, canUseTech, canUseTechWithoutTarget, canUseTechUnit, canUseTechPosition, TechTypes

Member Data Documentation

const Unitset BWAPI::Unitset::none
static

A blank Unitset containing no elements.

This is typically used as a return value for BWAPI interface functions that have encountered an error.