ai_controller

Vars
able_to_plan	are we even able to plan?
able_to_run	TRUE if we're able to run, FALSE if we aren't Should not be set manually, override get_able_to_run() instead Make sure you hook update_able_to_run() in setup_able_to_run() to whatever parameters changing that you added Otherwise we will not pay attention to them changing
ai_movement	Reference to the movement datum we use. Is a type on initialize but becomes a ref afterwards.
ai_status	Current status of AI (OFF/ON)
ai_traits	Bitfield of traits for this AI to handle extra behavior
behavior_args	Stored arguments for behaviors given during their initial creation
behavior_cooldowns	Current actions and their respective last time ran as an assoc list.
blackboard	This is a list of variables the AI uses and can be mutated by actions.
can_idle	Can this AI idle?
consecutive_pathing_attempts	Tracks recent pathing attempts, if we fail too many in a row we fail our current plans.
continue_processing_when_client	Can the AI remain in control if there is a client?
current_behaviors	Current actions being performed by the AI.
current_movement_target	Current movement target of the AI, generally set by decision making.
idle_behavior	The idle behavior this AI performs when it has no actions.
interesting_dist	What distance should we be checking for interesting things when considering idling/deidling? Defaults to AI_DEFAULT_INTERESTING_DIST
max_target_distance	distance to give up on target
movement_delay	Delay between movements. This is on the controller so we can keep the movement datum singleton
movement_target_source	Identifier for what last touched our movement target, so it can be cleared conditionally
on_failed_planning_timeout	are we currently on failed planning timeout?
our_cells	our current cell grid
paused_until	AI paused time
pawn	The atom this controller is controlling
planned_behaviors	Current actions planned to be performed by the AI in the upcoming plan
planning_subtrees	All subtrees this AI has available, will run them in order, so make sure they're in the order you want them to run. On initialization of this type, it will start as a typepath(s) and get converted to references of ai_subtrees found in SSai_controllers when init_subtrees() is called
Procs
PossessPawn	Proc to move from one pawn to another, this will destroy the target's existing controller.
SelectBehaviors	This is where you decide what actions are taken by the AI.
TryPossessPawn	Abstract proc for initializing the pawn to the new controller
UnpossessPawn	Proc for deinitializing the pawn to the old controller
add_blackboard_key	Adds the passed "thing" to the associated key
add_blackboard_key_assoc	Adds the value to the inner list at key with the inner key set to "thing" Throws an error if the key is not a list already, intended only for use with lists
add_blackboard_key_assoc_lazylist	Similar to [proc/add_blackboard_key_assoc], assuming key is intended to be a lazylist (so it will create a list) More dangerous / easier to override values, only use when you want to use a lazylist
add_blackboard_key_lazylist	Adds the passed "thing" to the associated key, assuming key is intended to be a lazylist (so it will create a list) More dangerous / easier to override values, only use when you want to use a lazylist
ai_can_interact	Can this pawn interact with objects?
ai_interact	Interact with objects
blackboard_key_exists	Returns true if we have a blackboard key with the provided key and it is not qdeleting
change_ai_movement_type	Overrides the current ai_movement of this controller with a new one
clear_blackboard_key	Clears the passed key, resetting it to null
get_able_to_run	Returns TRUE if the ai controller can actually run at the moment, FALSE otherwise
get_access	Use this proc to define how your controller defines what access the pawn has for the sake of pathfinding. Return the access list you want to use
get_expected_ai_status	Gets the AI status we expect the AI controller to be on at this current moment. Returns AI_STATUS_OFF if it's inhabited by a Client and shouldn't be, if it's dead and cannot act while dead, or is on a z level without clients. Returns AI_STATUS_ON otherwise.
get_minimum_distance	Returns the minimum required distance to preform one of our current behaviors. Honestly this should just be cached or something but fuck you
init_subtrees	Loops over the subtrees in planning_subtrees and looks at the ai_controllers to grab a reference, ENSURE planning_subtrees ARE TYPEPATHS AND NOT INSTANCES/REFERENCES BEFORE EXECUTING THIS
insert_blackboard_key	Similar to [proc/add_blackboard_key], but performs an insertion rather than an add Throws an error if the key is not a list already, intended only for use with lists
insert_blackboard_key_lazylist	Similar to [proc/insert_blackboard_key_lazylist], but performs an insertion / or rather than an add
on_changed_z_level	Called when the AI controller pawn changes z levels, we check if there's any clients on the new one and wake up the AI if there is.
on_stat_changed	Turn the controller on or off based on if you're alive, we only register to this if the flag is present so don't need to check again
override_blackboard_key	Helper to force a key to be a certain thing no matter what's already there
post_blackboard_key_set	Called after we set a blackboard key, forwards signal information.
process	Runs any actions that are currently running
queue_behavior	Call this to add a behavior to the stack.
remove_from_blackboard_lazylist_key	removes a tracked object from a lazylist
remove_thing_from_blackboard_key	Remove the passed thing from the associated blackboard key
replace_planning_subtrees	Completely replaces the planning_subtrees with a new set based on argument provided, list provided must contain specifically typepaths
reset_ai_status	Sets the AI on or off based on current conditions, call to reset after you've manually disabled it somewhere
set_ai_status	This proc handles changing ai status, and starts/stops processing if required.
set_blackboard_key	Sets the key to the passed "thing".
set_blackboard_key_assoc	Sets the key at index thing to the passed value
set_blackboard_key_assoc_lazylist	Similar to [proc/set_blackboard_key_assoc] but operates under the assumption the key is a lazylist (so it will create a list) More dangerous / easier to override values, only use when you want to use a lazylist
set_movement_target	Sets the current movement target, with an optional param to override the movement behavior
sig_remove_from_blackboard	Signal proc to go through every key and remove the datum from all keys it finds

