DarkTemplar Controls scouting behavior for a Protoss Dark Templar. Combines movement, target prioritization, and stealth-based harassment to pressure the enemy while scouting. More...

#include <DarkTemplar.h>

Public Member Functions
	DarkTemplar (ProtoBotCommander commander, ScoutingManager manager)
void	onStart ()
	Initializes the dark templar scouting state.
void	onFrame ()
	Main update loop executed every frame.
void	onUnitDestroy (BWAPI::Unit unit)
	Handles cleanup when the dark templar is destroyed.
void	setEnemyMain (const BWAPI::TilePosition &tp)
	Sets the enemy main base location and updates behavior state.
void	assign (BWAPI::Unit unit)
	Assigns a unit as the dark templar scout.
void	drawDebug () const
	Draws debug information for the dark templar scout.

Private Types
enum class	State { Idle , WaitEnemyMain , MoveToEnemyMain , ApproachNatural , AttackEnemyMain , Done }

Private Member Functions
void	issueMove (BWAPI::Unit unit, const BWAPI::Position &p, bool force=false)
	Issues a movement command with cooldown control.
BWAPI::Unit	pickTargetFor (BWAPI::Unit dt) const
	Selects the highest priority target inside the enemy base.
BWAPI::Unit	getLockedTarget () const
	Returns the currently locked target, if it still exists.
BWAPI::Position	getNaturalApproachPosition () const
	Returns the preferred approach position near the enemy natural.
BWAPI::Unit	findApproachTarget (BWAPI::Unit dt) const
	Finds a nearby target to attack while approaching the enemy base.

Static Private Member Functions
static bool	isDetectorBuildingType (BWAPI::UnitType type)
	Checks whether a unit type is considered a detector building.
static bool	isDetectorBuilding (BWAPI::Unit unit)
static bool	isWorker (BWAPI::Unit unit)
	Checks whether a unit is a worker.
static bool	isBuilding (BWAPI::Unit unit)
	Checks whether a unit is a building that is not specifically a detector.

Private Attributes
ProtoBotCommander *	commanderRef = nullptr
ScoutingManager *	manager = nullptr
BWAPI::Unit	darkTemplar = nullptr
int	lockedTargetId = -1
std::optional< BWAPI::TilePosition >	enemyMainTile
BWAPI::Position	enemyMainPos = BWAPI::Positions::Invalid
State	state = State::Idle
int	lastMoveIssueFrame = 0

Static Private Attributes
static constexpr int	kMoveCooldownFrames = 8
static constexpr int	kAttackRangePx = 20 * 32
static constexpr int	kArriveDistPx = 160
static constexpr int	kMainPriorityRadiusPx = 14 * 32

Detailed Description

DarkTemplar Controls scouting behavior for a Protoss Dark Templar. Combines movement, target prioritization, and stealth-based harassment to pressure the enemy while scouting.

/// Uses a state-driven system to:

Move toward the enemy natural and main base
Prioritize valuable targets while approaching
Attack key structures and workers inside the enemy base
Maintain target focus through locked target selection

Definition at line 21 of file DarkTemplar.h.

Member Enumeration Documentation

◆ State

enum class DarkTemplar::State

strongprivate

Definition at line 39 of file DarkTemplar.h.

    {
        Idle,
        WaitEnemyMain,
        MoveToEnemyMain,
        ApproachNatural,
        AttackEnemyMain,
        Done
    };

Constructor & Destructor Documentation

◆ DarkTemplar()

DarkTemplar::DarkTemplar	(	ProtoBotCommander *	commander,
		ScoutingManager *	manager )

inlineexplicit

Definition at line 24 of file DarkTemplar.h.

        : commanderRef(commander), manager(manager)
    {
    }

Member Function Documentation

◆ assign()

void DarkTemplar::assign ( BWAPI::Unit unit )

Assigns a unit as the dark templar scout.

Verifies the unit type and sets the initial movement state based on whether the enemy main is already known.

Parameters

unit	Unit to assign as scout

Definition at line 50 of file DarkTemplar.cpp.

{
    if (!unit || !unit->exists())
    {
        return;
    }
 
    if (unit->getType() != BWAPI::UnitTypes::Protoss_Dark_Templar)
    {
        return;
    }
 
    darkTemplar = unit;
 
    if (enemyMainPos.isValid())
    {
        state = State::MoveToEnemyMain;
    }
    else
    {
        state = State::WaitEnemyMain;
    }
}

◆ drawDebug()

void DarkTemplar::drawDebug ( ) const

