Skip to content

Individual Combat Behaviors

CombatManeuver dataclass 

CombatManeuver(micros=list())

Bases: Behavior

Execute behaviors sequentially.

Add behaviors

Example: 

from ares import AresBot
from ares.behaviors.combat import CombatManeuver
from ares.behaviors.combat.individual import (
    DropCargo,
    KeepUnitSafe,
    PathUnitToTarget,
    PickUpCargo,
)

class MyBot(AresBot):
    mine_drop_medivac_tag: int

    async def on_step(self, iteration):
        # Left out here, but `self.mine_drop_medivac_tag`
        # bookkeeping is up to the user
        medivac: Optional[Unit] = self.unit_tag_dict.get(
            self.mine_drop_medivac_tag, None
        )
        if not medivac:
            return

        air_grid: np.ndarray = self.mediator.get_air_grid

        # initiate a new CombatManeuver
        mine_drop: CombatManeuver = CombatManeuver()

        # then add behaviors in the order they should be executed
        # first priority is picking up units
        # (will return False if no cargo and move to next behavior)
        mine_drop.add(
            PickUpCargo(
                unit=medivac,
                grid=air_grid,
                pickup_targets=mines_to_pickup
            )
        )

        # if there is cargo, path to target and drop them off
        if medivac.has_cargo:
            # path
            mine_drop.add(
                PathUnitToTarget(
                    unit=medivac,
                    grid=air_grid,
                    target=self.enemy_start_locations[0],
                )
            )
            # drop off the mines
            mine_drop.add(DropCargo(unit=medivac, target=medivac.position))

        # no cargo and no units to pick up, stay safe
        else:
            mine_drop.add(KeepUnitSafe(unit=medivac, grid=air_grid))

        # register the mine_drop behavior
        self.register_behavior(mine_drop)

Attributes:

Name Type Description
micros list[Behavior] (optional, default: [])

A list of behaviors that should be executed. (Optional)

add 

add(behavior)

Parameters:

Name Type Description Default
behavior CombatBehavior

Add a new combat behavior to the current maneuver object.

 required

Returns:

Type Description
None
Source code in src/ares/behaviors/combat/combat_maneuver.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def add(
    self,
    behavior: Union[
        "CombatIndividualBehavior", "CombatGroupBehavior", "CombatManeuver"
    ],
) -> None:
    """
    Parameters
    ----------
    behavior : CombatBehavior
        Add a new combat behavior to the current maneuver object.

    Returns
    -------
        None
    """
    self.micros.append(behavior)

AMove dataclass 

AMove(unit, target)

Bases: CombatIndividualBehavior

A-Move a unit to a target.

Example: 

from ares.behaviors.combat import AMove

self.register_behavior(AMove(unit, self.game_info.map_center))

Attributes:

Name Type Description
unit Unit

The unit to stay safe.
target Point2

Where the unit is going.

AttackTarget dataclass 

AttackTarget(unit, target, extra_range=0.0)

Bases: CombatIndividualBehavior

Shoot a target.

Example: 

from ares.behaviors.combat import AttackTarget

unit: Unit
target: Unit
self.register_behavior(AttackTarget(unit, target))

Attributes:

Name Type Description
unit Unit

The unit to shoot.
target Unit

The unit we want to shoot at.

DropCargo dataclass 

DropCargo(unit, target)

Bases: CombatIndividualBehavior

Handle releasing cargo from a container.

Medivacs, WarpPrism, Overlords, Nydus.

Example: 

from ares.behaviors.combat import DropCargo

unit: Unit
target: Unit
self.register_behavior(DropCargo(unit, target))

Attributes:

Name Type Description
unit Unit

The container unit.
target Point2

The target position where to drop the cargo.

KeepUnitSafe dataclass 

KeepUnitSafe(unit, grid)

Bases: CombatIndividualBehavior

Get a unit to safety based on the influence grid passed in.

Example: 

from ares.behaviors.combat import KeepUnitSafe

unit: Unit
grid: np.ndarray = self.mediator.get_ground_grid
self.register_behavior(KeepUnitSafe(unit, grid))

Attributes:

Name Type Description
unit Unit

The unit to stay safe.
grid ndarray

2D Grid which usually contains enemy influence.

PathUnitToTarget dataclass 

PathUnitToTarget(
    unit,
    grid,
    target,
    success_at_distance=0.0,
    sensitivity=5,
    smoothing=False,
    sense_danger=True,
    danger_distance=20.0,
    danger_threshold=5.0,
)

Bases: CombatIndividualBehavior

Path a unit to its target destination.

TODO: Add attack enemy in range logic / parameter Not added yet since that may be it's own Behavior

Example: 

from ares.behaviors.combat import PathUnitToTarget

unit: Unit
grid: np.ndarray = self.mediator.get_ground_grid
target: Point2 = self.game_info.map_center
self.register_behavior(PathUnitToTarget(unit, grid, target))

Attributes:

