Condition

Overview

Conditions are key pieces of information generated by the NPC Sensing system. Conditions reflect the state of the world and the NPC, and they're used by the NPC to assess whether the NPC's current action is a good one, and then to choose a course of action if necessary.

Conditions abstract away complex information about the world into simple concepts. Some examples of conditions are: "I can see an enemy", "I have taken some damage", or "My weapon's clip is empty". The AI system will generate a variety of base conditions for any NPC, and specific NPC classes can then specify and control their own custom conditions to deal with things unique to their own behavior. For example, antlions drown when in water, so they have a custom condition that tells the "I am underwater".

Conditions validate an NPC's current course of action by acting as interrupts. Understanding this requires some knowledge of Schedules. Each schedule has an associated list of conditions that will act as interrupts for that schedule. If an interrupt condition is set for an NPC's current schedule, that schedule will be thrown away and the NPC will be forced to select a new one. For example, an NPC may be running a schedule to "Chase my enemy". This kind of schedule usually specifies the "I can see a new enemy" condition as an interrupt, because the NPC shouldn't keep chasing the old enemy if it has found a a newer, more important one.

Adding Custom Conditions

Conditions are enumerated inside the NPC class. For example, if our new NPC has a custom condition to reflect "I'm hungry", our condition enum should look something like this:

enum 
{
	COND_MYNPC_HUNGRY = BaseClass::NEXT_CONDITION,
	NEXT_CONDITION
};

It's good practice to include the NEXT_CONDITION enum, so that NPCs derived from our NPC can use BaseClass::NEXT_CONDITION to declare their custom conditions without causing collisions with ours.

Conditions must then be declared inside the AI_BEGIN_CUSTOM_NPC block. This is done through the DECLARE_CONDITION macro. For the above example, we'd use this line:

DECLARE_CONDITION( COND_MYNPC_HUNGRY )

Condition Handling

AI_BaseNPC stores conditions in the m_Conditions bitstring, but it's rarely necessary to access it directly. Instead, condition handling inside an NPC class is usually done through the following functions:

• void GatherConditions( void ) : The primary entry point for condition generation. The AI_BaseNPC::GatherConditions() function will handle entity sensing, so make sure you call back to the base class.
• void SetCondition( int iCondition ) : Sets a condition on.
• void ClearCondition( int iCondition ) : Clears a condition off.
• bool HasCondition( int iCondition ) : Returns true if the specified condition has been set on.
• void BuildScheduleTestBits( void ) : Used to modify the list of interrupts for the current schedule. Schedules define their own static list of interrupts. This function allows you to dynamically modify that list based upon the current state of the NPC & world.

NPC Code Examples

GatherConditions()

Here's a slightly trimmed version of the Antlion's GatherConditions(). Antlions jump around a lot, and sometimes land on top of other NPCs. They need to know whether they've landed on an NPC when decision making, so they generate a condition when they have. Antlions also need to drown if they ever find themselves in water, so they set a condition when their water level reaches waist high.

void CNPC_Antlion::GatherConditions( void )
{
	BaseClass::GatherConditions();

	// See if I've landed on another NPC after jumping.
	CBaseEntity *pGroundEnt = GetGroundEntity();
	if ( ( ( pGroundEnt != NULL ) && ( pGroundEnt->GetSolidFlags() & FSOLID_NOT_STANDABLE ) ) && (  GetFlags() & FL_ONGROUND ) )
	{
		SetCondition( COND_ANTLION_ON_NPC );
	}
	else
	{
		ClearCondition( COND_ANTLION_ON_NPC );
        }

	// See if I've landed in water
	if( m_lifeState == LIFE_ALIVE && GetWaterLevel() > 1 )
	{
		SetCondition( COND_ANTLION_IN_WATER );
	}
}

BuildScheduleTestBits()

The Assault Behavior wants to only use COND_NEW_ENEMY and COND_SEE_ENEMY as interrupts on the three specified schedules if the current assault point allows the NPC to divert from the assault. This kind of dynamic interrupt specification can't be done in the static schedule definitions, and is exactly what BuildScheduleTestBits() is designed for.

void CAI_AssaultBehavior::BuildScheduleTestBits()
{
	BaseClass::BuildScheduleTestBits();

	// If we're allowed to divert, add the appropriate interrupts to our movement schedules
	if ( m_hAssaultPoint && m_hAssaultPoint->m_bAllowDiversion )
	{
		if ( IsCurSchedule( SCHED_MOVE_TO_ASSAULT_POINT ) ||
			 IsCurSchedule( SCHED_MOVE_TO_RALLY_POINT ) || 
			 IsCurSchedule( SCHED_HOLD_RALLY_POINT ) )
		{
			GetOuter()->SetCustomInterruptCondition( COND_NEW_ENEMY );
			GetOuter()->SetCustomInterruptCondition( COND_SEE_ENEMY );
		}
	}
}

See Also

• Shared conditions - a list of conditions inherited by all NPCs