acquire_target

Baseline for target picking behaviors

Vars
ignore_list_key	Optional blackboard key holding a lazylist of atoms to skip while filtering candidates.
minimum_distance	How close the reachability path must get to the target (0 = onto/adjacent). Passed to can_reach_target when must_be_reachable is set.
must_be_reachable	If TRUE, only candidates the controller can path to are eligible; unreachable ones are reported via note_unreachable_target.
reach_distance	Pathfinding distance limit used when must_be_reachable is set.
revalidation_mode	How to behave when a target is already set. See TARGET_* defines in ai.dm.
search_priority_strategy	Optional selection strategy snapshot from the perform() that kicked off the current async search.
search_range	Range snapshot from the perform() that kicked off the current async search.
search_strategy	Strategy/range snapshot from the perform() that kicked off the current async search.
target_key	Blackboard key to write the found target into.
target_loss_distance	Extended range for retaining an existing target when candidates run dry. 0 = disabled.
target_priority_strategy	Optional /datum/target_priority_strategy typepath or blackboard key string. Null means unranked selection.
target_source	Typepath of the /datum/target_source type used to gather candidates. turned into the singleton instance when used
targeting_strategy	Either a /datum/targeting_strategy typepath (resolved directly) or a blackboard key string
vision_range	How far to scan for candidates (passed to the target source). Can be a key too.
Procs
can_search	Returns TRUE to abort the search before it starts (e.g. a detection field is already active).
clear_stale_target	Clears the target key when revalidating and the search turned up nothing, so a stale target doesn't linger.
filter_candidates	Filters the candidate list to valid targets and excludes candidates ranked below a retainable current target.
find_and_set_target	Actual behavior for collecting and filtering targets
get_target_priority_strategy	Resolves the optional target priority strategy for this behavior.
get_targeting_strategy	Resolves the targeting strategy for this behavior
get_vision_range	Resolves a numeric vision range without mutating the behavior's configured value.
include_current_target	Includes a retainable current target in priority-aware reselection even if the target source omitted it.
on_no_candidates	Fallback for no targets found.
on_no_valid_candidates	Called when filter_candidates produces nothing. Override to trigger side effects (e.g. spawning a detection field).
on_target_found	Called after a target is selected and written to the blackboard. Override for post-selection side effects.
perform_async	perform_async(): selects candidates in policy order, checking reachability until one succeeds.
pick_final_target	Picks the final target and keeps the current target on policy-defined ties.
should_keep_target	Returns TRUE if the current target is still good and we should skip the search.

Var Details

var
ignore_list_key

Optional blackboard key holding a lazylist of atoms to skip while filtering candidates.

var
minimum_distance

How close the reachability path must get to the target (0 = onto/adjacent). Passed to can_reach_target when must_be_reachable is set.

var
must_be_reachable

If TRUE, only candidates the controller can path to are eligible; unreachable ones are reported via note_unreachable_target.

var
reach_distance

Pathfinding distance limit used when must_be_reachable is set.

var
revalidation_mode

How to behave when a target is already set. See TARGET_* defines in ai.dm.

var
search_priority_strategy
– /datum/target_priority_strategy

Optional selection strategy snapshot from the perform() that kicked off the current async search.

var
search_range

Range snapshot from the perform() that kicked off the current async search.

var
search_strategy
– /datum/targeting_strategy

Strategy/range snapshot from the perform() that kicked off the current async search.

var
target_key

Blackboard key to write the found target into.

var
target_loss_distance

Extended range for retaining an existing target when candidates run dry. 0 = disabled.

var
target_priority_strategy

Optional /datum/target_priority_strategy typepath or blackboard key string. Null means unranked selection.

var
target_source

Typepath of the /datum/target_source type used to gather candidates. turned into the singleton instance when used

var
targeting_strategy

Either a /datum/targeting_strategy typepath (resolved directly) or a blackboard key string

var
vision_range

How far to scan for candidates (passed to the target source). Can be a key too.

Proc Details

proc
can_search
(/datum/ai_controller/controller)

Returns TRUE to abort the search before it starts (e.g. a detection field is already active).

proc
clear_stale_target
(/datum/ai_controller/controller, /atom/current_target)

Clears the target key when revalidating and the search turned up nothing, so a stale target doesn't linger.

