unit.py
- class sc2.unit.Unit(proto_data, bot_object, distance_calculation_index=-1, base_build=-1)
- property add_on_land_position: Point2
If this unit is an addon (techlab, reactor), returns the position where a terran building (BARRACKS, FACTORY, STARPORT) has to land to connect to this addon.
Why offset (-2.5, 0.5)? See description in ‘add_on_position’
- property add_on_position: Point2
If this unit is a terran production building (BARRACKS, FACTORY, STARPORT), this property returns the position of where the addon should be, if it should build one or has one attached.
Why offset (2.5, -0.5)? A barracks is of size 3x3. The distance from the center to the edge is 1.5. An addon is 2x2 and the distance from the edge to center is 1. The total distance from center to center on the x-axis is 2.5. The distance from center to center on the y-axis is -0.5.
- property add_on_tag: int
Returns the tag of the addon of unit. If the unit has no addon, returns 0.
- Return type
int
- property age: float
Returns how old the unit object data is (in game seconds). This age does not reflect when the unit was created / trained / morphed!
- Return type
float
- property age_in_frames: int
Returns how old the unit object data is (in game frames). This age does not reflect the unit was created / trained / morphed!
- Return type
int
- property air_dps: float
Returns the dps against air units. Does not include upgrades.
- property air_range: float
Returns the range against air units. Does not include upgrades.
- property alliance: Alliance
Returns the team the unit belongs to.
- Return type
Alliance
- property armor: float
Returns the armor of the unit. Does not include upgrades
- Return type
float
- property armor_upgrade_level: int
Returns the upgrade level of the units armor.
- Return type
int
- property assigned_harvesters: int
Returns the number of workers currently gathering resources at a geyser or mining base.
- Return type
int
- attack(target, queue=False)
Orders unit to attack. Target can be a Unit or Point2. Attacking a position will make the unit move there and attack everything on its way.
- Parameters
- Return type
Union[UnitCommand,bool]
- property attack_upgrade_level: int
Returns the upgrade level of the units attack. # NOTE: Returns 0 for units without a weapon.
- Return type
int
- property bonus_damage: Optional[Tuple[int, str]]
Returns a tuple of form ‘(bonus damage, armor type)’ if unit does ‘bonus damage’ against ‘armor type’. Possible armor typs are: ‘Light’, ‘Armored’, ‘Biological’, ‘Mechanical’, ‘Psionic’, ‘Massive’, ‘Structure’.
- property buff_duration_max: int
Returns the maximum amount of frames of the visible timer bar. # NOTE: Returns 0 for units without a timer bar.
- Return type
int
- property buff_duration_remain: int
Returns the amount of remaining frames of the visible timer bar. # NOTE: Returns 0 for units without a timer bar.
- Return type
int
- build(unit, position=None, queue=False, can_afford_check=False)
Orders unit to build another ‘unit’ at ‘position’. Usage:
SCV.build(COMMANDCENTER, position) # Target for refinery, assimilator and extractor needs to be the vespene geysir unit, not its position SCV.build(REFINERY, target_vespene_geysir)
- Parameters
unit (
UnitTypeId) –position (
Optional[Point2]) –queue (
bool) –can_afford_check (
bool) –
- Return type
Union[UnitCommand,bool]
- build_gas(target_geysir, queue=False, can_afford_check=False)
Orders unit to build another ‘unit’ at ‘position’. Usage:
# Target for refinery, assimilator and extractor needs to be the vespene geysir unit, not its position SCV.build_gas(target_vespene_geysir)
- Parameters
target_geysir (
Unit) –queue (
bool) –can_afford_check (
bool) –
- Return type
Union[UnitCommand,bool]
- property build_progress: float
Returns completion in range [0,1].
- Return type
float
- calculate_damage_vs_target(target, ignore_armor=False, include_overkill_damage=True)
Returns a tuple of: [potential damage against target, attack speed, attack range] Returns the properly calculated damage per full-attack against the target unit. Returns (0, 0, 0) if this unit can’t attack the target unit.
If ‘include_overkill_damage=True’ and the unit deals 10 damage, the target unit has 5 hp and 0 armor, the target unit would result in -5hp, so the returning damage would be 10. For ‘include_overkill_damage=False’ this function would return 5.
If ‘ignore_armor=False’ and the unit deals 10 damage, the target unit has 20 hp and 5 armor, the target unit would result in 15hp, so the returning damage would be 5. For ‘ignore_armor=True’ this function would return 10.
- Parameters
target (
Unit) –ignore_armor (
bool) –include_overkill_damage (
bool) –
- Return type
Tuple[float,float,float]
- calculate_dps_vs_target(target, ignore_armor=False, include_overkill_damage=True)
Returns the DPS against the given target.
- Parameters
target (
Unit) –ignore_armor (
bool) –include_overkill_damage (
bool) –
- Return type
float
- calculate_speed(upgrades=None)
Calculates the movement speed of the unit including buffs and upgrades. Note: Upgrades only work with own units. Use “upgrades” param to set expected enemy upgrades.
- Parameters
upgrades (
Optional[Set[UpgradeId]]) –- Return type
float
- property can_attack: bool
Checks if the unit can attack at all.
- property can_attack_air: bool
Checks if the unit can air attack at all. Does not include upgrades.
- property can_attack_both: bool
Checks if the unit can attack both ground and air units.
- Return type
bool
- property can_attack_ground: bool
Checks if the unit can attack ground units.
- property can_be_attacked: bool
Checks if the unit is revealed or not cloaked and therefore can be attacked.
- Return type
bool
- property cargo_left: int
Returns how much cargo space is currently left in the unit.
- Return type
int
- property cargo_max: int
How much cargo space is available at maximum.
- Return type
int
- property cargo_size: int
Returns the amount of cargo space the unit needs.
- Return type
int
- property cargo_used: int
Returns how much cargo space is currently used in the unit. Note that some units take up more than one space.
- Return type
int
- property cloak: CloakState
Returns cloak state. See https://github.com/Blizzard/s2client-api/blob/d9ba0a33d6ce9d233c2a4ee988360c188fbe9dbf/include/sc2api/sc2_unit.h#L95
- Return type
CloakState
- property detect_range: float
Returns the detection distance of the unit.
- Return type
float
- property distance_per_step: float
The distance a unit can move in one step. This does not take acceleration into account. Useful for micro-retreat/pathfinding
- Return type
float
- distance_to(p)
Using the 2d distance between self and p. To calculate the 3d distance, use unit.position3d.distance_to(p)
- distance_to_squared(p)
Using the 2d distance squared between self and p. Slightly faster than distance_to, so when filtering a lot of units, this function is recommended to be used. To calculate the 3d distance, use unit.position3d.distance_to(p)
- property distance_to_weapon_ready: float
Distance a unit can travel before it’s weapon is ready to be fired again.
- Return type
float
- property energy: float
Returns the amount of energy the unit has. Returns 0 for units without energy.
- Return type
float
- property energy_max: float
Returns the maximum amount of energy the unit can have. Returns 0 for units without energy.
- Return type
float
- property energy_percentage: float
Returns the percentage of amount of energy the unit has. Returns 0 for units without energy.
- property facing: float
Returns direction the unit is facing as a float in range [0,2π). 0 is in direction of x axis.
- Return type
float
- property footprint_radius: Optional[float]
For structures only. For townhalls this returns 2.5 For barracks, spawning pool, gateway, this returns 1.5 For supply depot, this returns 1 For sensor tower, creep tumor, this return 0.5
NOTE: This can be None if a building doesn’t have a creation ability. For rich vespene buildings, flying terran buildings, this returns None
- Return type
Optional[float]
- gather(target, queue=False)
Orders a unit to gather minerals or gas. ‘Target’ must be a mineral patch or a gas extraction building.
- Parameters
target (
Unit) –queue (
bool) –
- Return type
Union[UnitCommand,bool]
- property ground_dps: float
Returns the dps against ground units. Does not include upgrades.
- property ground_range: float
Returns the range against ground units. Does not include upgrades.
- property has_add_on: bool
Checks if unit has an addon attached.
- Return type
bool
- property has_cargo: bool
Checks if this unit has any units loaded.
- Return type
bool
- property has_reactor: bool
Check if a structure is connected to a reactor addon. This should only ever return True for BARRACKS, FACTORY, STARPORT.
- property has_techlab: bool
Check if a structure is connected to a techlab addon. This should only ever return True for BARRACKS, FACTORY, STARPORT.
- property has_vespene: bool
Checks if a geyser has any gas remaining. You can’t build extractors on empty geysers.
- Return type
bool
- property health: float
Returns the health of the unit. Does not include shields.
- Return type
float
- property health_max: float
Returns the maximum health of the unit. Does not include shields.
- Return type
float
- property health_percentage: float
Returns the percentage of health the unit has. Does not include shields.
- hold_position(queue=False)
Orders a unit to stop moving. It will not move until it gets new orders.
- Parameters
queue (
bool) –- Return type
Union[UnitCommand,bool]
- property ideal_harvesters: int
Returns the ideal harverster count for unit. 3 for gas buildings, 2*n for n mineral patches on that base.
- Return type
int
- in_ability_cast_range(ability_id, target, bonus_distance=0)
Test if a unit is able to cast an ability on the target without checking ability cooldown (like stalker blink) or if ability is made available through research (like HT storm).
- property is_active: bool
Checks if the unit has an order (e.g. unit is currently moving or attacking, structure is currently training or researching).
- Return type
bool
- property is_armored: bool
Checks if the unit has the ‘armored’ attribute.
- Return type
bool
- property is_attacking: bool
Checks if the unit is attacking. Only works for own units.
- property is_biological: bool
Checks if the unit has the ‘biological’ attribute.
- Return type
bool
- property is_blip: bool
Checks if the unit is detected by a sensor tower.
- Return type
bool
- property is_burrowed: bool
Checks if the unit is burrowed.
- Return type
bool
- property is_carrying_minerals: bool
Checks if a worker or MULE is carrying (gold-)minerals.
- property is_carrying_resource: bool
Checks if a worker is carrying a resource.
- property is_carrying_vespene: bool
Checks if a worker is carrying vespene gas.
- property is_cloaked: bool
Checks if the unit is cloaked.
- Return type
bool
- property is_collecting: bool
Checks if a unit is gathering or returning. Only works for own units.
- property is_constructing_scv: bool
Checks if the unit is an SCV that is currently building. Only works for own units.
- property is_detector: bool
Checks if the unit is a detector. Has to be completed in order to detect and Photoncannons also need to be powered.
- property is_enemy: bool
Checks if the unit is hostile.
- Return type
bool
- is_facing(other_unit, angle_error=0.05)
Check if this unit is facing the target unit. If you make angle_error too small, there might be rounding errors. If you make angle_error too big, this function might return false positives.
- Parameters
other_unit (
Unit) –angle_error (
float) –
- Return type
bool
- property is_flying: bool
Checks if the unit is flying.
- Return type
bool
- property is_gathering: bool
Checks if a unit is on its way to a mineral field or vespene geyser to mine. Only works for own units.
- property is_hallucination: bool
Returns True if the unit is your own hallucination or detected.
- Return type
bool
- property is_idle: bool
Checks if unit is idle.
- Return type
bool
- property is_light: bool
Checks if the unit has the ‘light’ attribute.
- Return type
bool
- property is_massive: bool
Checks if the unit has the ‘massive’ attribute.
- Return type
bool
- property is_mechanical: bool
Checks if the unit has the ‘mechanical’ attribute.
- Return type
bool
- property is_memory: bool
Returns True if this Unit object is referenced from the future and is outdated.
- Return type
bool
- property is_mine: bool
Checks if the unit is controlled by the bot.
- Return type
bool
- property is_mineral_field: bool
Checks if the unit is a mineral field.
- Return type
bool
- property is_moving: bool
Checks if the unit is moving. Only works for own units.
- property is_on_screen: bool
Checks if the unit is on the screen.
- Return type
bool
- property is_patrolling: bool
Checks if a unit is patrolling. Only works for own units.
- property is_placeholder: bool
Checks if the unit is a placerholder for the bot. Raw information about placeholders:
display_type: Placeholder alliance: Self unit_type: 86 owner: 1 pos {
x: 29.5 y: 53.5 z: 7.98828125
} radius: 2.75 is_on_screen: false
- Return type
bool
- property is_powered: bool
Checks if the unit is powered by a pylon or warppism.
- Return type
bool
- property is_psionic: bool
Checks if the unit has the ‘psionic’ attribute.
- Return type
bool
- property is_ready: bool
Checks if the unit is completed.
- Return type
bool
- property is_repairing: bool
Checks if the unit is an SCV or MULE that is currently repairing. Only works for own units.
- property is_returning: bool
Checks if a unit is returning from mineral field or vespene geyser to deliver resources to townhall. Only works for own units.
- property is_revealed: bool
Checks if the unit is revealed.
- Return type
bool
- property is_selected: bool
Checks if the unit is currently selected.
- Return type
bool
- property is_snapshot: bool
Checks if the unit is only available as a snapshot for the bot. Enemy buildings that have been scouted and are in the fog of war or attacking enemy units on higher, not visible ground appear this way.
- property is_structure: bool
Checks if the unit is a structure.
- Return type
bool
- property is_transforming: bool
Checks if the unit transforming. Only works for own units.
- is_using_ability(abilities)
Check if the unit is using one of the given abilities. Only works for own units.
- Return type
bool
- property is_vespene_geyser: bool
Checks if the unit is a non-empty vespene geyser or gas extraction building.
- Return type
bool
- property is_visible: bool
Checks if the unit is visible for the bot. NOTE: This means the bot has vision of the position of the unit! It does not give any information about the cloak status of the unit.
- property mineral_contents: int
Returns the amount of minerals remaining in a mineral field.
- Return type
int
- move(position, queue=False)
Orders the unit to move to ‘position’. Target can be a Unit (to follow that unit) or Point2.
- Parameters
- Return type
Union[UnitCommand,bool]
- property movement_speed: float
Returns the movement speed of the unit. This is the unit movement speed on game speed ‘normal’. To convert it to ‘faster’ movement speed, multiply it by a factor of ‘1.4’. E.g. reaper movement speed is listed here as 3.75, but should actually be 5.25. Does not include upgrades or buffs.
- Return type
float
- property name: str
Returns the name of the unit.
- Return type
str
- property order_target: Optional[Union[int, Point2]]
Returns the target tag (if it is a Unit) or Point2 (if it is a Position) from the first order, returns None if the unit is idle
- property orders: List[UnitOrder]
Returns the a list of the current orders.
- property owner_id: int
Returns the owner of the unit. This is a value of 1 or 2 in a two player game.
- Return type
int
- property passengers: Set[Unit]
Returns the units inside a Bunker, CommandCenter, PlanetaryFortress, Medivac, Nydus, Overlord or WarpPrism.
- property passengers_tags: Set[int]
Returns the tags of the units inside a Bunker, CommandCenter, PlanetaryFortress, Medivac, Nydus, Overlord or WarpPrism.
- patrol(position, queue=False)
Orders a unit to patrol between position it has when the command starts and the target position. Can be queued up to seven patrol points. If the last point is the same as the starting point, the unit will patrol in a circle.
- Parameters
position (
Point2) –queue (
bool) –
- Return type
Union[UnitCommand,bool]
- property position_tuple: Tuple[float, float]
Returns the 2d position of the unit as tuple without conversion to Point2.
- Return type
Tuple[float,float]
- property race: Race
Returns the race of the unit
- property radius: float
Half of unit size. See https://liquipedia.net/starcraft2/Unit_Statistics_(Legacy_of_the_Void)
- Return type
float
- property rally_targets: List[RallyTarget]
Returns the queue of rallytargets of the structure.
- property real_speed: float
See ‘calculate_speed’.
- repair(repair_target, queue=False)
Order an SCV or MULE to repair.
- Parameters
repair_target (
Unit) –queue (
bool) –
- Return type
Union[UnitCommand,bool]
- research(upgrade, queue=False, can_afford_check=False)
Orders unit to research ‘upgrade’. Requires UpgradeId to be passed instead of AbilityId.
- Parameters
upgrade (
UpgradeId) –queue (
bool) –can_afford_check (
bool) –
- Return type
Union[UnitCommand,bool]
- return_resource(target=None, queue=False)
Orders the unit to return resource. Does not need a ‘target’.
- Parameters
target (
Optional[Unit]) –queue (
bool) –
- Return type
Union[UnitCommand,bool]
- property shield: float
Returns the shield points the unit has. Returns 0 for non-protoss units.
- Return type
float
- property shield_health_percentage: float
Returns the percentage of combined shield + hp points the unit has. Also takes build progress into account.
- property shield_max: float
Returns the maximum shield points the unit can have. Returns 0 for non-protoss units.
- Return type
float
- property shield_percentage: float
Returns the percentage of shield points the unit has. Returns 0 for non-protoss units.
- property shield_upgrade_level: int
Returns the upgrade level of the units shield. # NOTE: Returns 0 for units without a shield.
- Return type
int
- property sight_range: float
Returns the sight range of the unit.
- Return type
float
- smart(target, queue=False)
Orders the smart command. Equivalent to a right-click order.
- Parameters
- Return type
Union[UnitCommand,bool]
- stop(queue=False)
Orders a unit to stop, but can start to move on its own if it is attacked, enemy unit is in range or other friendly units need the space.
- Parameters
queue (
bool) –- Return type
Union[UnitCommand,bool]
- property surplus_harvesters: int
Returns a positive int if unit has too many harvesters mining, a negative int if it has too few mining. Will only works on townhalls, and gas buildings.
- Return type
int
- property tag: int
Returns the unique tag of the unit.
- Return type
int
- target_in_range(target, bonus_distance=0)
Checks if the target is in range. Includes the target’s radius when calculating distance to target.
- Parameters
target (
Unit) –bonus_distance (
float) –
- Return type
bool
- property tech_alias: Optional[List[UnitTypeId]]
Building tech equality, e.g. OrbitalCommand is the same as CommandCenter For Hive, this returns [UnitTypeId.Hatchery, UnitTypeId.Lair] For SCV, this returns None
- train(unit, queue=False, can_afford_check=False)
Orders unit to train another ‘unit’. Usage: COMMANDCENTER.train(SCV)
- Parameters
unit (
UnitTypeId) –queue (
bool) –can_afford_check (
bool) –
- Return type
Union[UnitCommand,bool]
- property type_id: UnitTypeId
UnitTypeId found in sc2/ids/unit_typeid.
- Return type
- property unit_alias: Optional[UnitTypeId]
Building type equality, e.g. FlyingOrbitalCommand is the same as OrbitalCommand For flying OrbitalCommand, this returns UnitTypeId.OrbitalCommand For SCV, this returns None
- property vespene_contents: int
Returns the amount of gas remaining in a geyser.
- Return type
int
- warp_in(unit, position, can_afford_check=False)
Orders Warpgate to warp in ‘unit’ at ‘position’.
- Parameters
unit (
UnitTypeId) –queue –
can_afford_check (
bool) –
- Return type
Union[UnitCommand,bool]
- property weapon_cooldown: float
Returns the time until the unit can fire again, returns -1 for units that can’t attack. Usage: if unit.weapon_cooldown == 0:
unit.attack(target)
- elif unit.weapon_cooldown < 0:
unit.move(closest_allied_unit_because_cant_attack)
- else:
unit.move(retreatPosition)
- Return type
float
- property weapon_ready: bool
Checks if the weapon is ready to be fired.
- Return type
bool