Struct Unit

pub struct Unit { /* private fields */ }

Unit structure contains some raw data, helper methods for it’s analysis and some methods for actions execution.

Implementations

impl Unit

pub fn display_type(&self) -> DisplayType

How unit is displayed (i.e. visibility of unit).

pub fn alliance(&self) -> Alliance

Unit is owned, enemy or just neutral.

pub fn tag(&self) -> u64

Unique and constant for each unit tag. Used to find exactly the same unit in bunch of Units. See also get, get_mut and find_tags.

pub fn type_id(&self) -> UnitTypeId

The type of unit.

pub fn owner(&self) -> u32

Player id of the owner. Normally it should match your player_id for owned units and enemy_player_id for opponent’s units.

pub fn position(&self) -> Point2

Position on 2D grid.

pub fn position3d(&self) -> Point3

Position in 3D world space.

pub fn facing(&self) -> f32

Unit rotation angle (i.e. the direction unit is facing). Value in range [0, 2π).

pub fn radius(&self) -> f32

Radius of the unit.

pub fn build_progress(&self) -> f32

The progress of building construction. Value from 0 to 1.

pub fn is_cloaked(&self) -> bool

true when unit is burrowed or has cloak field turned on.

pub fn is_revealed(&self) -> bool

true when unit is detected.

pub fn buffs(&self) -> &FxHashSet<BuffId>

Set of buffs unit has.

pub fn detect_range(&self) -> f32

Detection range of detector or 0 if unit is not detector. See also is_detector.

pub fn radar_range(&self) -> f32

Range of terran’s sensor tower.

pub fn is_selected(&self) -> bool

Unit is selected.

pub fn is_on_screen(&self) -> bool

Unit is visible in game window.

pub fn is_blip(&self) -> bool

Enemies detected by sensor tower.

pub fn is_powered(&self) -> bool

Protoss structure is powered by pylon.

pub fn is_active(&self) -> bool

Building is training/researching (i.e. animated).

pub fn attack_upgrade_level(&self) -> u32

General attack upgrade level without considering buffs and special upgrades.

pub fn armor_upgrade_level(&self) -> i32

General armor upgrade level without considering buffs and special upgrades.

pub fn shield_upgrade_level(&self) -> i32

General shield upgrade level without considering buffs and special upgrades.

pub fn health(&self) -> Option<u32>

Current health of unit.

Note: Not populated for snapshots.

pub fn health_max(&self) -> Option<u32>

Maximum health of unit.

Note: Not populated for snapshots.

pub fn shield(&self) -> Option<u32>

Current shield of protoss unit.

Note: Not populated for snapshots.

pub fn shield_max(&self) -> Option<u32>

Maximum shield of protoss unit.

Note: Not populated for snapshots.

pub fn energy(&self) -> Option<u32>

Current energy of caster unit.

Note: Not populated for snapshots.

pub fn energy_max(&self) -> Option<u32>

Maximum energy of caster unit.

Note: Not populated for snapshots.

pub fn mineral_contents(&self) -> Option<u32>

Amount of minerals left in mineral field.

Note: Not populated for snapshots.

pub fn vespene_contents(&self) -> Option<u32>

Amount of vespene gas left in vespene geyser.

Note: Not populated for snapshots.

pub fn is_flying(&self) -> bool

Unit is flying.

Note: Not populated for snapshots.

pub fn is_burrowed(&self) -> bool

Zerg unit is burrowed.

Note: Not populated for snapshots.

pub fn is_hallucination(&self) -> bool

Is hallucination created by protoss sentry.

Note: Not populated for snapshots.

pub fn orders(&self) -> &[UnitOrder]

Current orders of unit.

Note: Not populated for enemies.

pub fn addon_tag(&self) -> Option<u64>

Tag of addon if any.

Note: Not populated for enemies.

pub fn passengers(&self) -> &[PassengerUnit]

Units inside transport or bunker.

Note: Not populated for enemies.

pub fn cargo_space_taken(&self) -> Option<u32>

Used space of transport or bunker.

Note: Not populated for enemies.

pub fn cargo_space_max(&self) -> Option<u32>

Maximum space of transport or bunker.

Note: Not populated for enemies.

pub fn assigned_harvesters(&self) -> Option<u32>

Current number of workers on gas or base.

Note: Not populated for enemies.

pub fn ideal_harvesters(&self) -> Option<u32>

Ideal number of workers on gas or base.

Note: Not populated for enemies.

pub fn weapon_cooldown(&self) -> Option<f32>

Frames left until weapon will be ready to shot.

Note: Not populated for enemies.

