UnitType

class BWAPI.UnitType

The UnitType is used to get information about a particular type of unit, such as its cost, build time, weapon, hit points, abilities, etc.

See also

Unit.getType(), UnitTypes

Constructors

UnitType([id = UnitTypes.Enum.None])

Expected type constructor.

If the type is an invalid type, then it becomes Unknown. A type is invalid if its value is less than 0 or greater than Unknown.

Parameters:id (int) – The id that corresponds to this type. It is typically an integer value that corresponds to an internal Broodwar type. If the given id is invalid, then it becomes Unknown.

Member Functions

getID() → int

Retrieves this type’s identifier as an integer.

Returns:An integer representation of this type. Return type:int

isValid() → boolean

Checks if the current type has a valid identifier. The purpose of this function is to prevent buffer overflows if a type has been handled improperly.

A type is valid if it is between 0 and Unknown (inclusive).

Returns:true if this type is valid and false otherwise. Return type:boolean

getName() → string

Returns:The variable name of the type. Return type:string

abilities() → TechTypeset

Retrieves the set of abilities that this unit can use, provided it is available to you in the game.

Returns:Set of TechType‘s containing ability information. Return type:BWAPI.TechTypeset

acceleration() → int

Retrieves the unit’s acceleration amount.

Returns:How fast the unit can accelerate to its top speed. Return type:int

airWeapon() → WeaponType

Retrieves this unit type’s weapon type used when attacking targets in the air.

Returns:WeaponType used as this unit type’s air weapon. Return type:BWAPI.WeaponType

See also

maxAirHits(), groundWeapon()

armor() → int

Retrieves the default amount of armor that the unit type starts with, excluding upgrades.

Returns:The amount of armor the unit type has. Return type:int

Note

This value may not necessarily match the value seen in the Use Map Settings game type.

armorUpgrade() → UpgradeType

Retrieves the upgrade type used to increase the armor of this unit type.

For each upgrade, this unit type gains +1 additional armor.

Returns:UpgradeType indicating the upgrade that increases this unit type’s armor amount. Return type:BWAPI.UpgradeType

buildScore() → int

Retrieves the amount of score points awarded for constructing this unit type.

This value is used for calculating scores in the post-game score screen.

Returns:Number of points awarded for constructing this unit type. Return type:int

See also

destroyScore()

buildsWhat() → UnitTypeset

Retrieves the set of units that this unit type is capable of creating.

This includes training, constructing, warping, and morphing.

Returns:UnitTypeset containing the units it can build. Return type:BWAPI.UnitTypeset

Note

Some maps have special parameters that disable construction of units that are otherwise normally available. Use Player.isUnitAvailable() to determine if a unit type is actually available in the current game for a specific player.

See also

Player.isUnitAvailable()

buildTime() → int

Retrieves the default time, in frames, needed to train, morph, or build the unit.

Returns:Number of frames needed in order to build the unit. Return type:int

Note

This value may not necessarily match the value seen in the Use Map Settings game type.

See also

Unit.getRemainingBuildTime()

canAttack() → boolean

Checks if this unit is capable of attacking.

Returns:true if this unit type is capable of damaging other units with a standard attack, and false otherwise. Return type:boolean

Note

This function returns false for units that can only inflict damage via special abilities, such as the High Templar.

canBuildAddon() → boolean

Checks if this unit type is capable of constructing an add-on.

An add-on is an extension or attachment for Terran structures, specifically the Command Center, Factory, Starport, and Science Facility.

Returns:true if this unit type can construct an add-on, and false if it can not. Return type:boolean

See also

isAddon()

canMove() → boolean

Checks if this unit type is capable of movement.

Returns:true if this unit can use a movement command, and false if they cannot move. Return type:boolean

Note

Buildings will return false, including Terran liftable buildings which are capable of moving when lifted.

canProduce() → boolean

Determines if a unit can train other units.

For example, BWAPI.UnitTypes.Terran_Barracks:canProduce() will return true, while BWAPI.UnitTypes.Terran_Marine:canProduce() will return false. This is also true for two non-structures: Protoss_Carrier (can produce interceptors) and Protoss_Reaver (can produce scarabs).

Returns:true if this unit type can have a production queue, and false otherwise. Return type:boolean