Draws debug information for the dark templar scout.

Displays:

Current state
Locked target
Enemy main direction
Enemy natural direction

Definition at line 615 of file DarkTemplar.cpp.

{
    if (!darkTemplar || !darkTemplar->exists())
    {
        return;
    }
    const char* stateName = "Unknown";
 
    switch (state)
    {
    case State::Idle:
        stateName = "Idle";
        break;
    case State::WaitEnemyMain:
        stateName = "WaitEnemyMain";
        break;
    case State::MoveToEnemyMain:
        stateName = "MoveToEnemyMain";
        break;
    case State::ApproachNatural:
        stateName = "ApproachNatural";
        break;
    case State::AttackEnemyMain:
        stateName = "AttackEnemyMain";
        break;
    case State::Done:
        stateName = "Done";
        break;
    default:
        stateName = "Unknown";
        break;
    }
   
 
    BWAPI::Position p = darkTemplar->getPosition();
 
    BWAPI::Broodwar->drawCircleMap(p, 22, BWAPI::Colors::Purple, false);
    BWAPI::Broodwar->drawTextMap(p.x - 30, p.y - 46, "\x05DT Scout");
    BWAPI::Broodwar->drawTextMap(p.x - 30, p.y - 34, "\x11State: %s", stateName);
 
    BWAPI::Unit target = getLockedTarget();
    if (target && target->exists())
    {
        BWAPI::Broodwar->drawLineMap(p, target->getPosition(), BWAPI::Colors::Red);
        BWAPI::Broodwar->drawCircleMap(target->getPosition(), 14, BWAPI::Colors::Red, false);
        BWAPI::Broodwar->drawTextMap(
            p.x - 30,
            p.y - 22,
            "\x08Target: %s",
            target->getType().getName().c_str()
        );
    }
    else
    {
        BWAPI::Broodwar->drawTextMap(p.x - 30, p.y - 22, "\x08Target: None");
    }
 
    if (enemyMainPos.isValid())
    {
        BWAPI::Broodwar->drawLineMap(p, enemyMainPos, BWAPI::Colors::Green);
    }
 
    if (manager)
    {
        auto nat = manager->getEnemyNatural();
        if (nat.has_value())
        {
            BWAPI::Position natPos(nat.value());
            BWAPI::Broodwar->drawLineMap(p, natPos, BWAPI::Colors::Orange);
        }
    }
 
   
}

◆ findApproachTarget()

BWAPI::Unit DarkTemplar::findApproachTarget ( BWAPI::Unit dt ) const

private

Finds a nearby target to attack while approaching the enemy base.

Used during movement states to opportunistically attack visible nearby targets without fully switching behavior.

Parameters

dt	Dark templar unit

Returns: Best nearby target, or nullptr if none found

Definition at line 410 of file DarkTemplar.cpp.

{
    if (!dt || !dt->exists())
    {
        return nullptr;
    }
 
    BWAPI::Unit best = nullptr;
    int bestDist = INT_MAX;
 
    for (BWAPI::Unit enemy : BWAPI::Broodwar->enemy()->getUnits())
    {
        if (!enemy || !enemy->exists())
        {
            continue;
        }
 
        if (!enemy->isVisible())
        {
            continue;
        }
 
        const int d = dt->getDistance(enemy);
 
        // only grab things reasonably close during the walk-in
        if (d > 8 * 32)
        {
            continue;
        }
 
        if (!isValidDTTarget(dt, enemy))
        {
            continue;
        }
 
        if (d < bestDist)
        {
            bestDist = d;
            best = enemy;
        }
    }
 
    return best;
}

◆ getLockedTarget()

BWAPI::Unit DarkTemplar::getLockedTarget ( ) const

private

Returns the currently locked target, if it still exists.

Returns: Locked enemy unit, or nullptr if unavailable

Definition at line 352 of file DarkTemplar.cpp.

{
    if (lockedTargetId < 0)
    {
        return nullptr;
    }
 
    for (BWAPI::Unit enemy : BWAPI::Broodwar->enemy()->getUnits())
    {
        if (!enemy || !enemy->exists())
        {
            continue;
        }
 
        if (enemy->getID() == lockedTargetId)
        {
            return enemy;
        }
    }
 
    return nullptr;
}

◆ getNaturalApproachPosition()

BWAPI::Position DarkTemplar::getNaturalApproachPosition ( ) const

private

Returns the preferred approach position near the enemy natural.

Falls back to the enemy main if no natural location is known.

Returns: Approach position for the dark templar

