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 or group of NPCs to actbusy, and the NPCs then choose from actbusy hints in their hint group. There are several criteria that the node must match for the NPC to be able to choose it:

• The node type must be set to World: Act Busy Hint
• The distance to the node must be less than the radius specified by the Search Range for Busy Hints key in the ai_goal_actbusy.
• The node must not be locked by any other NPC.
• The NPC must be able to play the animations required by the node.

NPCs will lock their chosen node immediately, before walking to it. This prevents multiple NPCs trying to walk into each other at the node.

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

<target_name_or_class> The targetname or classname of any NPCs to act busy. Wildcards are supported.

• SearchType

<boolean> Set it to true if the actor keyvalue specified is a classname.

• busysearchrange

<float> Maximum distance between an actbusy hint and NPC for the NPC to consider it.

• visibleonly

<boolean> An 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 decide to move, at which point they will return to normal behavior.

• SetBusySearchRange <float>

Alter the busysearchrange keyvalue.

• ForceNPCToActBusy <string>

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. "nearest" If this keyword is specified as a parameter, the NPC will choose the nearest valid actbusy node, instead of choosing one randomly from all valid actbusy nodes. Custom activity to use when navigating to the 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 <EHANDLE>

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 <EHANDLE>

Makes a parameter-specified NPC find a NPC exit point hint and vanish. Supports wildcards.

Outputs

• OnNPCStartedBusy <EHANDLE>

Fires when a NPC targeted by the goal starts an actbusy sequence.

• OnNPCFinishedBusy <EHANDLE>

Fires when a NPC targeted by the goal finishes an actbusy sequence.

• OnNPCLeft <EHANDLE>

Fires when a NPC ordered by the ForceThisNPCToLeave input leaves.

---

info_node_hint

Todo: Move this to its own page

These make up the actbusy locations. They cannot be info_hint or info_node_hint_air entities. For a more general guide on hints, see info_hint. {{note|hinttype must be set to 12 (World: Act Busy Hint) to become an actbusy hint.|}

{{note|hintactivity 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

Keyvalues

• Template:Kv targetname
• Template:Kv angles
• Template:Kv hintnode

Outputs

• OnNPCStartedUsing <EHANDLE>

Fired when an NPC has reached this node and started using it. Passes along the NPC.

• OnNPCStoppedUsing <EHANDLE>

Fired when an NPC has stopped using this node. Passes along the NPC.

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

The ai_debug_actbusy convar is the easiest way to debug act busy problems. Set it to a value between 1 & 4. The values are as follows:

1. Constantly draws a line from each NPC to their selected act busy node.
2. Whenever any NPC chooses to act busy, draw a line to the selected node, and draw the NPC's hull at the node.
   • This is useful to spot nodes placed in locations where the NPC will be unable to actually stand on the node. Make sure the NPC's hull doesn't interpenetrate the world around the node.
3. Selected NPCs will display why they're not able to choose act busy nodes.
   • To use this, select the desired NPC with the npc_select command. When that NPC next looks for an act busy node, you'll see a small text string appear on every node explaining why the NPC didn't choose that node.
4. Display all act busy logic.
   • This will show you all the logic decisions that each NPC makes as it runs the act busy AI. It's mostly useful for detecting bad entity I/O in the map.

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.

Download Example (VMF)

See also

• Actbusy Queues
• info_node_hint
• Activities