cloakingTech() → TechType

Retrieves the cloaking technology associated with certain units.

Returns:TechType referring to the cloaking technology that this unit type uses as an ability. Returns TechTypes.None if this unit type does not have an active cloak ability. Return type:BWAPI.TechType

destroyScore() → int

Retrieves the amount of score points awarded for killing this unit type.

This value is used for calculating scores in the post-game score screen.

Returns:Number of points awarded for killing this unit type. Return type:int

See also

buildScore()

dimensionDown() → int

Retrieves the distance from the center of the unit type to its bottom edge.

Returns:Distance to this unit type’s bottom edge from its center, in pixels. Return type:int

dimensionLeft() → int

Retrieves the distance from the center of the unit type to its left edge.

Returns:Distance to this unit type’s left edge from its center, in pixels. Return type:int

dimensionRight() → int

Retrieves the distance from the center of the unit type to its right edge.

Returns:Distance to this unit type’s right edge from its center, in pixels. Return type:int

dimensionUp() → int

Retrieves the distance from the center of the unit type to its top edge.

Returns:Distance to this unit type’s top edge from its center, in pixels. Return type:int

gasPrice() → int

Retrieves the default vespene gas price of purchasing the unit.

Returns:Vespene gas cost of the unit. Return type:int

Note

This value may not necessarily match the value seen in the Use Map Settings game type.

getRace() → Race

Retrieves the Race that the unit type belongs to.

Returns:Race indicating the race that owns this unit type. Returns Race.None indicating that the unit type does not belong to any particular race (a critter for example). Return type:BWAPI.Race

groundWeapon() → WeaponType

Retrieves this unit type’s weapon type used when attacking targets on the ground.

Returns:WeaponType used as this unit type’s ground weapon. Return type:BWAPI.WeaponType

See also

maxGroundHits(), airWeapon()

haltDistance() → int

Retrieves the unit’s halting distance.

This determines how fast a unit can stop moving.

Returns:A halting distance value. Return type:int

hasPermanentCloak() → boolean

Checks if this unit type is permanently cloaked.

This means the unit type is always cloaked and requires a detector in order to see it.

Returns:true if this unit type is permanently cloaked, and false otherwise. Return type:boolean

height() → int

A macro for retrieving the height of the unit type, which is calculated using dimensionUp + dimensionDown + 1.

Returns:Height of the unit, in pixels. Return type:int

isAddon() → boolean

Checks if this unit is an add-on.

Add-ons are attachments used by some Terran structures such as the Comsat Station.

Returns:true if this unit is an add-on, and false otherwise. Return type:boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: getRace() == BWAPI.Races.Terran, isBuilding()

isBeacon() → boolean

Checks if this unit type is a beacon.

Each race has exactly one beacon each. They are UnitTypes.Special_Zerg_Beacon, UnitTypes.Special_Terran_Beacon, and UnitTypes.Special_Protoss_Beacon.

Returns:true if this unit type is one of the three race beacons, and false otherwise. Return type:boolean

See also

isFlagBeacon()

isBuilding() → boolean

Checks if this unit is a structure.

This includes Mineral Fields and Vespene Geysers.

Returns:true if this unit is a building, and false otherwise. Return type:boolean

isBurrowable() → boolean

Checks if this unit type has the capability to use the Burrow technology when it is researched.

Returns:true if this unit can use the Burrow ability, and false otherwise. Return type:boolean

Note

The ~BWAPI.UnitTypes.Zerg_Lurker can burrow even without researching the ability.

See also

BWAPI.TechTypes.Burrowing

Note

If this function returns a successful state, then the following function calls will also return a successful state: getRace() == BWAPI.Races.Zerg, not isBuilding(), canMove()

isCloakable() → boolean

Checks if this unit type has the capability to use a cloaking ability when it is researched.

This applies only to Wraiths and Ghosts, and does not include units which are permanently cloaked.

Returns:true if this unit has a cloaking ability, false otherwise. Return type:boolean

See also

hasPermanentCloak(), TechTypes.Cloaking_Field, TechTypes.Personnel_Cloaking

isCritter() → boolean

Checks if this unit type is a neutral critter.

Returns:true if this unit type is a critter, and false otherwise. Return type:boolean

