Actbusy

From Valve Developer Community
Jump to navigation Jump to search

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.

Games

[confirm]

  1. Half-Life 2 Half-Life 2
  2. Alien Swarm Alien Swarm

Limitations/Bugs

Icon-Bug.pngBug:The check to see if npcs will fit on an actbusy node is slightly off. It references the placement of the node in editor. If ai_debug_actbusy 3 is showing issues, try moving the nodes up a couple units. Forcing the npc to teleport to the node avoids this issue.  [todo tested in?]
Icon-Bug.pngBug:Only some Half-Life 2 Half-Life 2 NPCs know how to act busy. These are:   [todo tested in?]
Icon-Bug.pngBug: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.  [todo tested in?]

Use GitHub to prevent duplicate or outdated bug reports at the wiki.

File format

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

Actbusy structure.png

An ai_goal_actbusy tells an 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.
  • The info_node_hint entity sometimes should be placed 4 units above the ground for correct working.

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

One or more info_node_hint's

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 actbusy activity, and must be performable by an NPC for the NPC to consider the hint.

If teleport 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.

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)

Files

🖿mod\scripts\actbusy.txt - lists all the usable Actbusy actions.

See also

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Actbusy&oldid=399509"