pub fn engaged_target_tag(&self) -> Option<u64>

pub fn buff_duration_remain(&self) -> Option<u32>

How long a buff or unit is still around (e.g. mule, broodling, chronoboost).

Note: Not populated for enemies.

pub fn buff_duration_max(&self) -> Option<u32>

How long the maximum duration of buff or unit (e.g. mule, broodling, chronoboost).

Note: Not populated for enemies.

pub fn rally_targets(&self) -> &[RallyTarget]

All rally points of structure.

Note: Not populated for enemies.

pub fn name(&self) -> &str

Name of the unit

pub fn is_worker(&self) -> bool

Checks if unit is worker.

pub fn is_townhall(&self) -> bool

Checks if it’s townhall.

pub fn is_addon(&self) -> bool

Checks if it’s addon.

pub fn is_melee(&self) -> bool

Checks if unit is melee attacker.

pub fn is_mineral(&self) -> bool

Checks if it’s mineral field.

pub fn is_geyser(&self) -> bool

Checks if it’s vespene geyser.

pub fn is_detector(&self) -> bool

Checks if unit is detector.

pub fn is_ready(&self) -> bool

Building construction is complete.

pub fn is_almost_ready(&self) -> bool

Building construction is more than 95% complete.

pub fn has_addon(&self) -> bool

Terran building has addon.

pub fn has_techlab(&self) -> bool

Terran building’s addon is techlab if any.

pub fn has_reactor(&self) -> bool

Terran building’s addon is reactor if any.

pub fn is_attacked(&self) -> bool

Unit was attacked on last step.

pub fn damage_taken(&self) -> u32

The damage was taken by unit if it was attacked, otherwise it’s 0.

pub fn abilities(&self) -> Option<FxHashSet<AbilityId>>

Abilities available for unit to use.

Ability won’t be available if it’s on cooldown, unit is out of energy or bot doesn’t have enough resources.

pub fn has_ability(&self, ability: AbilityId) -> bool

Checks if ability is available for unit.

Ability won’t be available if it’s on cooldown, unit is out of energy or bot doesn’t have enough resources.

pub fn race(&self) -> Race

Race of unit, dependent on it’s type.

pub fn has_cargo(&self) -> bool

There’re some units inside transport or bunker.

pub fn cargo_left(&self) -> Option<u32>

Free space left in transport or bunker.

pub fn footprint_radius(&self) -> Option<f32>

Half of building_size, but 2.5 for addons.

pub fn building_size(&self) -> Option<usize>

Correct building size in tiles (e.g. 2 for supply and addons, 3 for barracks, 5 for command center).

pub fn build_time(&self) -> f32

How long a unit takes to build.

pub fn cargo_size(&self) -> u32

Space that unit takes in transports and bunkers.

pub fn sight_range(&self) -> f32

How far unit can see.

pub fn armor(&self) -> i32

Initial armor of unit without considering upgrades and buffs.

pub fn towards_facing(&self, offset: f32) -> Point2

Returns point with given offset towards unit face direction.

pub fn is_visible(&self) -> bool

Checks if unit is fully visible.

pub fn is_snapshot(&self) -> bool

Checks if unit is snapshot (i.e. hidden in fog of war or on high ground).

pub fn is_hidden(&self) -> bool

Checks if unit is fully hidden.

pub fn is_placeholder(&self) -> bool

Checks if unit is building placeholder.

pub fn is_mine(&self) -> bool

Checks if unit is owned.

pub fn is_enemy(&self) -> bool

Checks if unit is enemy.

pub fn is_neutral(&self) -> bool

Checks if unit is neutral.

pub fn is_ally(&self) -> bool

Checks if unit is allied, but not owned.

pub fn can_be_attacked(&self) -> bool

Checks if unit is detected or not even cloaked.

pub fn is_invisible(&self) -> bool

Checks if unit is burrowed or cloaked, and not detected (i.e. must be detected to be attacked).

pub fn supply_cost(&self) -> f32

Returns how much supply this unit uses.

pub fn cost(&self) -> Cost

Returns cost of unit.

pub fn health_percentage(&self) -> Option<f32>

Returns health percentage (current health divided by max health). Value in range from 0 to 1.

pub fn shield_percentage(&self) -> Option<f32>

Returns shield percentage (current shield divided by max shield). Value in range from 0 to 1.

pub fn energy_percentage(&self) -> Option<f32>

Returns energy percentage (current energy divided by max energy). Value in range from 0 to 1.

pub fn hits(&self) -> Option<u32>

Returns summed health and shield.

Not populated for snapshots.

pub fn hits_max(&self) -> Option<u32>