Example usage

local myBasePosition = BWAPI.Position( BWAPI.Broodwar:self():getStartLocation() )
local pred = function(unit) return not BWAPI.Filter.IsOwned(unit) and not BWAPI.Filter.IsParasited(unit) end
local unitsAroundTheBase = BWAPI.Broodwar:getUnitsInRadius(myBasePosition, 1024, pred)
for u in unitsAroundTheBase:iterator() do
  if u:getType():isCritter() and not u:isInvincible() then
    local myQueenPred = function(unit) return unit:getType() == BWAPI.UnitTypes.Zerg_Queen and BWAPI.Filter.IsOwned(unit) end
    local myQueen = u:getClosestUnit(myQueenPred)
    if myQueen then
      myQueen:useTech(BWAPI.TechTypes.Parasite, u)
    end
  end
end

isDetector() → boolean

Checks if this unit type is capable of detecting units that are cloaked or burrowed.

Returns:true if this unit type is a detector by default, false if it does not have this property Return type:boolean

isFlagBeacon() → boolean

Checks if this unit type is a flag beacon.

Each race has exactly one flag beacon each. They are UnitTypes.Special_Zerg_Flag_Beacon, UnitTypes.Special_Terran_Flag_Beacon, and UnitTypes.Special_Protoss_Flag_Beacon. Flag beacons spawn a flag after some ARBITRARY I FORGOT AMOUNT OF FRAMES.

Returns:true if this unit type is one of the three race flag beacons, and false otherwise. Return type:boolean

See also

isBeacon()

isFlyer() → boolean

Checks if this unit type is a flying unit.

Flying units ignore ground pathing and collisions.

Returns:true if this unit type is in the air by default, and false otherwise. Return type:boolean

isFlyingBuilding() → boolean

Checks if this structure has the capability to use the lift-off command.

Returns:true if this unit type is a flyable building, false otherwise. Return type:boolean

Note

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

isHero() → boolean

Checks if this unit type is a hero.

Heroes are types that the player cannot obtain normally, and are identified by the white border around their icon when selected with a group.

Returns:true if this unit type is a hero type, and false otherwise. Return type:boolean

Note

There are two non-hero units included in this set, the Civilian <BWAPI.UnitTypes.Terran_Civilian> and Dark Templar Hero <BWAPI.UnitTypes.Hero_Dark_Templar>.

isInvincible() → boolean

Checks if this unit type is invincible by default.

Invincible units cannot take damage.

Returns:true if this unit type is invincible, and false if it is vulnerable to attacks. Return type:boolean

isMechanical() → boolean

Checks if this unit is mechanical.

The mechanical property is required for some actions such as repair.

Returns:true if this unit type has the mechanical property, and false otherwise. Return type:boolean

isMineralField() → boolean

Checks if this unit type is a mineral field and contains a resource amount.

This indicates that the unit type is either UnitTypes.Resource_Mineral_Field, UnitTypes.Resource_Mineral_Field_Type_2, or UnitTypes.Resource_Mineral_Field_Type_3.

Returns:true if this unit type is a mineral field resource. Return type:boolean

isNeutral() → boolean

Checks if this unit type is a neutral type, such as critters and resources.

Returns:true if this unit is intended to be neutral, and false otherwise. Return type:boolean

isOrganic() → boolean

Checks if this unit is an organic unit.

The organic property is required for some abilities such as ~BWAPI.TechTypes.Heal.

Returns:true if this unit type has the organic property, and false otherwise. Return type:boolean

isPowerup() → boolean

Checks if this unit type is a powerup.

Powerups can be picked up and carried by workers. They are usually only seen in campaign maps and Capture The Flag.

Returns:true if this unit type is a powerup type, and false otherwise. Return type:boolean

isRefinery() → boolean

Checks if this unit type is a refinery.

A refinery is a structure that is placed on top of a Vespene Geyser . Refinery types are BWAPI.UnitTypes.Terran_Refinery , BWAPI.UnitTypes.Zerg_Extractor , and BWAPI.UnitTypes.Protoss_Assimilator.

Returns:true if this unit type is a refinery, and false if it is not. Return type:boolean

Example

