code/datums/ai/making_your_ai.md

This is a step by step guide for making an AI Controller for your atom. It teaches the basics of each part of an AI Controller so the target for this guide is someone who doesn't know anything about Controllers and wants to hop in.

At the moment the quality of ai datums has some dubious code lying all around, and I wanted to show the best examples. So while I walk through this with the basic cow ai as an example, I do swap to other datums involving items, generic instrument planning, and some other stuff to help explain singular concepts. I make it clear later in the guide when I'm getting back to following along with filling out the cow ai, so watch out for that.

We're simply starting out with our definition of what we're modifying. Any atom can have an ai controller.

/mob/living/basic/cow
	name = "cow"
	desc = "Known for their milk, just don't tip them over."

Next, we'll want to define the AI Controller. This is the "brain" of the AI. It starts as a type, but is turned into an instance once the object is instanced.

For clarity, i've included all the variables we're going to set up but haven't yet as nulls. In reality, some of these are always expected to be something and you should take a look at the base controller for which.

/mob/living/basic/cow
    name = "cow"
    desc = "Known for their milk, just don't tip them over."

    ai_controller = /datum/ai_controller/basic_controller/cow

/datum/ai_controller/basic_controller/cow
	blackboard = list()

	ai_traits = null
	ai_movement = null
	idle_behavior = null
	planning_subtrees = list()

AI Movement is a datum that decides how the AI you're making pathfinds. This has to at least be set to dumb movement, it cannot be null. We're making a basic mob, so we're just going to go inbetween complex and simple pathfinding with the basic_avoidance type.

/datum/ai_controller/basic_controller/cow
	blackboard = list()

	ai_traits = null
	ai_movement = /datum/ai_movement/basic_avoidance
	idle_behavior = null
	planning_subtrees = list()

Idle Behavior is very similar, datum that decides what the AI should do when it decides it doesn't need to do anything (No planned behaviors, we'll walk through that later). Cows having some idle movement sounds nice, so we're going to pick that.

/datum/ai_controller/basic_controller/cow
	blackboard = list()

	ai_traits = null
	ai_movement = /datum/ai_movement/basic_avoidance
	idle_behavior = /datum/idle_behavior/idle_random_walk
	planning_subtrees = list()

AI traits are flags you can set to modify generic idle and movement behavior. In this case, we want farm animals to be able to be coralled, so we're going to add the STOP_MOVING_WHEN_PULLED flag.

/datum/ai_controller/basic_controller/cow
	blackboard = list()

	ai_traits = STOP_MOVING_WHEN_PULLED
	ai_movement = /datum/ai_movement/basic_avoidance
	idle_behavior = /datum/idle_behavior/idle_random_walk
	planning_subtrees = list()

The blackboard is the variables of the ai controller. They are set up by the subtrees that use them, or are defaults set by the ai controller that the subtrees read. As we don't have our subtrees set up, we don't know what the blackboard should have! We're going to come back to this.

So we have all the fundamentals of the cow set in stone, but we do not have the actual behaviors that make cows... act like cows! We introduce these through subtrees. They're singletons that ai controllers hold references to that plan out each step of how an AI should act, loading up behaviors.

Let's take a look at a simple subtree:

/datum/ai_planning_subtree/item_throw_attack

/datum/ai_planning_subtree/item_throw_attack/SelectBehaviors(datum/ai_controller/controller, delta_time)
	var/obj/item/item_pawn = controller.pawn

	if(!controller.blackboard[BB_ITEM_TARGET] || !DT_PROB(ITEM_AGGRO_ATTACK_CHANCE, delta_time))
		return //no target, or didn't aggro

	controller.queue_behavior(controller.blackboard[BB_ITEM_MOVE_AND_ATTACK_TYPE], BB_ITEM_TARGET, BB_ITEM_THROW_ATTEMPT_COUNT)
	return SUBTREE_RETURN_FINISH_PLANNING

This subtree takes a blackboard named BB_ITEM_TARGET, the target of the item set by other subtrees, and if that exists alongside a probability to aggro, the subtree queues the behavior to attack that mob.

So, neat. When you have a target, queue an attack. This item attack subtree is pretty basic, but a more complicated one may queue different attacks depending on the target. How does this fit into the subtrees?

Let's look where it's used, specifically in the subtrees variable:

/datum/ai_controller/haunted
    planning_subtrees = list(
        ///this applies aggro for picking up the item
        /datum/ai_planning_subtree/item_ghost_resist,
        ///this picks targets from the aggro list
        /datum/ai_planning_subtree/item_target_from_aggro_list,
        ///this uses the target to attack.
        /datum/ai_planning_subtree/item_throw_attack,
    )

As you can see the subtrees go top to bottom on their processing. SUBTREE_RETURN_FINISH_PLANNING will prematurely end the subtrees, so we can be sure the ai will focus on the behaviors planned so far in a "priority list" kind of way.

Let's visualize this in a case where the subtrees should stop prematurely!

/datum/ai_controller/haunted
    planning_subtrees = list(
        ///someone is currently holding the item,
        ///preventing it from attacking!
        ///resist and end planning.
        /datum/ai_planning_subtree/item_ghost_resist,
        ///this does not fire this time around
        /datum/ai_planning_subtree/item_target_from_aggro_list,
        ///this does not fire this time around
        /datum/ai_planning_subtree/item_throw_attack,
    )

Subtrees also have procs for when the mob first starts using them and when they stop. You can use this to make subtrees "react" to events via signals, and this is where we set defaults for blackboards if necessary (we want lists to be empty, not null!)

Example:

