View source for 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_hint|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==
<center>[[Image:Actbusy_structure.png]]</center>

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 <code>mod\scripts</code> directory. It contains the list of Actbusy actions that Actbusy hint nodes can use. Entries match the following format (from the <code>actbusy.txt</code> 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 <code>sit_in_chair_03</code> 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 <code>Idle_to_Sit_Chair03</code> entry sequence, and then repeatedly loop the <code>Sit_Chair03</code> 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 <code>BA_INT_COMBAT</code> 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 <code>Sit_Chair03_to_Idle</code> 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 <code>BA_INT_NONE</code>, the NPC will never leave the node, until they receive further input from the [[Inputs and Outputs|I/O system]].

----

===[[info_node_hint]]===
These node entities make up the actbusy locations. (They cannot be [[info_hint]] or [[info_node_air_hint]] nodes.)
Their ''hinttype'' keyvalue must be set to 12 (''World: Act Busy Hint'') to become an actbusy hint, and their ''hintactivity'' keyvalue 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. It must be an [[Activities|actbusy activity]], and must be performable by an NPC for the NPC to consider the hint.

If <code>teleport</code> is added to the ''hintactivity'' keyvalue (after the activity name, separated with a space), NPCs are teleported into their actbusy state, instead of navigating to it. This appears to be of most use when the hint is on or near other geometry and props, e.g. when the NPC is sitting in a chair.

For a more general guide on hint nodes, see [[Hint nodes]].

==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:
# Constantly draws a line from each NPC to their selected act busy node.
# 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.
# 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.
# 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.

:'''[http://www.steamreview.org/external/vdc/actbusy/ai_actbusy_example.zip Download Example (VMF)]'''

==See also==
* [[ai_goal_actbusy]]
* [[info_node_hint]]

* [[Activities]]
* [[Actbusy Queues]] - Another actbusy system, used when handling queues.

[[Category:AI]]