Condition

Conditions are key pieces of information, generated afresh by the NPC Sensing system every time NPCThink() runs, about the state of the world and the NPC. They are primarily used to select or interrupt schedules.

Some examples of conditions are:

• "I can see an enemy"
• "I have taken some damage"
• "My weapon's clip is empty"

The automatically-generated conditions above are usually supplemented by others specific to an NPC. For example, antlions drown when in water, so they have a condition of their own that tells them "I am underwater".

Tip:You can see a list of all conditions by searching in Visual Studio's 'Class View'.

Note:By default there is a maximum of 256 conditions in any one game or mod. You can increase this number in ai_condition.h, but doing so will break older saved games and increase memory usage.

Conditions and schedules

As well as being used when selecting a new schedule, conditions validate the current one by acting as interrupts. Each schedule has an associated list of conditions that will interrupt it if set. Whenever any one of them is found, the schedule is cancelled and another chosen.

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 new conditions

Conditions are enumerated inside the NPC class. For example, if our new NPC has a custom condition to reflect "I am 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 (as we do, on the first line) 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 functions

CAI_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 done with these functions:

void GatherConditions()

The primary entry point for condition generation, which is called every time the NPC thinks. Make sure you call BaseClass::GatherConditions() within it!

void SetCondition( int iCondition )

void ClearCondition( int iCondition )

Sets/clears a condition. Instead of passing an integer, you'll of course make use of your enum.

bool HasCondition( int iCondition )

True if the specified condition is currently set. Remember that conditions are thrown away and re-generated on every think.

void BuildScheduleTestBits()

This function allows you to dynamically modify a schedule's interrupts at any time. It's useful for appending your custom NPC conditions to base NPC or shared schedules.

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()
{
	BaseClass::GatherConditions();

	// See if I've landed on another NPC after jumping.
	CBaseEntity *pGroundEnt = GetGroundEntity();
	if ( pGroundEnt && 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 );
}

Todo: Why is ClearCondition() used here?

BuildScheduleTestBits()

The Assault behavior allows mappers to specify whether an NPC should divert from their path to fight new enemies or keep running. 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