Var Details

var
able_to_plan

are we even able to plan?

var
able_to_run

TRUE if we're able to run, FALSE if we aren't Should not be set manually, override get_able_to_run() instead Make sure you hook update_able_to_run() in setup_able_to_run() to whatever parameters changing that you added Otherwise we will not pay attention to them changing

var
ai_movement
– /datum/ai_movement

Reference to the movement datum we use. Is a type on initialize but becomes a ref afterwards.

var
ai_status

Current status of AI (OFF/ON)

var
ai_traits

Bitfield of traits for this AI to handle extra behavior

var
behavior_args
– /list

Stored arguments for behaviors given during their initial creation

var
behavior_cooldowns
– /list

Current actions and their respective last time ran as an assoc list.

var
blackboard
– /list

This is a list of variables the AI uses and can be mutated by actions.

When an action is performed you pass this list and any relevant keys for the variables it can mutate.

DO NOT set values in the blackboard directly, and especially not if you're adding a datum reference to this! Use the setters, this is important for reference handing.

var
can_idle

Can this AI idle?

var
consecutive_pathing_attempts

Tracks recent pathing attempts, if we fail too many in a row we fail our current plans.

var
continue_processing_when_client

Can the AI remain in control if there is a client?

var
current_behaviors
– /list

Current actions being performed by the AI.

var
current_movement_target
– /atom

Current movement target of the AI, generally set by decision making.

var
idle_behavior
– /datum/idle_behavior

The idle behavior this AI performs when it has no actions.

var
interesting_dist

What distance should we be checking for interesting things when considering idling/deidling? Defaults to AI_DEFAULT_INTERESTING_DIST

var
max_target_distance

distance to give up on target

var
movement_delay

Delay between movements. This is on the controller so we can keep the movement datum singleton

var
movement_target_source

Identifier for what last touched our movement target, so it can be cleared conditionally

var
on_failed_planning_timeout

are we currently on failed planning timeout?

var
our_cells
– /datum/cell_tracker

our current cell grid

var
paused_until

AI paused time

var
pawn
– /atom

The atom this controller is controlling

var
planned_behaviors
– /list

Current actions planned to be performed by the AI in the upcoming plan

var
planning_subtrees
– /list

All subtrees this AI has available, will run them in order, so make sure they're in the order you want them to run. On initialization of this type, it will start as a typepath(s) and get converted to references of ai_subtrees found in SSai_controllers when init_subtrees() is called

Proc Details

proc
PossessPawn
(/atom/new_pawn)

Proc to move from one pawn to another, this will destroy the target's existing controller.

proc
SelectBehaviors
(seconds_per_tick)

This is where you decide what actions are taken by the AI.

proc
TryPossessPawn
(/atom/new_pawn)

Abstract proc for initializing the pawn to the new controller

proc
UnpossessPawn
(destroy)