Returns summed max health and max shield.

Not populated for snapshots.

pub fn hits_percentage(&self) -> Option<f32>

Returns percentage of summed health and shield (current hits divided by max hits). Value in range from 0 to 1.

Not populated for snapshots.

pub fn speed(&self) -> f32

Basic speed of the unit without considering buffs and upgrades.

Use real_speed to get speed including buffs and upgrades.

pub fn real_speed(&self) -> f32

Returns actual speed of the unit calculated including buffs and upgrades.

pub fn distance_per_step(&self) -> f32

Distance unit can travel per one step.

pub fn distance_to_weapon_ready(&self) -> f32

Distance unit can travel until weapons be ready to fire.

pub fn attributes(&self) -> &[Attribute]

Attributes of unit, dependent on it’s type.

pub fn has_attribute(&self, attribute: Attribute) -> bool

Checks if unit has given attribute.

pub fn is_light(&self) -> bool

Checks if unit has Light attribute.

pub fn is_armored(&self) -> bool

Checks if unit has Armored attribute.

pub fn is_biological(&self) -> bool

Checks if unit has Biological attribute.

pub fn is_mechanical(&self) -> bool

Checks if unit has Mechanical attribute.

pub fn is_robotic(&self) -> bool

Checks if unit has Robotic attribute.

pub fn is_psionic(&self) -> bool

Checks if unit has Psionic attribute.

pub fn is_massive(&self) -> bool

Checks if unit has Massive attribute.

pub fn is_structure(&self) -> bool

Checks if unit has Structure attribute.

pub fn is_hover(&self) -> bool

Checks if unit has Hover attribute.

pub fn is_heroic(&self) -> bool

Checks if unit has Heroic attribute.

pub fn is_summoned(&self) -> bool

Checks if unit has Summoned attribute.

pub fn has_buff(&self, buff: BuffId) -> bool

Checks if unit has given buff.

pub fn has_any_buff<'a, B: IntoIterator<Item = &'a BuffId>>( &self, buffs: B, ) -> bool

Checks if unit has any from given buffs.

pub fn is_carrying_minerals(&self) -> bool

Checks if worker is carrying minerals.

pub fn is_carrying_vespene(&self) -> bool

Checks if worker is carrying vespene gas (Currently not works if worker is carrying gas from rich vespene geyeser, because SC2 API is not providing this information).

pub fn is_carrying_resource(&self) -> bool

Checks if worker is carrying any resource (Currently not works if worker is carrying gas from rich vespene geyeser, because SC2 API is not providing this information)

pub fn weapons(&self) -> &[Weapon]

pub fn weapon_target(&self) -> Option<TargetType>

Targets unit can attack if it has weapon.

pub fn can_attack(&self) -> bool

Checks if unit can attack at all (i.e. has weapons).

pub fn can_attack_both(&self) -> bool

Checks if unit can attack both air and ground targets.

pub fn can_attack_ground(&self) -> bool

Checks if unit can attack ground targets.

pub fn can_attack_air(&self) -> bool

Checks if unit can attack air targets.

pub fn can_attack_unit(&self, target: &Unit) -> bool

Checks if unit can attack given target.

pub fn on_cooldown(&self) -> bool

Checks if unit’s weapon is on cooldown.

pub fn max_cooldown(&self) -> Option<f32>

Returns max cooldown in frames for unit’s weapon.

pub fn cooldown_percentage(&self) -> Option<f32>

Returns weapon cooldown percentage (current cooldown divided by max cooldown). Value in range from 0 to 1.

pub fn ground_range(&self) -> f32

Returns ground range of unit’s weapon without considering upgrades. Use real_ground_range to get range including upgrades.

pub fn air_range(&self) -> f32

Returns air range of unit’s weapon without considering upgrades. Use real_air_range to get range including upgrades.

pub fn range_vs(&self, target: &Unit) -> f32

Returns range of unit’s weapon vs given target if unit can it, otherwise returns 0. Doesn’t consider upgrades, use real_range_vs instead to get range including upgrades.

pub fn real_ground_range(&self) -> f32

Returns actual ground range of unit’s weapon including upgrades.

pub fn real_air_range(&self) -> f32

Returns actual air range of unit’s weapon including upgrades.

pub fn real_range_vs(&self, target: &Unit) -> f32

Returns actual range of unit’s weapon vs given target if unit can attack it, otherwise returs 0. Takes upgrades into account.

pub fn ground_dps(&self) -> f32

Returns ground dps of unit’s weapon without considering upgrades. Use real_ground_weapon to get dps including upgrades.

pub fn air_dps(&self) -> f32

