Actbusy

The Actbusy system is used by level designers to make NPCs look "busy". NPCs act busy on level designer placed nodes, and continue to act busy until one of several conditions are met (such as spotting an enemy). The level designer has full control of when NPCs act busy, what actions they should perform when acting busy, and what conditions should cause them to stop.

The components of the Actbusy system are as follows:

• actbusy.txt
  • A text file that resides inside your mod\scripts directory. It lists all the usable Actbusy actions.

• ai_goal_actbusy
  • The Actbusy control entity. Used to control how & when the NPCs it controls should act busy.

• One or more info_node_hints with Hint set to World: Act Busy Hint
  • These specify the places in the world where NPCs can act busy, and point to an entry within the actbusy.txt file. The entry tells the NPCs what actions they should perform at the node.

Structure

An ai_goal_actbusy tells a NPC to actbusy, and the NPC chooses from actbusy hints in its hint group.

---

actbusy.txt

This text file resides inside your mod\scripts directory. It contains the list of Actbusy actions that Actbusy hint nodes can use. Entries match the following format (from the actbusy.txt file):

"act busy name"			This is the name that the level designer specifies in the hint node.
{ 
	"busy_anim" 		"Activity Name".
	"entry_anim"		"Activity Name"
	"exit_anim"		"Activity Name"
	"busy_sequence"		"Sequence Name". 
                                  If specified, this is used over the activity name. Specify it in  the hint node.
	"entry_sequence" 	"Sequence Name". 
                                  If specified, this is used over the entry anim.
	"exit_sequence" 	"Sequence Name". 
                                  If specified, this is used over the exit anim.
	"busy_sound"		"Sound Name". 
                                  If specified, the NPC will play this sound when it plays the busy anim/seq. 
                                  Can be a GameSound name or a response rules concept.
	"entry_sound"		"Sound Name". 
                                  If specified, the NPC will play this sound when it plays the entry anim/seq. 
                                  Can be a GameSound name or a response rules concept.
	"exit_sound"		"Sound Name". 
                                  If specified, the NPC will play this sound when it plays the exit anim/seq. 
                                  Can be a GameSound name or a response rules concept.
 	"min_time"		"Minimum time to spend in this busy anim"
	"max_time"		"Maximum time to spend in this busy anim"	
                                  0 = only stop when interrupted by external event
	"interrupts"		One of:
				 "BA_INT_NONE"   break out only when time runs out. No external influence will break me out.
				 "BA_INT_DANGER" break out only if threatened
			 	 "BA_INT_PLAYER" break out if I can see the player, or I'm threatened
				 "BA_INT_AMBUSH" break out if I see an enemy in my forward view cone.
				 "BA_INT_COMBAT" break out if I see an enemy or any sign of combat (bullet impacts, etc).
}

An example entry might look like this:

"sit_in_chair_03"
{	
   "busy_sequence"   "Sit_Chair03"
   "entry_sequence"  "Idle_to_Sit_Chair03"
   "exit_sequence"   "Sit_Chair03_to_Idle"
   "min_time"        "10.0"
   "max_time"        "20.0"
   "interrupts"      "BA_INT_COMBAT"
}

To use this entry, the level designer would specify "sit_in_chair_03" in the Hint Activity of the Actbusy hint node. Any NPC who's model contained the required entry, busy, and exit sequences would be allowed to use the node. An NPC choosing to use the node would walk to it, play the "Idle_to_Sit_Chair03" entry sequence, and then repeatedly loop the "Sit_Chair03" busy sequence. The min_time and max_time entries would make the NPC act busy on the node for a random amount of time between 10 and 20 seconds. The "BA_INT_COMBAT" option would make the NPC break out of the act busy early if it saw an enemy, or heard a nearby combat sound (bullet impact, explosion, etc). When the NPC left the act busy node (due to the time being met or seeing combat), the NPC would play the "Sit_Chair03_to_Idle" exit sequence before falling back to normal AI.

