Behavior-based AI framework: a technical overview

Yes, I'll be departing the land of the living briefly on a trip to Melbourne, city of the ever-obscured sun. So before I leave, I want to take the chance to write one more post about my AI work, continuing from last week's post about the very general philosophy behind my design choices. The weekend has been a flurry of commits, though a lot of the work was based on earlier versions of code I'd written (most notably the Sensor class and datablock), so I pretty much knew what I was doing when I sat down to write stuff. All of my work is public in my fork of T3D, so I urge you to check it out if you want to get your hands on this code, or just see what it looks like.

What I want to do in this blog is look at how the design I introduced last week is implemented in practice. I'm actually really excited about getting to this stage at last. Since the last time I tried to work on AI, I created Walkabout, which was quite an exercise in user experience design. This time, when working on AI, I began to think more about how people - myself included! - would actually use this AI in missions. So without further ado, I'll present the system from the top down:

Placing AI characters

The first time I wrote this kind of AI, I left everything down to datablock properties - brain type, sensor type, etc. This has a certain elegance, in that once you create an object, the other objects used to give it AI (specifically, a Sensor and a BehaviorManager) are taken care of. However, it means you have to control everything through scripts, which isn't so nice when you're trying to write a level in a visual editor.

The first stage of adding AI characters to a level is obviously placing them in the world editor. I tend to favour using SpawnSpheres for placing things like characters and items in levels, so this time I decided to work with their spawnScript property to define the properties of spawned characters. That meant creating some utility functions to make that process quite quick and easy. Here's a screenshot of the current system in use:


Defining a patrolling AI character in a mission
The text in the screenshot is a little small, so here's that script again:

AIBrainClass($SpawnObject, BasicBrain);
AIPatrolBehavior($SpawnObject, GatePath, 0.1);

These are two of my utility functions, and I'm really happy at how they give the mini-script a very declarative flavour. The first line creates a brain (BehaviorManager) for the AI character, and the second actually starts running a simple behavior to make the character patrol through the nodes of the path named GatePath (you can't really tell from the screenshot, but my testing level is a very blocky orange castle). This behavior runs with a priority of 0.1 - in effect, fairly low.

Braaaains

Ugh, did I just make a zombie reference? Whatever. Let's move on. The AIBrainClass function is really simple. Actually, I've simplified it for this blog post, but the idea is the same in my own scripts - I've just split it up to be more general and reusable.

function AIBrainClass(%obj, %class)
{
   if(isObject(%obj.brain))
      %obj.brain.delete();
   %obj.brain = new BehaviorManager() {
      class = %class;
      object = %obj;
	  resources[0] = "move";
	  resources[1] = "aim";
	  resources[2] = "voice";
   };
}

You can see we just create a BehaviorManager object with some resources and a specific class. That class isn't anything special - it's the standard TorqueScript inheritance specifier, which allows me to write functions in a particular namespace. This is very handy for callbacks, like this one:

function BasicBrain::onEvent(%this, %event, %evtData)
{
   // Dispatch event to running actions.
   %this.event(%event, %evtData);
   // React to event however we feel necessary.
   switch$(%event)
   {
      case "onDamage":
	     // Decide whether this is a small or large amount of damage.
         %amount = getWord(%evtData, 0);
         %pain = (%amount < 50)
            ? "ouch"
            : "ouch!";
	     // Start a pain reaction action.
         %this.startAction(AIPainAction, // Which action to run
            getMin(0.9, %amount / 100), // Priority of the action
            %pain); // Data for the action
   }
}

This is a simple handler that gets called whenever some event happens to the character. For example, I've hijacked PlayerData's onDamage callback to call %obj.brain.onEvent(...). This means that all running actions will be notified that the character just took damage. I'll come back to events a bit later, but right now let's go over the rest of this function. Once we've dispatched the event to running actions, we can actually take the chance to add some reaction to the event. Because this function is for a particular brain class (in this case, BasicBrain), these reactions are specific to characters using this class.

In this example, I've chosen to respond to onDamage callbacks with a pain reaction. This is implemented by simply starting a new action in the BehaviorManager. Notice that there's no mention of a Behavior here - this action is simply tossed into the manager at some priority between 0 and 0.9, and when it ends, it ends. Let's look in more detail at how this action works.

