BWAPI::Unitset class

Contents

Base classes

template<class T, typename Compare = std::less<>>
class SetContainer<T, Compare>
This container is used to wrap convenience functions for BWAPI and be used as a bridge with a built-in set type.

Public static variables

static const Unitset none
A blank Unitset containing no elements.

Public functions

auto getClosestUnit(const UnitFilter& pred = nullptr, int radius = 999999) const -> Unit
Retrieves the closest unit to this one.
auto getInterceptors() const -> Unitset
Creates a single set containing all the Interceptors of all Carriers in this set.
auto getLarva() const -> Unitset
Creates a single set containing all the Larvae of all Hatcheries, Lairs, and Hives in this set.
auto getLoadedUnits() const -> Unitset
Creates a single set containing all units that are loaded into units of this set.
auto getPosition() const -> Position
Calculates the average of all valid Unit positions in this set.
auto getUnitsInRadius(int radius, const UnitFilter& pred = nullptr) const -> Unitset
Retrieves the set of all units in a given radius of the current unit.
template<typename ... Ts>
auto operator=(Ts && ... vals) -> Unitset&

Unit Commands

auto issueCommand(UnitCommand command) const -> bool
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.
auto attack(Position target, bool shiftQueueCommand = false) const -> bool
Orders the unit(s) to attack move to the specified position.
auto attack(Unit target, bool shiftQueueCommand = false) const -> bool
Orders the unit(s) to attack move to the specified position.
auto buildAddon(UnitType type) const -> bool
Orders the Terran structure(s) to construct an add-on.
auto train(UnitType type) const -> bool
Orders the unit(s) to add a UnitType to its training queue, or morphs into the UnitType if it is Zerg.
auto morph(UnitType type) const -> bool
Orders the unit(s) to morph into a different UnitType.
auto setRallyPoint(Unit target) const -> bool
Orders the unit to set its rally position.
auto setRallyPoint(Position target) const -> bool
Orders the unit to set its rally position.
auto move(Position target, bool shiftQueueCommand = false) const -> bool
Orders the unit to move from its current position to the specified position.
auto patrol(Position target, bool shiftQueueCommand = false) const -> bool
Orders the unit to patrol between its current position and the specified position.
auto holdPosition(bool shiftQueueCommand = false) const -> bool
Orders the unit to hold its position.
auto stop(bool shiftQueueCommand = false) const -> bool
Orders the unit to stop.
auto follow(Unit target, bool shiftQueueCommand = false) const -> bool
Orders the unit to follow the specified unit.
auto gather(Unit target, bool shiftQueueCommand = false) const -> bool
Orders the unit to gather the specified unit (must be mineral or refinery type).
auto returnCargo(bool shiftQueueCommand = false) const -> bool
Orders the unit to return its cargo to a nearby resource depot such as a Command Center.
auto repair(Unit target, bool shiftQueueCommand = false) const -> bool
Orders the unit to repair the specified unit.
auto burrow() const -> bool
Orders the unit to burrow.
auto unburrow() const -> bool
Orders a burrowed unit to unburrow.
auto cloak() const -> bool
Orders the unit to cloak.
auto decloak() const -> bool
Orders a cloaked unit to decloak.
auto siege() const -> bool
Orders the unit to siege.
auto unsiege() const -> bool
Orders the unit to unsiege.
auto lift() const -> bool
Orders the unit to lift.
auto load(Unit target, bool shiftQueueCommand = false) const -> bool
Orders the unit to load the target unit.
auto unloadAll(bool shiftQueueCommand = false) const -> bool
auto unloadAll(Position target, bool shiftQueueCommand = false) const -> bool
auto rightClick(Unit target, bool shiftQueueCommand = false) const -> bool
Performs a right click action as it would work in StarCraft.
auto rightClick(Position target, bool shiftQueueCommand = false) const -> bool
Performs a right click action as it would work in StarCraft.
auto haltConstruction() const -> bool
Orders a SCV to stop constructing a structure.
auto cancelConstruction() const -> bool
Orders this unit to cancel and refund itself from begin constructed.
auto cancelAddon() const -> bool
Orders this unit to cancel and refund an add-on that is being constructed.
auto cancelTrain(int slot = -2) const -> bool
Orders the unit to remove the specified unit from its training queue.
auto cancelMorph() const -> bool
Orders this unit to cancel and refund a unit that is morphing.
auto cancelResearch() const -> bool
Orders this unit to cancel and refund a research that is in progress.
auto cancelUpgrade() const -> bool
Orders this unit to cancel and refund an upgrade that is in progress.
auto useTech(TechType tech) const -> bool
Orders the unit to use a technology.
auto useTech(TechType tech, Unit target) const -> bool
Orders the unit to use a technology.
auto useTech(TechType tech, Position target) const -> bool
Orders the unit to use a technology.