proc
filter_candidates
(/datum/ai_controller/controller, /list/candidates, /datum/targeting_strategy/strategy, /datum/target_priority_strategy/priority_strategy, /atom/current_target, range)

Filters the candidate list to valid targets and excludes candidates ranked below a retainable current target.

proc
find_and_set_target
(/datum/ai_controller/controller, /datum/targeting_strategy/targeting_strategy, /datum/target_priority_strategy/priority_strategy, range)

Actual behavior for collecting and filtering targets

proc
get_target_priority_strategy
(/datum/ai_controller/controller)

Resolves the optional target priority strategy for this behavior.

proc
get_targeting_strategy
(/datum/ai_controller/controller)

Resolves the targeting strategy for this behavior

proc
get_vision_range
(/datum/ai_controller/controller)

Resolves a numeric vision range without mutating the behavior's configured value.

proc
include_current_target
(/datum/ai_controller/controller, /list/candidates, /datum/targeting_strategy/strategy, /datum/target_priority_strategy/priority_strategy, /atom/current_target, range)

Includes a retainable current target in priority-aware reselection even if the target source omitted it.

proc
on_no_candidates
(/datum/ai_controller/controller, /atom/current_target, /datum/targeting_strategy/strategy, range)

Fallback for no targets found.

proc
on_no_valid_candidates
(/datum/ai_controller/controller, /atom/current_target)

Called when filter_candidates produces nothing. Override to trigger side effects (e.g. spawning a detection field).

proc
on_target_found
(/datum/ai_controller/controller, /atom/target, /datum/targeting_strategy/strategy)

Called after a target is selected and written to the blackboard. Override for post-selection side effects.

↑
perform_async
(/datum/ai_controller/controller)

perform_async(): selects candidates in policy order, checking reachability until one succeeds.

proc
pick_final_target
(/datum/ai_controller/controller, /list/filtered_targets, /datum/target_priority_strategy/priority_strategy, /atom/current_target)

Picks the final target and keeps the current target on policy-defined ties.

proc
should_keep_target
(/datum/ai_controller/controller, /datum/targeting_strategy/strategy, /datum/target_priority_strategy/priority_strategy, /atom/current_target, resolved_vision_range)

Returns TRUE if the current target is still good and we should skip the search.

acquire_target /datum/bt_node/ai_behavior/acquire_target

Vars

Procs

Var Details

var ignore_list_key

var minimum_distance

var must_be_reachable

var reach_distance

var revalidation_mode

var search_priority_strategy – /datum/target_priority_strategy

var search_range

var search_strategy – /datum/targeting_strategy

var target_key

var target_loss_distance

var target_priority_strategy

var target_source

var targeting_strategy

var vision_range

Proc Details

proc can_search(/datum/ai_controller/controller)

proc clear_stale_target(/datum/ai_controller/controller, /atom/current_target)

proc filter_candidates(/datum/ai_controller/controller, /list/candidates, /datum/targeting_strategy/strategy, /datum/target_priority_strategy/priority_strategy, /atom/current_target, range)

proc find_and_set_target(/datum/ai_controller/controller, /datum/targeting_strategy/targeting_strategy, /datum/target_priority_strategy/priority_strategy, range)

proc get_target_priority_strategy(/datum/ai_controller/controller)

proc get_targeting_strategy(/datum/ai_controller/controller)

proc get_vision_range(/datum/ai_controller/controller)

proc include_current_target(/datum/ai_controller/controller, /list/candidates, /datum/targeting_strategy/strategy, /datum/target_priority_strategy/priority_strategy, /atom/current_target, range)

proc on_no_candidates(/datum/ai_controller/controller, /atom/current_target, /datum/targeting_strategy/strategy, range)

proc on_no_valid_candidates(/datum/ai_controller/controller, /atom/current_target)

proc on_target_found(/datum/ai_controller/controller, /atom/target, /datum/targeting_strategy/strategy)

↑perform_async(/datum/ai_controller/controller)

proc pick_final_target(/datum/ai_controller/controller, /list/filtered_targets, /datum/target_priority_strategy/priority_strategy, /atom/current_target)

proc should_keep_target(/datum/ai_controller/controller, /datum/targeting_strategy/strategy, /datum/target_priority_strategy/priority_strategy, /atom/current_target, resolved_vision_range)