A simple AIAction

Actions, of class AIAction, are declared in much the same way as datablocks, except they're strictly server-side objects. have a look at the declaration for AIPainAction:

new AIAction(AIPainAction) {
   // Use this character's "voice" resource queue.
   resource = "voice";
   // If we can't start immediately, don't bother joining the queue!
   allowWait = false;
   // We want to be notified of any events that happen.
   receiveEvents = true;
};

function AIPainAction::onStart(%this, %obj, %data, %resume)
{
   // Use the AIPlayer::say function to play a bark given by %data.
   %obj.say(%data);
}

function AIPainAction::onEvent(%this, %obj, %data, %event, %evtData)
{
   // This event is generated when the AIPlayer finishes playing an audio file started by the say function.
   if(%event $= "onFinishedTalking")
      return "Complete";
   return "Working";
}

Let's break this down bit by bit. The definitions in the AIAction object are fairly self-explanatory, but I will explain allowWait a bit further. If I had set that member to true, the action would be happy to be superseded by higher-priority actions using the same resource, and if, when it was first started, it was not the highest-priority action, it would go into the queue and wait until the higher-priority actions finished. Setting it to false means the action is a one-shot deal: if it's run, and it's not the highest-priority action in the "voice" queue, it fails immediately. Similarly, if it's in progress, and a higher-priority action comes along, it stops immediately instead of waiting.

The onStart callback is called whenever an action reaches the head of the queue - the %resume variable is set if the action had previously started and was waiting. For this action, I just use the 'say' function (which you can find in my Moment script project!) which plays a sound and then generates the onFinishedTalking event. Which, you can see, is caught in the action's onEvent callback.

Actions also have an onEnd callback which is called when the action leaves the head of the queue (for whatever reason), but this action doesn't need to do anything at that time.

This callback-oriented design means that actions don't constantly poll conditions like how close to the goal we are. In my last pass at this sort of AI framework, I was writing script functions that would be called every tick, evaluating the distance to the target and returning success or failure based on that. I realised that all this work is already being done in classes like AIPlayer, which generates an onReachDestination event when it (surprise!) reaches its destination. This makes for clearer action design as well as better performance.

Putting it together: Behaviors

Now we can move onto the second part of our simple spawn script: the call to AIPatrolBehavior. This is just a convenience function that creates a Behavior of class AIPatrolBehavior. A Behavior is a simple object that only needs to do one thing: respond to a stopped action. Here's the event function for the patrolling behavior:

function AIPatrolBehavior::onActionStopped(%this, %action, %data, %index, %status)
{
   // Ignore failures and waiting.
   if(%status !$= "Complete")
      return;
   // Select next node.
   %this.pathNode++;
   if(%this.pathNode >= %this.path.getCount())
      %this.pathNode = 0;
   // Start a new action to move to the new node.
   %this.object.brain.startAction(AIWalkToAction, // Specify action
      %this.priority, // Give it a priority
      %this.path.getObject(%this.pathNode).getPosition(), // Location to go to
      %this); // We own this action
}

This function is called whenever an action ends that was owned by this Behavior. That is determined by the last argument of startAction, as you can see in the script. In this example, all we do is add a new action to the manager, and keep moving to locations around the path. In more complex behaviors, you might have a lot of logic to think about in these callbacks, and you'd want to consider whether the action ended on a success or failure.

Where do we go from here?

Well, my goal is obviously to create some more Behaviors that do interesting things! High on my list is a conversation behavior that orchestrates a conversation between two characters - and if I can implement the design I'm thinking of, it should be able to function as well for guard-to-guard conversations as it does for NPC-to-player dialogue. Also, of course, combat behaviors - once I have some weapons in my project, at least!

I've also been working furiously away at AI senses, which I'll save for another blog post (maybe that'll give me something to do on the 12-hour bus ride...). While detection is working well, I need to refine the callbacks so that the mose useful events can be given to the BehaviorManager.

Once that's all working, I can actually focus on designing the AI, not just implementing it. Doing things like making sure not every character in a room says 'hi!' to you at the same time when you walk in. Making teams and having AI respond differently to enemies and friendlies. Designating 'out-of-bounds' areas where guards don't like you to be. Adding weapon selection and handling. The list goes on... but I'm looking forward to all of it.