units.py
- class sc2.units.Units(units, bot_object)
A collection of Unit objects. Makes it easy to select units by selectors.
- closer_than(distance, position)
Returns all units (from this Units object) that are closer than ‘distance’ away from target unit or position.
Example:
enemy_zerglings = self.enemy_units(UnitTypeId.ZERGLING) my_marine = next((unit for unit in self.units if unit.type_id == UnitTypeId.MARINE), None) if my_marine: close_zerglings = enemy_zerglings.closer_than(3, my_marine) # Contains all zerglings that are distance 3 or less away from the marine (does not include unit radius in calculation)
- closest_distance_to(position)
Returns the distance between the closest unit from this group to the target unit.
Example:
enemy_zerglings = self.enemy_units(UnitTypeId.ZERGLING) my_marine = next((unit for unit in self.units if unit.type_id == UnitTypeId.MARINE), None) if my_marine: closest_zergling_distance = enemy_zerglings.closest_distance_to(my_marine) # Contains the distance between the marine and the closest zergling
- closest_n_units(position, n)
Returns the n closest units in distance to position.
Example:
enemy_zerglings = self.enemy_units(UnitTypeId.ZERGLING) my_marine = next((unit for unit in self.units if unit.type_id == UnitTypeId.MARINE), None) if my_marine: zerglings_filtered = enemy_zerglings.closest_n_units(my_marine, 5) # Contains 5 zerglings that are the closest to the marine
- closest_to(position)
Returns the closest unit (from this Units object) to the target unit or position.
Example:
enemy_zerglings = self.enemy_units(UnitTypeId.ZERGLING) my_marine = next((unit for unit in self.units if unit.type_id == UnitTypeId.MARINE), None) if my_marine: closest_zergling = enemy_zerglings.closest_to(my_marine) # Contains the zergling that is closest to the target marine
- copy()
Creates a new mutable Units object from Units or list object.
- Parameters
units –
- Return type
- exclude_type(other)
Filters all units that are not of a specific type
Example:
# Use a set instead of lists in the argument ignore_units = self.enemy_units.exclude_type({LARVA, EGG, OVERLORD})
- Parameters
other (
Union[UnitTypeId,Iterable[UnitTypeId]]) –- Return type
- filter(pred)
Filters the current Units object and returns a new Units object.
Example:
from sc2.ids.unit_typeid import UnitTypeId my_marines = self.units.filter(lambda unit: unit.type_id == UnitTypeId.MARINE) completed_structures = self.structures.filter(lambda structure: structure.is_ready) queens_with_energy_to_inject = self.units.filter(lambda unit: unit.type_id == UnitTypeId.QUEEN and unit.energy >= 25) orbitals_with_energy_to_mule = self.structures.filter(lambda structure: structure.type_id == UnitTypeId.ORBITALCOMMAND and structure.energy >= 50) my_units_that_can_shoot_up = self.units.filter(lambda unit: unit.can_attack_air)
See more unit properties in unit.py
- further_than(distance, position)
Returns all units (from this Units object) that are further than ‘distance’ away from target unit or position.
Example:
enemy_zerglings = self.enemy_units(UnitTypeId.ZERGLING) my_marine = next((unit for unit in self.units if unit.type_id == UnitTypeId.MARINE), None) if my_marine: far_zerglings = enemy_zerglings.further_than(3, my_marine) # Contains all zerglings that are distance 3 or more away from the marine (does not include unit radius in calculation)
- furthest_distance_to(position)
Returns the distance between the furthest unit from this group to the target unit
Example:
enemy_zerglings = self.enemy_units(UnitTypeId.ZERGLING) my_marine = next((unit for unit in self.units if unit.type_id == UnitTypeId.MARINE), None) if my_marine: furthest_zergling_distance = enemy_zerglings.furthest_distance_to(my_marine) # Contains the distance between the marine and the furthest away zergling
- furthest_n_units(position, n)
Returns the n furhest units in distance to position.
Example:
enemy_zerglings = self.enemy_units(UnitTypeId.ZERGLING) my_marine = next((unit for unit in self.units if unit.type_id == UnitTypeId.MARINE), None) if my_marine: zerglings_filtered = enemy_zerglings.furthest_n_units(my_marine, 5) # Contains 5 zerglings that are the furthest to the marine
- furthest_to(position)
Returns the furhest unit (from this Units object) to the target unit or position.
Example:
enemy_zerglings = self.enemy_units(UnitTypeId.ZERGLING) my_marine = next((unit for unit in self.units if unit.type_id == UnitTypeId.MARINE), None) if my_marine: furthest_zergling = enemy_zerglings.furthest_to(my_marine) # Contains the zergling that is furthest away to the target marine
- property gathering: Units
Returns all workers that are mining minerals or vespene (gather command).
- Return type
- property idle: Units
Returns all units or structures that are doing nothing (unit is standing still, structure is doing nothing).
- Return type
- in_attack_range_of(unit, bonus_distance=0)
Filters units that are in attack range of the given unit. This uses the unit and target unit.radius when calculating the distance, so it should be accurate. Caution: This may not work well for static structures (bunker, sieged tank, planetary fortress, photon cannon, spine and spore crawler) because it seems attack ranges differ for static / immovable units.
Example:
enemy_zerglings = self.enemy_units(UnitTypeId.ZERGLING) my_marine = next((unit for unit in self.units if unit.type_id == UnitTypeId.MARINE), None) if my_marine: all_zerglings_my_marine_can_attack = enemy_zerglings.in_attack_range_of(my_marine)
Example:
enemy_mutalisks = self.enemy_units(UnitTypeId.MUTALISK) my_marauder = next((unit for unit in self.units if unit.type_id == UnitTypeId.MARAUDER), None) if my_marauder: all_mutalisks_my_marauder_can_attack = enemy_mutaliskss.in_attack_range_of(my_marauder) # Is empty because mutalisk are flying and marauder cannot attack air
- in_closest_distance_to_group(other_units)
Returns unit in shortest distance from any unit in self to any unit in group.
Loops over all units in self, then loops over all units in other_units and calculates the shortest distance. Returns the units that is closest to any unit of ‘other_units’.
- in_distance_between(position, distance1, distance2)
Returns units that are further than distance1 and closer than distance2 to unit or position.
Example:
enemy_zerglings = self.enemy_units(UnitTypeId.ZERGLING) my_marine = next((unit for unit in self.units if unit.type_id == UnitTypeId.MARINE), None) if my_marine: zerglings_filtered = enemy_zerglings.in_distance_between(my_marine, 3, 5) # Contains all zerglings that are between distance 3 and 5 away from the marine (does not include unit radius in calculation)
- in_distance_of_group(other_units, distance)
Returns units that are closer than distance from any unit in the other units object.
- n_closest_to_distance(position, distance, n)
Returns n units that are the closest to distance away. For example if the distance is set to 5 and you want 3 units, from units with distance [3, 4, 5, 6, 7] to position, the units with distance [4, 5, 6] will be returned
- n_furthest_to_distance(position, distance, n)
Inverse of the function ‘n_closest_to_distance’, returns the furthest units instead
- property not_ready: Units
Returns all structures that are not ready (construction not complete).
- Return type
- of_type(other)
Filters all units that are of a specific type
Example:
# Use a set instead of lists in the argument some_attack_units = self.units.of_type({ZERGLING, ROACH, HYDRALISK, BROODLORD})
- Parameters
other (
Union[UnitTypeId,Iterable[UnitTypeId]]) –- Return type
- property prefer_idle: Units
Sorts units based on if they are idle. Idle units come first.
- Return type
- property returning: Units
Returns all workers that are carrying minerals or vespene and are returning to a townhall.
- Return type
- same_tech(other)
Returns all structures that have the same base structure.
Untested: This should return the equivalents for WarpPrism, Observer, Overseer, SupplyDepot and others
Example:
# All command centers, flying command centers, orbital commands, flying orbital commands, planetary fortress terran_townhalls = self.townhalls.same_tech(UnitTypeId.COMMANDCENTER) # All hatcheries, lairs and hives zerg_townhalls = self.townhalls.same_tech({UnitTypeId.HATCHERY}) # All spires and greater spires spires = self.townhalls.same_tech({UnitTypeId.SPIRE}) # The following returns the same spires = self.townhalls.same_tech({UnitTypeId.GREATERSPIRE}) # This also works with multiple unit types zerg_townhalls_and_spires = self.structures.same_tech({UnitTypeId.HATCHERY, UnitTypeId.SPIRE})
- Parameters
other (
Set[UnitTypeId]) –- Return type
- same_unit(other)
Returns all units that have the same base unit while being in different modes.
Untested: This should return the equivalents for WarpPrism, Observer, Overseer, SupplyDepot and other units that have different modes but still act as the same unit
Example:
# All command centers on the ground and flying ccs = self.townhalls.same_unit(UnitTypeId.COMMANDCENTER) # All orbital commands on the ground and flying ocs = self.townhalls.same_unit(UnitTypeId.ORBITALCOMMAND) # All roaches and burrowed roaches roaches = self.units.same_unit(UnitTypeId.ROACH) # This is useful because roach has a different type id when burrowed burrowed_roaches = self.units(UnitTypeId.ROACHBURROWED)
- Parameters
other (
Union[UnitTypeId,Iterable[UnitTypeId]]) –- Return type
- sorted_by_distance_to(position, reverse=False)
This function should be a bit faster than using units.sorted(key=lambda u: u.distance_to(position))
- subgroup(units)
Creates a new mutable Units object from Units or list object.
- property tags: Set[int]
Returns all unit tags as a set.
- Return type
Set[int]
- tags_in(other)
Filters all units that have their tags in the ‘other’ set/list/dict
Example:
my_inject_queens = self.units.tags_in(self.queen_tags_assigned_to_do_injects) # Do not use the following as it is slower because it first loops over all units to filter out if they are queens and loops over those again to check if their tags are in the list/set my_inject_queens_slow = self.units(QUEEN).tags_in(self.queen_tags_assigned_to_do_injects)
- Parameters
other (
Iterable[int]) –- Return type
- tags_not_in(other)
Filters all units that have their tags not in the ‘other’ set/list/dict
Example:
my_non_inject_queens = self.units.tags_not_in(self.queen_tags_assigned_to_do_injects) # Do not use the following as it is slower because it first loops over all units to filter out if they are queens and loops over those again to check if their tags are in the list/set my_non_inject_queens_slow = self.units(QUEEN).tags_not_in(self.queen_tags_assigned_to_do_injects)
- Parameters
other (
Iterable[int]) –- Return type