Note that some Actbusy entries specific 0 min & max times. NPCs using these entries will never leave the node due to a timeout. If the entry also specifies an interrupt of "BA_INT_NONE", the NPC will never leave the node, until they receive further input from the I/O system.

---

ai_goal_actbusy

The ai_goal_actbusy entity points to a set of NPCs to control, and contains options about how it should go about making those NPCs act busy. There are two common methods of using ai_goal_actbusy entities. The first is to fire the Activate input on the ai_goal_actbusy entity, which will cause it to start ordering the NPCs under its command to act busy. The second is to leave the ai_goal_actbusy inactive, and send it ForceNPCToActBusy inputs to order specific NPCs under its command to act busy.

Keyvalues

• Actor(s) to affect: the name of any NPCs to act busy. Supports wildcards. Can be a class name or a targetname.
• Search Range for Busy Hints: maximum distance between an actbusy hint and NPC for the NPC to consider it.
• Visible Busy Hints Only: a NPC will only consider actbusy hints in view when deciding which to use. Once the choice has been made it will not change, even if new hints become visible.

Inputs

• Activate: begins ordering NPCs to actbusy.
• Deactivate: ends ordering NPCs to actbusy. They will remain busy until they next decide to move, at which point they will return to normal behaviour.
• SetBusySearchRange: alter the Search Range for Busy Hints keyvalue.
• ForceNPCToActBusy: Force a specified NPC to actbusy. Takes the following optional parameters, separated by spaces:
  • Name of NPC(s)
  • Name of the Hint node. Used to force an NPC to act busy on a specific node.
  • "teleport"
    • If this keyword is specified as a parameter, the NPC will teleport onto the actbusy node instead of navigating to it.
  • Custom activity/sequence to perform at actbusy node
    • Activities prefixed with $ will be performed while moving to the hint, e.g. $ACT_RUN
  • Maximum time to actbusy
    • Specify 0 to have them actbusy until disturbed
• ForceThisNPCToActBusy: makes a parameter-specified NPC act busy.
  • Only useful as a connection for outputs of other entities that pass along the NPC. The most common usage of this is to connect the "OnSpawnNPC" output of an npc_maker to this input, since the "OnSpawnNPC" output contains the spawned NPC in the parameter.
  • If there are multiple NPCs with the same name, only one will be ordered
• ForceThisNPCToLeave: makes a parameter-specified NPC find a NPC exit point hint and vanish. Supports wildcards.

Outputs

• OnNPCStartedBusy: Fires when a NPC targeted by the goal starts an actbusy sequence.
  • Outputs the NPC name
• OnNPCFinishedBusy: Fires when a NPC targeted by the goal finishes an actbusy sequence.
  • Outputs the NPC name
• OnNPCLeft: Fires when a NPC ordered by the ForceThisNPCToLeave input leaves.
  • Outputs the NPC name

---

info_node_hint

These make up the actbusy locations. They cannot by info_hint or info_node_hint_air entities. For a more general guide on hints, see info_hint.

Keyvalues

• Hint: must be set to World: Act Busy Hint to become an actbusy hint.
• Hint Activity: specifies the name of the entry in the actbusy.txt file that contains the data needed by the NPC to act busy on this node.
  • Must be an actbusy activity
  • Must be performable by a NPC for NPC to consider hint

Limitations and Bugs

• Only some HL2 NPCs know how to act busy. These are:
  • Combine Soldiers
  • Metropolice
  • Player companions ( Citizens, Alyx, Barney, Grigori, Eli, Kleiner )
• At one point during testing there were two groups of identical info_node_hints being alternated in a map, but only one group would work.

Debugging

There are some useful debugging tools built into the engine to help you debug your act busy setups. TBD: List them.

Example

This example map contains 16 npc_citizens and 16 actbusy hints. Each actbusy hint is set to an activity that can be performed by a npc_citizen. Try spawning hostile NPCs and observing the citizens' reactions to it.

Example (VMF)

See also

Actbusy Queues

Info_node_hint

Activities