Definition at line 382 of file DarkTemplar.cpp.

{
    if (manager)
    {
        auto nat = manager->getEnemyNatural();
        if (nat.has_value())
        {
            return BWAPI::Position(nat.value());
        }
    }
 
    if (enemyMainPos.isValid())
    {
        return enemyMainPos;
    }
 
    return BWAPI::Positions::Invalid;
}

◆ isBuilding()

bool DarkTemplar::isBuilding ( BWAPI::Unit unit )

staticprivate

Checks whether a unit is a building that is not specifically a detector.

Parameters

unit	Unit to check

Returns: True if the unit is a building

Definition at line 505 of file DarkTemplar.cpp.

{
    return unit && unit->exists() && unit->getType().isBuilding();
}

◆ isDetectorBuilding()

bool DarkTemplar::isDetectorBuilding ( BWAPI::Unit unit )

staticprivate

Definition at line 471 of file DarkTemplar.cpp.

{
    if (!unit || !unit->exists())
    {
        return false;
    }
 
    const BWAPI::UnitType type = unit->getType();
 
    if (isDetectorBuildingType(type))
    {
        return true;
    }
 
    return false;
}

◆ isDetectorBuildingType()

bool DarkTemplar::isDetectorBuildingType ( BWAPI::UnitType type )

staticprivate

Checks whether a unit type is considered a detector building.

Parameters

type	Unit type to check

Returns: True if the type is a detector building

Definition at line 461 of file DarkTemplar.cpp.

{
    return
        type == BWAPI::UnitTypes::Terran_Missile_Turret ||
        type == BWAPI::UnitTypes::Terran_Comsat_Station ||
        type == BWAPI::UnitTypes::Protoss_Photon_Cannon ||
        type == BWAPI::UnitTypes::Protoss_Observatory ||
        type == BWAPI::UnitTypes::Zerg_Spore_Colony;
}

◆ issueMove()

void DarkTemplar::issueMove	(	BWAPI::Unit	unit,
		const BWAPI::Position &	p,
		bool	force = false )

private

Issues a movement command with cooldown control.

Prevents command spam by throttling repeated move orders.

Parameters

unit	Unit receiving the command
p	Target position
force	Force movement regardless of cooldown

Definition at line 326 of file DarkTemplar.cpp.

{
    if (!unit || !unit->exists() || !p.isValid())
    {
        return;
    }
 
    const int now = BWAPI::Broodwar->getFrameCount();
 
    if (!force && (now - lastMoveIssueFrame) < kMoveCooldownFrames)
    {
        return;
    }
 
    if (force || !unit->isMoving() || unit->getDistance(p) > 48)
    {
        unit->move(p);
        lastMoveIssueFrame = now;
    }
}

◆ isWorker()

bool DarkTemplar::isWorker ( BWAPI::Unit unit )

staticprivate

Checks whether a unit is a worker.

Parameters

unit	Unit to check

Returns: True if the unit is a worker

Definition at line 494 of file DarkTemplar.cpp.

{
    return unit && unit->exists() && unit->getType().isWorker();
}

◆ onFrame()

void DarkTemplar::onFrame ( )

Main update loop executed every frame.

Controls state transitions and behavior including:

Waiting for enemy main information
Moving toward the enemy main
Approaching through the enemy natural
Attacking targets inside the enemy base

Definition at line 127 of file DarkTemplar.cpp.

