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.

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!

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!

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.

property armor: float: Returns the armor of the unit. Does not include upgrades

property armor_upgrade_level: int: Returns the upgrade level of the units armor.

property assigned_harvesters: int: Returns the number of workers currently gathering resources at a geyser or mining base.

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:

target (Union[Unit, Point2])
queue (bool)

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.

property bonus_damage: Tuple[int, str] | None: 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.

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.

property buffs: FrozenSet[BuffId]: Returns the set of current buffs the unit has.

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 (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].

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

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.

property cargo_left: int: Returns how much cargo space is currently left in the unit.

property cargo_max: int: How much cargo space is available at maximum.

property cargo_size: int: Returns the amount of cargo space the unit needs.

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.

property cloak: CloakState: Returns cloak state. See https://github.com/Blizzard/s2client-api/blob/d9ba0a33d6ce9d233c2a4ee988360c188fbe9dbf/include/sc2api/sc2_unit.h#L95

property detect_range: float: Returns the detection distance of the unit.

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

distance_to(p)

Using the 2d distance between self and p. To calculate the 3d distance, use unit.position3d.distance_to(p)

Parameters:: p (Union[Unit, Point2])
Return type:: float

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)

Parameters:: p (Union[Unit, Point2])
Return type:: float

property distance_to_weapon_ready: float: Distance a unit can travel before it’s weapon is ready to be fired again.

property energy: float: Returns the amount of energy the unit has. Returns 0 for units without energy.

property energy_max: float: Returns the maximum amount of energy the unit can have. Returns 0 for units without energy.

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.

property footprint_radius: float | None

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

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.

has_buff(buff)

Checks if unit has buff ‘buff’.

Parameters:: buff (BuffId)
Return type:: bool

property has_cargo: bool: Checks if this unit has any units loaded.

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.

property health: float: Returns the health of the unit. Does not include shields.

property health_max: float: Returns the maximum health of the unit. Does not include shields.

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.

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

Parameters:

ability_id (AbilityId)
target (Union[Unit, Point2])
bonus_distance (float)

Return type:

bool

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

property is_armored: bool: Checks if the unit has the ‘armored’ attribute.

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.

property is_blip: bool: Checks if the unit is detected by a sensor tower.

property is_burrowed: bool: Checks if the unit is burrowed.

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.

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.

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.

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.

property is_idle: bool: Checks if unit is idle.

property is_light: bool: Checks if the unit has the ‘light’ attribute.

property is_massive: bool: Checks if the unit has the ‘massive’ attribute.

property is_mechanical: bool: Checks if the unit has the ‘mechanical’ attribute.

property is_memory: bool: Returns True if this Unit object is referenced from the future and is outdated.

property is_mine: bool: Checks if the unit is controlled by the bot.

property is_mineral_field: bool: Checks if the unit is a mineral field.

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.

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

property is_powered: bool: Checks if the unit is powered by a pylon or warppism.

property is_psionic: bool: Checks if the unit has the ‘psionic’ attribute.

property is_ready: bool: Checks if the unit is completed.

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.

property is_selected: bool: Checks if the unit is currently selected.

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.

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.

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.

move(position, queue=False)

Orders the unit to move to ‘position’. Target can be a Unit (to follow that unit) or Point2.

Parameters:

position (Union[Unit, Point2])
queue (bool)

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.

property name: str: Returns the name of the unit.

property order_target: int | Point2 | None: 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.

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: Point2: Returns the 2d position of the unit.

property position3d: Point3: Returns the 3d position of the unit.

property position_tuple: Tuple[float, float]: Returns the 2d position of the unit as tuple without conversion to Point2.

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)

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 (Unit)
queue (bool)

Return type:

Union[UnitCommand, bool]

property shield: float: Returns the shield points the unit has. Returns 0 for non-protoss units.

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.

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.

property sight_range: float: Returns the sight range of the unit.

smart(target, queue=False)

Orders the smart command. Equivalent to a right-click order.

Parameters:

target (Union[Unit, Point2])
queue (bool)

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.

property tag: int: Returns the unique tag of the unit.

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: List[UnitTypeId] | None: 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.

property unit_alias: UnitTypeId | None: 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.

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)

property weapon_ready: bool: Checks if the weapon is ready to be fired.