Proc for deinitializing the pawn to the old controller

proc
add_blackboard_key
(key, thing)

Adds the passed "thing" to the associated key

Works with lists or numbers, but not lazylists.

key - A blackboard key
thing - a value to set the blackboard key to.

proc
add_blackboard_key_assoc
(key, thing, value)

Adds the value to the inner list at key with the inner key set to "thing" Throws an error if the key is not a list already, intended only for use with lists

key - A blackboard key, with its value set to a list
thing - a value which becomes the inner list value's key
value - what to set the inner list's value to

proc
add_blackboard_key_assoc_lazylist
(key, thing, value)

Similar to [proc/add_blackboard_key_assoc], assuming key is intended to be a lazylist (so it will create a list) More dangerous / easier to override values, only use when you want to use a lazylist

key - A blackboard key, with its value set to a list
thing - a value which becomes the inner list value's key
value - what to set the inner list's value to

proc
add_blackboard_key_lazylist
(key, thing)

Adds the passed "thing" to the associated key, assuming key is intended to be a lazylist (so it will create a list) More dangerous / easier to override values, only use when you want to use a lazylist

key - A blackboard key
thing - a value to set the blackboard key to.

proc
ai_can_interact
()

Can this pawn interact with objects?

proc
ai_interact
(target, combat_mode, /list/modifiers)

Interact with objects

proc
blackboard_key_exists
(key)

Returns true if we have a blackboard key with the provided key and it is not qdeleting

proc
change_ai_movement_type
(/datum/ai_movement/new_movement)

Overrides the current ai_movement of this controller with a new one

proc
clear_blackboard_key
(key)

Clears the passed key, resetting it to null

Not intended for use with list keys - use [proc/remove_thing_from_blackboard_key] if you are removing a value from a list at a key

key - A blackboard key

proc
get_able_to_run
()

Returns TRUE if the ai controller can actually run at the moment, FALSE otherwise

proc
get_access
()

Use this proc to define how your controller defines what access the pawn has for the sake of pathfinding. Return the access list you want to use

proc
get_expected_ai_status
()

Gets the AI status we expect the AI controller to be on at this current moment. Returns AI_STATUS_OFF if it's inhabited by a Client and shouldn't be, if it's dead and cannot act while dead, or is on a z level without clients. Returns AI_STATUS_ON otherwise.

proc
get_minimum_distance
()

Returns the minimum required distance to preform one of our current behaviors. Honestly this should just be cached or something but fuck you

proc
init_subtrees
()

Loops over the subtrees in planning_subtrees and looks at the ai_controllers to grab a reference, ENSURE planning_subtrees ARE TYPEPATHS AND NOT INSTANCES/REFERENCES BEFORE EXECUTING THIS

proc
insert_blackboard_key
(key, thing)

Similar to [proc/add_blackboard_key], but performs an insertion rather than an add Throws an error if the key is not a list already, intended only for use with lists

key - A blackboard key, with its value set to a list
thing - a value to set the blackboard key to.

proc
insert_blackboard_key_lazylist
(key, thing)

Similar to [proc/insert_blackboard_key_lazylist], but performs an insertion / or rather than an add

key - A blackboard key
thing - a value to set the blackboard key to.

proc
on_changed_z_level
(/atom/source, /turf/old_turf, /turf/new_turf, same_z_layer, notify_contents)

Called when the AI controller pawn changes z levels, we check if there's any clients on the new one and wake up the AI if there is.

proc
on_stat_changed
(/mob/living/source, new_stat)

Turn the controller on or off based on if you're alive, we only register to this if the flag is present so don't need to check again

proc
override_blackboard_key
(key, thing)

Helper to force a key to be a certain thing no matter what's already there

Useful for if you're overriding a list with a new list entirely, as otherwise it would throw a runtime error from trying to override a list

Not necessary to use if you aren't dealing with lists, as set_blackboard_key will clear the existing value in that case already, but may be useful for clarity.

key - A blackboard key
thing - a value to set the blackboard key to.

proc
post_blackboard_key_set
(key)

Called after we set a blackboard key, forwards signal information.

↑
process
(seconds_per_tick)

Runs any actions that are currently running

proc
queue_behavior
(behavior_type, ...)

Call this to add a behavior to the stack.

proc
remove_from_blackboard_lazylist_key
(key, thing)