Returns air dps of unit’s weapon without considering upgrades. Use real_air_weapon to get dps including upgrades.

pub fn dps_vs(&self, target: &Unit) -> f32

Returns dps of unit’s weapon vs given target if unit can it, otherwise returns 0. Doesn’t consider upgrades, use real_weapon_vs instead to get dps including upgrades.

pub fn real_weapon(&self, attributes: &[Attribute]) -> (f32, f32)

Returns (dps, range) of first unit’s weapon including bonuses from buffs and upgrades.

If you need to get only real range of unit, use real_ground_range, real_air_range or real_range_vs instead, because they’re generally faster.

pub fn real_ground_weapon(&self, attributes: &[Attribute]) -> (f32, f32)

Returns (dps, range) of unit’s ground weapon including bonuses from buffs and upgrades.

If you need to get only real range of unit, use real_ground_range instead, because it’s generally faster.

pub fn real_air_weapon(&self, attributes: &[Attribute]) -> (f32, f32)

Returns (dps, range) of unit’s air weapon including bonuses from buffs and upgrades.

If you need to get only real range of unit, use real_air_range instead, because it’s generally faster.

pub fn real_weapon_vs(&self, target: &Unit) -> (f32, f32)

Returns (dps, range) of unit’s weapon vs given target if unit can attack it, otherwise returs (0, 0). Takes buffs and upgrades into account.

If you need to get only real range of unit, use real_range_vs instead, because it’s generally faster.

pub fn calculate_weapon_abstract( &self, target_type: TargetType, attributes: &[Attribute], ) -> (f32, f32)

Returns (dps, range) of unit’s weapon vs given abstract target if unit can attack it, otherwise returs (0, 0). Abstract target is described by it’s type (air or ground) and attributes (e.g. light, armored, …).

If you need to get only real range of unit, use real_ground_range, real_air_range or real_range_vs instead, because they’re generally faster.