local myUnits = BWAPI.Broodwar:self():getUnits()
for u in myUnits:iterator() do
  if u:getType():isRefinery() then
    local workersAssigned = u.clientInfo["work"]
    if not workersAssigned or workersAssigned < 3 then
      local idleWorkerFilter = function(unit) return BWAPI.Filter.IsWorker(unit) and BWAPI.Filter.IsIdle(unit) end
      local closestIdleWorker = u:getClosestUnit(idleWorkerFilter)
      if closestIdleWorker then
        -- gather from the refinery (and check if successful)
        if closestIdleWorker:gather(u) then
          -- set a back reference for when the unit is killed or re-assigned (code not provided)
          closestIdleWorker.clientInfo['ref'] = u

          -- Increment the number of workers assigned and associate it with the refinery
          workersAssigned = workersAssigned + 1
          u.clientInfo['work'] = workersAssigned
        end
      end
    end
  end
end

isResourceContainer() → boolean

Checks if this unit type is capable of storing resources such as Mineral Fields.

Resources are harvested from resource containers.

Returns:true if this unit type may contain resources that can be harvested, false otherwise. Return type:boolean

isResourceDepot() → boolean

Checks if this unit type is a resource depot.

Resource depots must be placed a certain distance from resources. Resource depots are typically the main building for any particular race. Workers will return resources to the nearest resource depot.

Returns:true if the unit type is a resource depot, false if it is not. Return type:boolean

Example

if BWAPI.Broodwar:self() then
  local myUnits = BWAPI.Broodwar:self():getUnits()
  for u in myUnits:iterator() do
    if u:isIdle() and u:getType():isResourceDepot() then
      u:train( u:getType():getRace():getWorker() )
   end
  end
end

isRobotic() → boolean

Checks if this unit is robotic.

The robotic property is applied to robotic units such as the Protoss_Probe which prevents them from taking damage from BWAPI.TechTypes.Irradiate.

Returns:true if this unit type has the robotic property, and false otherwise. Return type:boolean

isSpecialBuilding() → boolean

Checks if this structure is special and cannot be obtained normally within the game.

Returns:true if this structure is a special building, and false otherwise. Return type:boolean

Note

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

isSpell() → boolean

Identifies if this unit type is used to complement some abilities.

These include UnitTypes.Spell_Dark_Swarm, UnitTypes.Spell_Disruption_Web, and UnitTypes.Spell_Scanner_Sweep, which correspond to TechTypes.Dark_Swarm, TechTypes.Disruption_Web, and TechTypes.Scanner_Sweep respectively.

Returns:true if this unit type is used for an ability, and false otherwise. Return type:boolean

isSpellcaster() → boolean

Checks if this unit type has the capacity to store energy and use it for special abilities.

Returns:true if this unit type generates energy, and false if it does not have an energy pool. Return type:boolean

isSuccessorOf(unitType) → boolean

Checks if the current type is equal to the provided type, or a successor of the provided type.

For example, a Hive is a successor of a Hatchery, since it can still research the Burrowing technology.

Parameters:unitType (BWAPI.UnitType) – The unit type to check. Returns:true if this unit type is a successor of the given unit type, and false if it is not. Return type:boolean

isTwoUnitsInOneEgg() → boolean

Checks if this unit type spawns two units when being hatched from an Zerg_Egg.

This is only applicable to Zerglings.

Returns:true if morphing this unit type will spawn two of them, and false if only one is spawned. Return type:boolean

isWorker() → boolean

Checks if this unit type is a worker unit.

Worker units can harvest resources and build structures. Worker unit types include the Terran_SCV , Protoss_Probe, and Zerg_Drone.

Returns:true if this unit type is a worker, and false if it is not. Return type:boolean

maxAirHits() → int

Retrieves the maximum number of hits this unit can deal to a flying target using its air weapon.

This value is multiplied by the air weapon’s damage to calculate the unit type’s damage potential.

Returns:Maximum number of hits given to air targets. Return type:int

See also

airWeapon(), maxGroundHits()

maxEnergy() → int

Retrieves the maximum amount of energy this unit type can have by default.

Returns:Integer indicating the maximum amount of energy for this unit type. Returns 0 if this unit does not gain energy for abilities. Return type:int

maxGroundHits() → int