/datum/ai_planning_subtree/item_ghost_resist/SetupSubtree(datum/ai_controller/controller)
	RegisterSignal(controller.pawn, COMSIG_ITEM_EQUIPPED, PROC_REF(on_equip))
	controller.blackboard[BB_LIKES_EQUIPPER] = FALSE
	controller.blackboard[BB_ITEM_AGGRO_LIST] = list()

/datum/ai_planning_subtree/item_ghost_resist/ForgetSubtree(datum/ai_controller/controller)
	UnregisterSignal(controller.pawn, list(COMSIG_ITEM_EQUIPPED, COMSIG_ITEM_DROPPED))

Do not set blackboards on the subtree! Subtrees are there to sort and optimize behavior selection, putting logic for setting blackboards is essentially skipping a behavior. I'm putting this here because unfortunately a lot of our current ai datum code has this exact mistake, and I'm hoping we can move on from it!

BAD:

	if(prob(50))
		var/list/possible_targets = list()
		for(var/atom/thing in view(2, living_pawn))
			if(!thing.mouse_opacity)
				continue
			if(thing.IsObscured())
				continue
			possible_targets += thing
		var/atom/target = pick(possible_targets)
		if(target)
			controller.blackboard[BB_MONKEY_CURRENT_PRESS_TARGET] = target
			controller.queue_behavior(/datum/ai_behavior/use_on_object, BB_MONKEY_CURRENT_PRESS_TARGET)
			return

GOOD:

	if(!controller.blackboard[BB_MONKEY_CURRENT_PRESS_TARGET])
		controller.queue_behavior(/datum/ai_behavior/find_nearby, BB_MONKEY_CURRENT_PRESS_TARGET)
		return

	if(prob(50))
		controller.queue_behavior(/datum/ai_behavior/use_on_object, BB_MONKEY_CURRENT_PRESS_TARGET)
		return SUBTREE_RETURN_FINISH_PLANNING

As you can see we're putting the search behavior... on a behavior! and since the planning subtree passes to other subtrees afterwards, the monkey will still find things to do. The next pass, if the search behavior was successful the action can be completed.

Finally, we've reached the final stop on this controller rabbit hole: Behaviors! These are what subtrees are planning, and the AI will do these from first planned all the way to the end, just like it runs through subtrees.

As before, let's take a look at a basic example of one:

/datum/ai_behavior/follow
	behavior_flags = AI_BEHAVIOR_REQUIRE_MOVEMENT | AI_BEHAVIOR_MOVE_AND_PERFORM
	required_distance = 1

/datum/ai_behavior/follow/perform(delta_time, datum/ai_controller/controller, follow_key, range_key)
	. = ..()
	var/mob/living/living_pawn = controller.pawn
	if(!istype(living_pawn) || !isturf(living_pawn.loc))
		return

	var/datum/weakref/follow_ref = controller.blackboard[follow_key]
	var/atom/movable/follow_target = follow_ref?.resolve()
	if(!follow_target || get_dist(living_pawn, follow_target) > controller.blackboard[range_key])
		finish_action(controller, FALSE)
		return

	var/mob/living/living_target = follow_target
	if(istype(living_target) && (living_target.stat == DEAD))
		finish_action(controller, TRUE)
		return

	controller.current_movement_target = living_target

/datum/ai_behavior/follow/finish_action(datum/ai_controller/controller, succeeded, follow_key, range_key)
	. = ..()
	controller.blackboard[follow_key] = null

This behavior makes the ai move to one tile away and finish the action, only finishing the action if the target is dead (success) or out of range (fail). When the action finishes, the follow target is unset by finish_action() regardless of success. Nice!

The last important thing to know is that behaviors take the keys from subtree planning as arguments. They do not search for the blackboards they need themselves.

BAD:

/datum/ai_behavior/play_instrument

/datum/ai_behavior/play_instrument/perform(delta_time, datum/ai_controller/controller)
	. = ..()

	//bzzt! using blackboard keys directly! let the subtree pass this in!
	var/datum/song/song = controller.blackboard[BB_SONG_DATUM]

	song.start_playing(controller.pawn)
	finish_action(controller, TRUE)

GOOD:

/datum/ai_behavior/play_instrument

/datum/ai_behavior/play_instrument/perform(delta_time, datum/ai_controller/controller, song_datum_key)
	. = ..()

	var/datum/song/song = controller.blackboard[song_datum_key]

	song.start_playing(controller.pawn)
	finish_action(controller, TRUE) //NOTE: you may forget, but this doesn't end the proc! return after it if you have code later

Wow, what a tangent! But it's important to understand subtree planning as it is the core of our AI. We have a subtree for the cows to occasionally make sounds, which can be interrupted by the tipping subtree (since cows can be tipped!) The Blackboard stays empty for our cows, since the tipped subtree does not have any blackboards it needs to read that could change per-ai controller. The Tipping blackboards are handled by the subtree's setup.

/datum/ai_controller/basic_controller/cow
	blackboard = list()

	ai_traits = STOP_MOVING_WHEN_PULLED
	ai_movement = /datum/ai_movement/basic_avoidance
	idle_behavior = /datum/idle_behavior/idle_random_walk
	planning_subtrees = list(
		/datum/ai_planning_subtree/tip_reaction,
		/datum/ai_planning_subtree/random_speech/cow,
	)

And... we're finished! The tip_reaction subtree hooks into signals and runs behaviors when the cow is tipped, the random speech occasionally plans speech, the idle behavior runs when no behaviors are planned, and the cow acts like a cow! We used a mob in this case because everyone knows how a cow works as it's a very simple creature, but AI Controllers work on anything! It's just as valid of a use case to make, say, the staff of animation apply AI Controllers to items.