{
    BWAPI::Unit dt = darkTemplar;
 
    if (state == State::Done || !dt || !dt->exists())
    {
        return;
    }
 
    if (!enemyMainPos.isValid() && commanderRef)
    {
        const auto& e = commanderRef->enemy();
        if (e.main.has_value())
        {
            setEnemyMain(*e.main);
        }
    }
 
    switch (state)
    {
        case State::Idle:
        {
            state = enemyMainPos.isValid() ? State::MoveToEnemyMain : State::WaitEnemyMain;
            break;
        }
 
        case State::WaitEnemyMain:
        {
            if (enemyMainPos.isValid())
            {
                state = State::MoveToEnemyMain;
            }
            break;
        }
 
        case State::MoveToEnemyMain:
        {
            if (enemyMainPos.isValid() && dt->getDistance(enemyMainPos) <= kMainPriorityRadiusPx)
            {
                lockedTargetId = -1;
                state = State::AttackEnemyMain;
                break;
            }
 
            if (manager)
            {
                auto nat = manager->getEnemyNatural();
                if (nat.has_value())
                {
                    state = State::ApproachNatural;
                    break;
                }
            }
 
            BWAPI::Unit target = getLockedTarget();
 
            if (!target || !target->exists())
            {
                target = findApproachTarget(dt);
 
                if (target && target->exists())
                {
                    lockedTargetId = target->getID();
                }
                else
                {
                    lockedTargetId = -1;
                }
            }
 
            if (target && target->exists())
            {
                if (dt->getOrderTarget() != target)
                {
                    dt->attack(target);
                }
            }
            else if (dt->getDistance(enemyMainPos) > kArriveDistPx)
            {
                if (dt->getLastCommandFrame() < BWAPI::Broodwar->getFrameCount() - kMoveCooldownFrames)
                {
                    dt->attack(enemyMainPos);
                }
            }
            else
            {
                state = State::ApproachNatural;
            }
 
            break;
        }
 
        case State::ApproachNatural:
        {
            BWAPI::Position approachPos = getNaturalApproachPosition();
 
            if (!approachPos.isValid())
            {
                if (enemyMainPos.isValid())
                {
                    approachPos = enemyMainPos;
                }
                else
                {
                    break;
                }
            }
 
            const int dist = dt->getDistance(approachPos);
 
            const int mainPriorityRadius = 10 * 32;
 
            if (enemyMainPos.isValid() && dt->getDistance(enemyMainPos) <= mainPriorityRadius)
            {
                lockedTargetId = -1;
                state = State::AttackEnemyMain;
                break;
            }
 
            BWAPI::Unit target = getLockedTarget();
 
            if (!target || !target->exists())
            {
                target = findApproachTarget(dt);
 
                if (target && target->exists())
                {
                    lockedTargetId = target->getID();
                }
                else
                {
                    lockedTargetId = -1;
                }
            }
 
            if (target && target->exists())
            {
                if (dt->getOrderTarget() != target)
                {
                    dt->attack(target);
                }
            }
            else if (dt->getLastCommandFrame() < BWAPI::Broodwar->getFrameCount() - kMoveCooldownFrames)
            {
                dt->attack(approachPos);
            }
 
            break;
        }
 
        case State::AttackEnemyMain:
        {
            BWAPI::Unit target = getLockedTarget();
 
            if (!target || !target->exists())
            {
                target = pickTargetFor(dt);
 
                if (target && target->exists())
                {
                    lockedTargetId = target->getID();
                }
                else
                {
                    lockedTargetId = -1;
                }
            }
 
            if (target && target->exists())
            {
                if (dt->getOrderTarget() != target)
                {
                    dt->attack(target);
                }
            }
            else
            {
                issueMove(dt, enemyMainPos);
            }
            break;
        }
 
        case State::Done:
        default:
        {
            break;
        }
    }
}

◆ onStart()

void DarkTemplar::onStart ( )

Initializes the dark templar scouting state.

Resets movement timing and sets the initial state to Idle.

Definition at line 13 of file DarkTemplar.cpp.

{
    state = State::Idle;
    lastMoveIssueFrame = 0;
}

◆ onUnitDestroy()

void DarkTemplar::onUnitDestroy ( BWAPI::Unit unit )

Handles cleanup when the dark templar is destroyed.

Clears the tracked unit, resets locked target state, and marks the behavior as complete.

Parameters

unit	Destroyed unit

Definition at line 82 of file DarkTemplar.cpp.

{
    if (!unit)
    {
        return;
    }
 
    if (darkTemplar == unit)
    {
        darkTemplar = nullptr;
        lockedTargetId = -1;
        state = State::Done;
    }
}

◆ pickTargetFor()

BWAPI::Unit DarkTemplar::pickTargetFor ( BWAPI::Unit dt ) const

private

Selects the highest priority target inside the enemy base.

Priority order:

Detector buildings
Workers
Other buildings

Parameters

dt	Dark templar unit

Returns: Best target to attack, or nullptr if none found

Definition at line 521 of file DarkTemplar.cpp.

