Schedule

From Valve Developer Community
Jump to: navigation, search

A schedule is a list of tasks for an NPC to perform. A new schedule is chosen only when there is no active one; this might be because the NPC has only just spawned or because the last schedule just completed, failed, or encountered an interrupt condition.

Creating a new schedule

Enumeration

Schedules are identified with a number. Naturally, enums are employed for human readability.

enum
{
	SCHED_DODGE_ENEMY_FIRE = LAST_SHARED_SCHEDULE, 
	LAST_MY_NPC_SCHEDULE,
};

The "last schedule" values are used to prevent collisions between enums when inheriting from existing classes. LAST_SHARED_SCHEDULE is the end of the standard list of schedules that are shared by all NPCs; if you are inheriting from something other than CAI_BaseNPC you will probably want to check your baseclass and get its own "last schedule" value.

Definition

Once the schedule is enumerated we can start defining it within the AI_BEGIN_CUSTOM_NPC block. All schedules use the same structure:

AI_BEGIN_CUSTOM_NPC( npc_custom, CNPC_Custom )
	DEFINE_SCHEDULE
	(
		SCHED_DODGE_ENEMY_FIRE,

		"	Tasks"
		"		TASK_FIND_DODGE_DIRECTION	3"
		"		TASK_JUMP	 		0"
		""
		"	Interrupts"
		"		COND_LIGHT_DAMAGE"
	)
AI_END_CUSTOM_NPC()
Warning.pngWarning:The first character of each string (except for the 'gap') must be a space or a tab. Your schedule will otherwise be invalid!

There are two parts to the definition:

Tasks
The list of sequential tasks an NPC must perform in order to complete the schedule. See Shared tasks for the engine's basic set.
Note.pngNote:Every task requires a numeric argument. If the task doesn't actually make use of one, just pass 0.
Interrupts
A list of conditions that will cause the schedule to be abandoned, and a new one chosen, if any are ever detected.

In the example above the NPC will attempt to find a suitable direction to dodge in (checking in a maximum of three directions, judging by the parameter) before using the output of that task, stored somewhere in the class, to perform the movement itself. But if it encounters COND_LIGHT_DAMAGE (any damage greater than zero) during the process, it will abandon the schedule and select another.

The behavioural code which decides what the NPC actually does is defined in the component tasks.

SelectSchedule()

int SelectSchedule(void) is called whenever an NPC finds itself without a schedule, and contains the logic that decides which should be selected to fill the gap. The NPC's current state and conditions usually play a large part in the decision.

A schedule is selected if the function returns it's name - e.g. return SCHED_DODGE_ENEMY_FIRE;.

Tip.pngTip:If you expect to write a lot of schedule selection logic, you may find it useful to split it into sub-functions of your own making. CAI_BaseNPC for instance has SelectIdleSchedule(), SelectCombatSchedule(), etc. which are called depending on the NPC's state.

Useful functions

HasCondition(int condition)
True if the specified condition has been set for the current think. Of course, you'd use your enumerated names instead of passing an integer directly!
GetState()
Returns the NPC's state. You can also access m_NPCState directly, but GetState() is read-only and therefore safer.
return BaseClass::SelectSchedule()
If none of your own schedules were picked, there are very few situations where you won't want to pass through to the base class.

TranslateSchedule()

TranslateSchedule() is called immediately after SelectSchedule(). It is designed to allow child classes to replace their parent's or parents' schedules with those of their own without having to duplicate selection logic.

int CNPC_Custom::TranslateSchedule( int scheduleType )
{
	switch( scheduleType )
	{
		case SCHED_IDLE_WALK:
		{
			return SCHED_CUSTOM_IDLE_WALK;
			break;
		}
	}

	return BaseClass::TranslateSchedule( scheduleType );
}