Retrieves the maximum number of hits this unit can deal to a ground target using its ground weapon.

This value is multiplied by the ground weapon’s damage to calculate the unit type’s damage potential.

Returns:Maximum number of hits given to ground targets. Return type:int

See also

groundWeapon(), maxAirHits()

maxHitPoints() → int

Retrieves the default maximum amount of hit points that this unit type can have.

Returns:Integer indicating the maximum amount of hit points for this unit type. Return type:int

Note

This value may not necessarily match the value seen in the Use Map Settings game type.

maxShields() → int

Retrieves the default maximum amount of shield points that this unit type can have.

Returns:Integer indicating the maximum amount of shield points for this unit type. Returns 0 if this unit type does not have shields. Return type:int

Note

This value may not necessarily match the value seen in the Use Map Settings game type.

mineralPrice() → int

Retrieves the default mineral price of purchasing the unit.

Returns:Mineral cost of the unit. Return type:int

Note

This value may not necessarily match the value seen in the Use Map Settings game type.

producesCreep() → boolean

Checks if this structure type produces creep.

That is, the unit type spreads creep over a wide area so that Zerg structures can be placed on it.

Returns:true if this unit type spreads creep. Return type:boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: getRace() == BWAPI.Races.Zerg, isBuilding()

producesLarva() → boolean

Checks if this unit type produces larva.

This is essentially used to check if the unit type is a Zerg_Hatchery, Zerg_Lair, or Zerg_Hive.

Returns:true if this unit type produces larva. Return type:boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: getRace() == BWAPI.Races.Zerg, isBuilding()

regeneratesHP() → boolean

Checks if this unit type can regenerate hit points.

This generally applies to Zerg units.

Returns:true if this unit type regenerates its hit points, and false otherwise. Return type:boolean

requiredTech() → TechType

Identifies the required TechType in order to create certain units.

Returns:TechType indicating the technology that must be researched in order to create this unit type. Returns TechTypes.None if creating this unit type does not require a technology to be researched. Return type:BWAPI.TechType

Note

The only unit that requires a technology is the Zerg_Lurker, which needs Lurker_Aspect.

requiredUnits() → table

Retrieves the immediate technology tree requirements to make this unit type.

Important

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

Returns:Table containing the number of required units of each type that are necessary to make this unit type. Return type:table of the format { [<unitTypeID>] = <howMany> }, where <unitTypeID> is the integer ID/Enum of a required UnitType (equal to UnitType:getID()) and <howMany> is the required number of that unit.

Example usage

local scv = BWAPI.UnitTypes.SCV
local requiredUnits = scv:requiredUnits()
for unitTypeID, howMany in pairs(requiredUnits) do
  local requiredUnitType = BWAPI.UnitType(unitTypeID)
  local str = string.format("%s requires %d %s",
    tostring(scv),
    howMany,
    tostring(requiredUnitType)
  )
  print(str)
end

requiresCreep() → boolean

Checks if this structure must be placed on Zerg creep.

Returns:true if this unit type requires creep, false otherwise. Return type:boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: isBuilding(), getRace() == BWAPI.Races.Zerg

requiresPsi() → boolean

Checks if this structure is powered by a psi field.

Structures powered by psi can only be placed near a Protoss_Pylon. If the Protoss_Pylon is destroyed, then this unit will lose power.

Returns:true if this unit type can only be placed in a psi field, false otherwise. Return type:boolean

Note

If this function returns a successful state, then the following function calls will also return a successful state: isBuilding(), getRace() == BWAPI.Races.Protoss

researchesWhat() → TechTypeset

Retrieves the set of technologies that this unit type is capable of researching.

Returns:TechTypeset containing the technology types that can be researched. Return type:BWAPI.TechTypeset

Note

Some maps have special parameters that disable certain technologies. Use Player.isResearchAvailable() to determine if a technology is actually available in the current game for a specific player.

See also

Player.isResearchAvailable()

seekRange() → int

Retrieves the range at which this unit type will start targeting enemy units.

Returns:Distance at which this unit type begins to seek out enemy units, in pixels. Return type:int

sightRange() → int

Retrieves the sight range of this unit type.

Returns:Sight range of this unit type, measured in pixels. Return type:int