{
    if (!dt || !dt->exists())
    {
        return nullptr;
    }
 
    BWAPI::Unit bestDetector = nullptr;
    int bestDetectorDist = INT_MAX;
 
    BWAPI::Unit bestWorker = nullptr;
    int bestWorkerDist = INT_MAX;
 
    BWAPI::Unit bestBuilding = nullptr;
    int bestBuildingDist = INT_MAX;
 
    for (BWAPI::Unit enemy : BWAPI::Broodwar->enemy()->getUnits())
    {
 
        if (!enemy || !enemy->exists())
        {
            continue;
        }
 
        if (!isValidDTTarget(dt, enemy))
        {
            continue;
        }
 
        const int d = dt->getDistance(enemy);
 
        if (d > kAttackRangePx)
        {
            continue;
        }
 
        if (isDetectorBuilding(enemy))
        {
            if (d < bestDetectorDist)
            {
                bestDetectorDist = d;
                bestDetector = enemy;
            }
            continue;
        }
 
        if (isWorker(enemy))
        {
            if (d < bestWorkerDist)
            {
                bestWorkerDist = d;
                bestWorker = enemy;
            }
            continue;
        }
 
        if (isBuilding(enemy))
        {
            if (d < bestBuildingDist)
            {
                bestBuildingDist = d;
                bestBuilding = enemy;
            }
        }
    }
 
    if (bestDetector)
    {
        return bestDetector;
    }
 
    if (bestWorker)
    {
        return bestWorker;
    }
 
    if (bestBuilding)
    {
        return bestBuilding;
    }
 
    return nullptr;
}

◆ setEnemyMain()

void DarkTemplar::setEnemyMain ( const BWAPI::TilePosition & tp )

Sets the enemy main base location and updates behavior state.

If the dark templar is already assigned, transitions into movement toward the enemy main. Otherwise waits for assignment.

Parameters

tp	Enemy main tile position

Definition at line 27 of file DarkTemplar.cpp.

{
    enemyMainTile = tp;
    enemyMainPos = BWAPI::Position(tp);
 
    if (darkTemplar && darkTemplar->exists())
    {
        state = State::MoveToEnemyMain;
    }
    else
    {
        state = State::WaitEnemyMain;
    }
}

Member Data Documentation

◆ commanderRef

ProtoBotCommander* DarkTemplar::commanderRef = nullptr

private

Definition at line 49 of file DarkTemplar.h.

◆ darkTemplar

BWAPI::Unit DarkTemplar::darkTemplar = nullptr

private

Definition at line 52 of file DarkTemplar.h.

◆ enemyMainPos

BWAPI::Position DarkTemplar::enemyMainPos = BWAPI::Positions::Invalid

private

Definition at line 56 of file DarkTemplar.h.

◆ enemyMainTile

std::optional<BWAPI::TilePosition> DarkTemplar::enemyMainTile

private

Definition at line 55 of file DarkTemplar.h.

◆ kArriveDistPx

int DarkTemplar::kArriveDistPx = 160

staticconstexprprivate

Definition at line 63 of file DarkTemplar.h.

◆ kAttackRangePx

int DarkTemplar::kAttackRangePx = 20 * 32

staticconstexprprivate

Definition at line 62 of file DarkTemplar.h.

◆ kMainPriorityRadiusPx

int DarkTemplar::kMainPriorityRadiusPx = 14 * 32

staticconstexprprivate

Definition at line 64 of file DarkTemplar.h.

◆ kMoveCooldownFrames

int DarkTemplar::kMoveCooldownFrames = 8

staticconstexprprivate

Definition at line 61 of file DarkTemplar.h.

◆ lastMoveIssueFrame

int DarkTemplar::lastMoveIssueFrame = 0

private

Definition at line 60 of file DarkTemplar.h.

◆ lockedTargetId

int DarkTemplar::lockedTargetId = -1

private

Definition at line 53 of file DarkTemplar.h.

◆ manager

ScoutingManager* DarkTemplar::manager = nullptr

private

Definition at line 50 of file DarkTemplar.h.

◆ state

State DarkTemplar::state = State::Idle

private

Definition at line 58 of file DarkTemplar.h.

The documentation for this class was generated from the following files:

src/protobot/DarkTemplar.h
src/protobot/DarkTemplar.cpp

Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

◆ State

Constructor & Destructor Documentation

◆ DarkTemplar()

Member Function Documentation

◆ assign()

◆ drawDebug()

◆ findApproachTarget()

◆ getLockedTarget()

◆ getNaturalApproachPosition()

◆ isBuilding()

◆ isDetectorBuilding()

◆ isDetectorBuildingType()

◆ issueMove()

◆ isWorker()

◆ onFrame()

◆ onStart()

◆ onUnitDestroy()

◆ pickTargetFor()

◆ setEnemyMain()

Member Data Documentation

◆ commanderRef

◆ darkTemplar

◆ enemyMainPos

◆ enemyMainTile

◆ kArriveDistPx

◆ kAttackRangePx

◆ kMainPriorityRadiusPx

◆ kMoveCooldownFrames

◆ lastMoveIssueFrame

◆ lockedTargetId

◆ manager

◆ state