removes a tracked object from a lazylist

proc
remove_thing_from_blackboard_key
(key, thing)

Remove the passed thing from the associated blackboard key

Intended for use with lists, if you're just clearing a reference from a key use [proc/clear_blackboard_key]

key - A blackboard key
thing - a value to set the blackboard key to.

proc
replace_planning_subtrees
(/list/typepaths_of_new_subtrees)

Completely replaces the planning_subtrees with a new set based on argument provided, list provided must contain specifically typepaths

proc
reset_ai_status
()

Sets the AI on or off based on current conditions, call to reset after you've manually disabled it somewhere

proc
set_ai_status
(new_ai_status, additional_flags)

This proc handles changing ai status, and starts/stops processing if required.

proc
set_blackboard_key
(key, thing)

Sets the key to the passed "thing".

key - A blackboard key
thing - a value to set the blackboard key to.

proc
set_blackboard_key_assoc
(key, thing, value)

Sets the key at index thing to the passed value

Assumes the key value is already a list, if not throws an error.

key - A blackboard key, with its value set to a list
thing - a value which becomes the inner list value's key
value - what to set the inner list's value to

proc
set_blackboard_key_assoc_lazylist
(key, thing, value)

Similar to [proc/set_blackboard_key_assoc] but operates under the assumption the key is a lazylist (so it will create a list) More dangerous / easier to override values, only use when you want to use a lazylist

key - A blackboard key, with its value set to a list
thing - a value which becomes the inner list value's key
value - what to set the inner list's value to

proc
set_movement_target
(source, /atom/target, /datum/ai_movement/new_movement)

Sets the current movement target, with an optional param to override the movement behavior

proc
sig_remove_from_blackboard
(/datum/source)

Signal proc to go through every key and remove the datum from all keys it finds

ai_controller /datum/ai_controller

Vars

Procs

Var Details

var able_to_plan

var able_to_run

var ai_movement – /datum/ai_movement

var ai_status

var ai_traits

var behavior_args – /list

var behavior_cooldowns – /list

var blackboard – /list

var can_idle

var consecutive_pathing_attempts

var continue_processing_when_client

var current_behaviors – /list

var current_movement_target – /atom

var idle_behavior – /datum/idle_behavior

var interesting_dist

var max_target_distance

var movement_delay

var movement_target_source

var on_failed_planning_timeout

var our_cells – /datum/cell_tracker

var paused_until

var pawn – /atom

var planned_behaviors – /list

var planning_subtrees – /list

Proc Details

proc PossessPawn(/atom/new_pawn)

proc SelectBehaviors(seconds_per_tick)

proc TryPossessPawn(/atom/new_pawn)

proc UnpossessPawn(destroy)

proc add_blackboard_key(key, thing)

proc add_blackboard_key_assoc(key, thing, value)

proc add_blackboard_key_assoc_lazylist(key, thing, value)

proc add_blackboard_key_lazylist(key, thing)

proc ai_can_interact()

proc ai_interact(target, combat_mode, /list/modifiers)

proc blackboard_key_exists(key)

proc change_ai_movement_type(/datum/ai_movement/new_movement)

proc clear_blackboard_key(key)

proc get_able_to_run()

proc get_access()

proc get_expected_ai_status()

proc get_minimum_distance()

proc init_subtrees()

proc insert_blackboard_key(key, thing)

proc insert_blackboard_key_lazylist(key, thing)

proc on_changed_z_level(/atom/source, /turf/old_turf, /turf/new_turf, same_z_layer, notify_contents)

proc on_stat_changed(/mob/living/source, new_stat)

proc override_blackboard_key(key, thing)

proc post_blackboard_key_set(key)

↑process(seconds_per_tick)

proc queue_behavior(behavior_type, ...)

proc remove_from_blackboard_lazylist_key(key, thing)

proc remove_thing_from_blackboard_key(key, thing)

proc replace_planning_subtrees(/list/typepaths_of_new_subtrees)

proc reset_ai_status()

proc set_ai_status(new_ai_status, additional_flags)

proc set_blackboard_key(key, thing)

proc set_blackboard_key_assoc(key, thing, value)

proc set_blackboard_key_assoc_lazylist(key, thing, value)

proc set_movement_target(source, /atom/target, /datum/ai_movement/new_movement)

proc sig_remove_from_blackboard(/datum/source)