Name Type Description
unit Unit

The unit to path.
grid ndarray

2D Grid to path on.
target Point2

Target destination.
success_at_distance float (default: 0.0)

If unit has got this close, consider path behavior complete.
sensitivity int (default: 5)

Path precision.
smoothing bool (default: False)

Smooth out the path.
sense_danger bool (default: True)

Check for dangers, if none are present pathing query is skipped.
danger_distance float (default: 20.0)

If sense_danger=True, how far to check for dangers?
danger_threshold float (default: 5.0)

Influence at which a danger is respected.

PickUpCargo dataclass 

PickUpCargo(
    unit, grid, pickup_targets, cargo_switch_to_role=None
)

Bases: CombatIndividualBehavior

Handle loading cargo into a container.

Medivacs, WarpPrism, Overlords, Nydus.

Example: 

from ares.behaviors.combat import PickUpCargo

unit: Unit # medivac for example
grid: np.ndarray = self.mediator.get_ground_grid
pickup_targets: Union[Units, list[Unit]] = self.workers
self.register_behavior(PickUpCargo(unit, grid, pickup_targets))

Attributes:

Name Type Description
unit Unit

The container unit.
grid ndarray

Pathing grid for container unit.
pickup_targets Union[Units, list[Unit]]

Units we want to load into the container.
cargo_switch_to_role UnitRole (default: None)

Sometimes useful to switch cargo tp new role immediately after loading.

PlacePredictiveAoE dataclass 

PlacePredictiveAoE(
    unit,
    path,
    enemy_center_unit,
    aoe_ability,
    ability_delay,
)

Bases: CombatIndividualBehavior

Predict an enemy position and fire AoE accordingly.

Warning: Use this at your own risk. Work in progress.

TODO: Guess where the enemy is going based on how it's been moving. Cythonize this.

Attributes:

Name Type Description
unit Unit

The unit to fire the AoE.
path List[Point2]

How we're getting to the target position (the last point in the list)
enemy_center_unit Unit

Enemy unit to calculate positions based on.
aoe_ability AbilityId

AoE ability to use.
ability_delay int

Amount of frames between using the ability and the ability occurring.

ShootTargetInRange dataclass 

ShootTargetInRange(unit, targets, extra_range=0.0)

Bases: CombatIndividualBehavior

Find something to shoot at.

TODO: Currently only picks lowest health. Might want to pick best one shot KO for example

Example: 

from ares.behaviors.combat import ShootTargetInRange

unit: Unit
target: Unit
self.register_behavior(ShootTargetInRange(unit, target))

Attributes:

Name Type Description
unit Unit

The unit to shoot.
targets Union[list[Unit], Units]

Units we want to check.
extra_range float(optional)

Look outside unit weapon range. This might be useful for hunting down low hp units.

StutterUnitBack dataclass 

StutterUnitBack(
    unit, target, kite_via_pathing=True, grid=None
)

Bases: CombatIndividualBehavior

Shoot at the target if possible, else move back.

Example: 

from ares.behaviors.combat import StutterUnitBack

unit: Unit
target: Unit
self.register_behavior(StutterUnitBack(unit, target))

Attributes:

Name Type Description
unit Unit

The unit to shoot.
target Unit

The unit we want to shoot at.
kite_via_pathing bool

Kite back using pathing? Value for grid must be present.
grid Optional[ndarray]

Pass in if using kite_via_pathing.

StutterUnitForward dataclass 

StutterUnitForward(unit, target)

Bases: CombatIndividualBehavior

Shoot at the target if possible, else move back.

Example: 

from ares.behaviors.combat import StutterUnitForward

unit: Unit
target: Unit
self.register_behavior(StutterUnitForward(unit, target))

Attributes:

Name Type Description
unit Unit

The unit to shoot.
target Unit

The unit we want to shoot at.

UseAbility dataclass 

UseAbility(ability, unit, target)

Bases: CombatIndividualBehavior

A-Move a unit to a target.

Example: 

from ares.behaviors.combat import UseAbility
from sc2.ids.ability_id import AbilityId

unit: Unit
target: Union[Unit, Point2]
self.register_behavior(
    UseAbility(
        AbilityId.FUNGALGROWTH_FUNGALGROWTH, unit, target
    )
)

Attributes:

Name Type Description
ability AbilityId

The ability we want to use.
unit Unit

The unit to use the ability.
target Union[Point2, Unit, None]

Target for this ability.

WorkerKiteBack dataclass 

WorkerKiteBack(unit, target)

Bases: CombatIndividualBehavior

Shoot at the target if possible, else move back.

This is similar to stutter unit back, but takes advantage of mineral walking.

Example: 

from ares.behaviors.combat import WorkerKiteBack

unit: Unit
target: Unit
self.register_behavior(
    WorkerKiteBack(
        unit, target
    )
)

Attributes:

Name Type Description
unit Unit

The unit to shoot.
target Unit

The unit we want to shoot at.