AI Programming Overview

From Valve Developer Community
Revision as of 21:38, 8 January 2008 by TheRatcheteer (talk | contribs) (Possessive is just I-T-S. Scalawag.)
Jump to: navigation, search

An NPC will react to its environment in specific ways, depending on what mood it is in, at that given time. The depth of the AI implementation allows the programmer to create dumb bots that perform a minimal set of tasks, to complex characters that simulate true to life behavior.


From a high-level perspective, NPCs follow a fairly simple (and real-world logical) process for making decisions. The easiest way to understand it is to examine the basic outline first, and then dig further into the necessary exceptions afterwards.

Each time an NPC "thinks", it does the following:

  • Perform Sensing
    • The NPC generates a list of entities that it can see, and another list of NPC sounds that it can hear. The NPC ignores entities & sounds that it doesn't care about, and hence doesn't place them into the lists.
  • Generate a list of Conditions
    • Conditions are key pieces of information that the NPC will be using to make a decision. They are extracted from the sensed lists of entities & sounds, and from the state of the world and the NPC. Examples of conditions are: "I can see an enemy", "I have taken some damage", or "My weapon's clip is empty".
  • Choose an appropriate State
    • The NPC State is the overall assessment of the NPC based upon the list of Conditions. For example: NPCs with a visible enemy will consider themselves in Combat State. NPCs who have no enemies left after killing one will drop back to Alert State. NPCs with a health of 0 would move to Dead State.
  • Select a new Schedule if appropriate
    • The Schedule is the overall action being taken by the NPC, which is then broken down into sub parts for the NPC to actually perform. Schedules are chosen based upon the NPCs current State, and the list of Conditions. Examples of schedules are: "I'm taking cover to reload my gun", "I'm chasing after my enemy", "I'm moving to a position where I have line-of-sight to my enemy".
    • NPCs will choose a new schedule for one of two reasons:
      • They finish performing the last part of the current schedule.
      • They generate a condition that their current schedule has specified as an Interrupt.
    • If neither of these are true, the NPC will continue running its current schedule.
  • Perform the current Task
    • The Task is the sub part of a Schedule that describes a discrete action within the schedule. The tasks must be performed, one by one, for the schedule to be completed. For example, the "I'm taking cover to reload my gun" schedule would be broken down into the following tasks: "Find a position to take cover at", "Generate a path to that position", "Run the path", and then "Reload my gun".
    • Many tasks take some time to perform (like the "Run the path" task in the above example), so the NPC will keep performing that task each time it thinks until the task is completed. Then, it'll move onto then next task in the current schedule, or pick a new schedule if there are none left.

Code Overview

For us to understand how to code our own custom NPC's we must understand the programming logic that drives Source's AI. Most of this logic is driven by the code in CAI_BaseNPC, in order to start making a custom NPC, this is the best place to subclass from.

Each time the NPC thinks with NPCThink() a core method is executed RunAI().

RunAI() gathers the NPC's current Conditions according to its environment and determines the best State it should be in, any kind of logic can influence the NPC's conditions and state including the things it sees or the sounds it hears.

The NPC will then determine the best Schedule to run for the given conditions and state, it will maintain any current schedules or interrupt them and run more appropriate schedules to those given conditions and state.

The following links describe states, conditions, schedules and tasks in more detail:

For convenience a stripped down version of the RunAI() method is shown below in order to give you an idea of how an NPC's core logic works.

void CAI_BaseNPC::RunAI( void )










Outside this NPC core logic, there are two event handling methods.

HandleAnimEvent() handles script events(defined in scriptevent.h), NPC events(npcevent.h), and animation events(defined in eventlist.h, and DECLARE_ANIMEVENT). An animation event is fired when the game play animation sequence with an event option.

If a sequence is defined in .qc as:

$sequence fire01 "Fire01" fps 30 snap activity ACT_VM_PRIMARYATTACK 1 { event AE_MUZZLEFLASH 0 "SHOTGUN MUZZLE" } node 2 

It will fire an animevent AE_MUZZLEFLASH with an option "SHOTGUN MUZZLE" when played.

HandleInteraction() handles specific interactions between different types of characters. HandleInteraction() in CAI_BaseNPC shows how this BaseNPC reacts to barnacle grabbing. If you want your NPC to interact with another NPC, Use DECARE_INTERACTION() macro to define one, then call its target entity's DispatchInteraction() to make it react to the interaction.