Function documentation

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.

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 .

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 .

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.

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.

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.

Parameters
radius The 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.

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

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
  BWAPI::Unitset myResources = pMain->getUnitsInRadius(1024, BWAPI::Filter::IsMineralField);
  if ( !myResources.empty() ) // check if we have resources nearby
  {
    BWAPI::Unitset myWorkers = pMain->getUnitsInRadius(512, BWAPI::Filter::IsWorker && BWAPI::Filter::IsIdle && BWAPI::Filter::IsOwned );
    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

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

bool BWAPI::Unitset::attack(Position target, bool shiftQueueCommand = false) const

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

Parameters
target A Position to designate as the target. 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.

bool BWAPI::Unitset::attack(Unit target, bool shiftQueueCommand = false) const

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

Parameters
target A Position to designate as the target. 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.

bool BWAPI::Unitset::buildAddon(UnitType type) const

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

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

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
type The UnitType to train.
Returns true if the command was passed to Broodwar, and false if BWAPI determined that the command would fail.

bool BWAPI::Unitset::morph(UnitType type) const

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

Parameters
type The UnitType to morph into.
Returns true if the command was passed to Broodwar, and false if BWAPI determined that the command would fail.

bool BWAPI::Unitset::setRallyPoint(Unit target) const

Orders the unit to set its rally position.

Parameters
target The target position that this structure will rally completed units to.
Returns true if the command was passed to Broodwar, and false if BWAPI determined that the command would fail.

bool BWAPI::Unitset::setRallyPoint(Position target) const

Orders the unit to set its rally position.

Parameters
target The target position that this structure will rally completed units to.
Returns true if the command was passed to Broodwar, and false if BWAPI determined that the command would fail.

bool BWAPI::Unitset::move(Position target, bool shiftQueueCommand = false) const

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

Parameters
target The 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.

bool BWAPI::Unitset::patrol(Position target, bool shiftQueueCommand = false) const

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

Parameters
target The 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.

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.

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.

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.

bool BWAPI::Unitset::follow(Unit target, bool shiftQueueCommand = false) const

Orders the unit to follow the specified unit.

Parameters
target The 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.

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

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

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.

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.

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

bool BWAPI::Unitset::repair(Unit target, bool shiftQueueCommand = false) const

Orders the unit to repair the specified unit.

Parameters
target The 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.

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

bool BWAPI::Unitset::burrow() const

Orders the unit to burrow.

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

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.

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.

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.

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.

bool BWAPI::Unitset::siege() const

Orders the unit to siege.

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

Only works for Siege Tanks.

bool BWAPI::Unitset::unsiege() const

Orders the unit to unsiege.

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

Only works for sieged Siege Tanks.

bool BWAPI::Unitset::lift() const

Orders the unit to lift.

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

Only works for liftable Terran structures.

bool BWAPI::Unitset::load(Unit target, bool shiftQueueCommand = false) const

Orders the unit to load the target unit.

Parameters
target The 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.

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

bool BWAPI::Unitset::rightClick(Unit target, bool shiftQueueCommand = false) const

Performs a right click action as it would work in StarCraft.

Parameters
target The target position 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.

bool BWAPI::Unitset::rightClick(Position target, bool shiftQueueCommand = false) const

Performs a right click action as it would work in StarCraft.

Parameters
target The target position 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.

bool BWAPI::Unitset::haltConstruction() const

Orders a SCV to stop constructing a structure.

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

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

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.

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.

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.

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.

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.

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.

bool BWAPI::Unitset::useTech(TechType tech) const

Orders the unit to use a technology.

Parameters
tech The technology type to use.
Returns true if the command was passed to Broodwar, and false if BWAPI determined that the command would fail.

bool BWAPI::Unitset::useTech(TechType tech, Unit target) const

Orders the unit to use a technology.

Parameters
tech The technology type to use.
target If specified, indicates the target location to use the tech on.
Returns true if the command was passed to Broodwar, and false if BWAPI determined that the command would fail.

bool BWAPI::Unitset::useTech(TechType tech, Position target) const

Orders the unit to use a technology.

Parameters
tech The technology type to use.
target If specified, indicates the target location to use the tech on.
Returns true if the command was passed to Broodwar, and false if BWAPI determined that the command would fail.

Variable documentation

static const Unitset BWAPI::Unitset::none

A blank Unitset containing no elements.

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