pub fn calculate_weapon_stats(&self, target: CalcTarget<'_>) -> (f32, f32)

Returns (dps, range) of unit’s weapon vs given target (can be unit or abstract) if unit can attack it, otherwise returs (0, 0).

If you need to get only real range of unit, use real_ground_range, real_air_range or real_range_vs instead, because they’re generally faster.

pub fn in_range(&self, target: &Unit, gap: f32) -> bool

Checks if unit is close enough to attack given target.

See also in_real_range which uses actual range of unit for calculations.

pub fn in_range_of(&self, threat: &Unit, gap: f32) -> bool

Checks if unit is close enough to be attacked by given threat. This unit.in_range_of(threat, gap) is equivalent to threat.in_range(unit, gap).

See also in_real_range_of which uses actual range of unit for calculation.

pub fn in_real_range(&self, target: &Unit, gap: f32) -> bool

Checks if unit is close enough to attack given target.

Uses actual range from real_range_vs in it’s calculations.

pub fn in_real_range_of(&self, threat: &Unit, gap: f32) -> bool

Checks if unit is close enough to be attacked by given threat. This unit.in_real_range_of(threat, gap) is equivalent to threat.in_real_range(unit, gap).

Uses actual range from real_range_vs in it’s calculations.

pub fn in_ability_cast_range<A>( &self, ability_id: AbilityId, target: A, gap: f32, ) -> bool

where A: Into<Point2> + Radius,

Checks if unit is close enough to use given ability on target.

pub fn damage_bonus(&self) -> Option<(Attribute, u32)>

Returns (attribute, bonus damage) for first unit’s weapon if any.

pub fn order(&self) -> Option<(AbilityId, Target, f32)>

Returns (ability, target, progress) of the current unit order or None if it’s idle.

pub fn target(&self) -> Target

Returns target of first unit’s order.

pub fn target_pos(&self) -> Option<Point2>

Returns target point of unit’s order if any.

pub fn target_tag(&self) -> Option<u64>

Returns target tag of unit’s order if any.

pub fn ordered_ability(&self) -> Option<AbilityId>

Returns ability of first unit’s order.

pub fn is_idle(&self) -> bool

Checks if unit don’t have any orders currently.

pub fn is_almost_idle(&self) -> bool

Checks if unit don’t have any orders currently or it’s order is more than 95% complete.

pub fn is_unused(&self) -> bool

Checks if production building with reactor don’t have any orders currently.

pub fn is_almost_unused(&self) -> bool

Checks if production building with reactor don’t have any orders currently or it’s order is more than 95% complete.

pub fn is_using(&self, ability: AbilityId) -> bool

Checks if unit is using given ability.

Doesn’t work with enemies.

pub fn is_using_any<A: Container<AbilityId>>(&self, abilities: &A) -> bool

Checks if unit is using any of given abilities.

Doesn’t work with enemies.

pub fn is_attacking(&self) -> bool

Checks if unit is currently attacking.

Doesn’t work with enemies.

pub fn is_moving(&self) -> bool

Checks if unit is currently moving.

Doesn’t work with enemies.

pub fn is_patrolling(&self) -> bool

Checks if unit is currently patrolling.

Doesn’t work with enemies.

pub fn is_repairing(&self) -> bool

Checks if SCV or MULE is currently repairing.

Doesn’t work with enemies.

pub fn is_gathering(&self) -> bool

Checks if worker is currently gathering resource.

Doesn’t work with enemies.

pub fn is_returning(&self) -> bool

Checks if worker is currently returning resource closest base.

Doesn’t work with enemies.

pub fn is_collecting(&self) -> bool

Checks if worker is currently gathering or returning resources.

Doesn’t work with enemies.

pub fn is_constructing(&self) -> bool

Checks if worker is currently constructing a building.

Doesn’t work with enemies.

pub fn is_making_addon(&self) -> bool

Checks if terran building is currently making addon.

Doesn’t work with enemies.

pub fn is_making_techlab(&self) -> bool

Checks if terran building is currently building techlab.

Doesn’t work with enemies.

pub fn is_making_reactor(&self) -> bool

Checks if terran building is currently building reactor.

Doesn’t work with enemies.

pub fn is_sleeping(&self) -> bool

Checks if unit is doing something important and it’s bad idea to interrupt it, so you can skip evaluating it anyway.

Use with sleep to skip evaluating units executing durable commands.

pub fn sleep(&self, duration: u32)

Makes unit ignore all your commands for given amount of frames.

Use with is_sleeping to skip evaluating units executing durable commands.

pub fn toggle_autocast(&self, ability: AbilityId)

Toggles autocast on given ability.

pub fn command(&self, ability: AbilityId, target: Target, queue: bool)

Orders unit to execute given command.

pub fn use_ability(&self, ability: AbilityId, queue: bool)

Orders unit to use given ability (This is equivalent of unit.command(ability, Target::None, queue)).

pub fn smart(&self, target: Target, queue: bool)

Orders unit a Smart ability (This is equivalent of right click).

pub fn attack(&self, target: Target, queue: bool)

Orders unit to attack given target.

pub fn move_to(&self, target: Target, queue: bool)

Orders unit to move to given target.

pub fn hold_position(&self, queue: bool)

Orders unit to hold position.

pub fn gather(&self, target: u64, queue: bool)

Orders worker to gather given resource.

pub fn return_resource(&self, queue: bool)

Orders worker to return resource to closest base.

pub fn stop(&self, queue: bool)

Orders unit to stop actions.

pub fn patrol(&self, target: Target, queue: bool)

Orders unit to patrol.

pub fn repair(&self, target: u64, queue: bool)

Orders SCV or MULE to repair given structure or mechanical unit.

pub fn cancel_building(&self, queue: bool)

Orders building which is in progress to cancel construction.

pub fn cancel_queue(&self, queue: bool)

Orders production building to cancel last unit in train queue.

pub fn build_gas(&self, target: u64, queue: bool)

Orders worker to build race gas building on given geyser.

pub fn build(&self, unit: UnitTypeId, target: Point2, queue: bool)

Orders worker to build something on given position.

pub fn train(&self, unit: UnitTypeId, queue: bool)

Orders production building to train given unit.

This also works for morphing units and building addons.

pub fn research(&self, upgrade: UpgradeId, queue: bool)

Orders building to research given upgrade.

pub fn warp_in(&self, unit: UnitTypeId, target: Point2)

Orders protoss warp gate to warp unit on given position.

pub fn lift(&self, queue: bool)

Orders terran building to lift in the air.

pub fn land(&self, target: Point2, queue: bool)

Orders flying terran building to land on given position.

Trait Implementations

impl Clone for Unit

fn clone(&self) -> Unit

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Extend<Unit> for Units

fn extend<T: IntoIterator<Item = Unit>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<&Unit> for Point2

fn from(u: &Unit) -> Self

Converts to this type from the input type.

impl From<Unit> for Point2

fn from(u: Unit) -> Self

Converts to this type from the input type.

impl FromIterator<Unit> for Units

fn from_iter<I: IntoIterator<Item = Unit>>(iter: I) -> Self

Creates a value from an iterator.

impl Radius for &Unit

fn radius(&self) -> f32

Radius for struct

impl Radius for Unit

fn radius(&self) -> f32

Radius for struct