size() → UnitSizeType

Retrieves the UnitSizeType of this unit, which is used in calculations along with weapon damage types to determine the amount of damage that will be dealt to this type.

Returns:UnitSizeType indicating the conceptual size of the unit type. Return type:BWAPI.UnitSizeType

See also

WeaponType.damageType()

spaceProvided() → int

Retrieves the amount of space provided by this Terran_Bunker or Transport(Terran_Dropship, Protoss_Shuttle, Zerg_Overlord ) for unit transportation.

Returns:The number of slots provided by this unit type. Return type:int

See also

spaceRequired()

spaceRequired() → int

Retrieves the amount of space required by this unit type to fit inside a Terran_Bunker or Transport(Terran_Dropship, Protoss_Shuttle, Zerg_Overlord ).

Returns:Amount of space required by this unit type for transport. Returns 255 if this unit type can not be transported. Return type:int

See also

spaceProvided()

supplyProvided() → int

Retrieves the amount of supply that this unit type produces for its appropriate Race‘s supply pool.

Returns: Return type:int

Note

In Starcraft programming, the managed supply values are double than what they appear in the game. The reason for this is because Zerglings use 0.5 visible supply.

See also

supplyRequired(), Player.supplyTotal(), Player.supplyUsed()

supplyRequired() → int

Retrieves the amount of supply that this unit type will use when created.

It will use the supply pool that is appropriate for its Race.

Returns:Integer containing the supply required to build this unit. Return type:int

Note

In Starcraft programming, the managed supply values are double than what they appear in the game. The reason for this is because Zerglings use 0.5 visible supply.

See also

supplyProvided(), Player.supplyTotal(), Player.supplyUsed()

tileHeight() → int

Retrieves the height of this unit type, in tiles.

Used for determining the tile size of structures.

Returns:Height of this unit type, in tiles. Return type:int

tileSize() → TilePosition

Retrieves the tile size of this unit type.

Used for determining the tile size of structures.

Returns:TilePosition containing the width (x) and height (y) of the unit type, in tiles. Return type:BWAPI.TilePosition

tileWidth() → int

Retrieves the width of this unit type, in tiles.

Used for determining the tile size of structures.

Returns:Width of this unit type, in tiles. Return type:int

topSpeed() → double

Retrieves this unit type’s top movement speed with no upgrades.

Returns:The approximate top speed, in pixels per frame, as a double. For liftable Terran structures, this function returns their movement speed while lifted. Return type:double

Note

That some units have inconsistent movement and this value is sometimes an approximation.

turnRadius() → int

Retrieves a unit’s turning radius.

This determines how fast a unit can turn.

Returns:A turn radius value. Return type:int

upgrades() → UpgradeTypeset

Retrieves the set of upgrades that this unit can use to enhance its fighting ability.

Returns:Set of UpgradeType‘s containing upgrade types that will impact this unit type. Return type:BWAPI.UpgradeTypeset

upgradesWhat() → UpgradeTypeset

Retrieves the set of upgrades that this unit type is capable of upgrading.

Returns:UpgradeTypeset containing the upgrade types that can be upgraded. Return type:BWAPI.UpgradeTypeset

Note

Some maps have special upgrade limitations. Use Player.getMaxUpgradeLevel() to check if an upgrade is available.

See also

Player.getMaxUpgradeLevel()

whatBuilds() → unitType, int

Obtains the source unit type that is used to build or train this unit type, as well as the amount of them that are required.

Important

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

Returns:Two values, where the first value is the UnitType that builds this unit type, and the second value is the number of those types that are required (this value is 2 for Archons <BWAPI.UnitType.Protoss_Archon>, and 1 for all other types). Returns nil if this unit type cannot be made by the player. Return type:UnitType, int

width() → int

A macro for retrieving the width of the unit type, which is calculated using dimensionLeft + dimensionRight + 1.

Returns:Width of the unit, in pixels. Return type:int

UnitTypeset

class BWAPI.UnitTypeset

A container for a set of UnitType objects.

Constructors

UnitTypeset()

Default constructor.

UnitTypeset(set)

Copy constructor.

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

UnitTypeset(tbl)

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

Parameters:tbl (table) – A table containing UnitType objects.

Member Functions

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