From Valve Developer Community
Revision as of 20:31, 3 July 2005 by TomEdwards (talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

An actbusy routine provides a framework for NPCs to perform interesting actions when not doing anything useful. The presence of hostiles or anything else that requires a response will end an actbusy schedule. It consists of two components:

  • ai_goal_actbusy (One per NPC name group)


  • ai_goal_actbusy_queue (One per NPC name group)
  • info_node_hints with Hint set to World: Act Busy Hint.

An actbusy system is semi-scripted. NPCs will be told to actbusy and will be told at which locations they can do so, but will decide which specific location to use themselves. An actbusy_queue system is fully scripted.


Actbusy structure.png


  1. An ai_goal_actbusy tells a NPC to actbusy, and the NPC chooses from actbusy hints in its hint group.
  2. An ai_goal_actbusy_queue tells a NPC to join a preset queue of actbusy hints. The NPC moves along the queue under the control of the goal.


Controls the hints and NPCs that are the act busy. Although it forces a NPC to actbusy, it does not force it to do so at a particular hint.


  • Actor(s) to affect: the name of any NPCs to act busy. Supports wildcards.
  • 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.


  • 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 Hint Group
    • Named destination to teleport to
    • 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 actbusy. Supports wildcards.
    • 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.


  • 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


Behaves in the same way as ai_goal_actbusy, except that actbusy hints and NPCs are ordered in a queue. The queue can be moved forwards, and the when first NPC in the queue leaves it can be given orders.

Actbusy hints not specified in the keyvalues will function as normal, as will NPCs who cannot join the queue.

Hint activities should not require exiting or the queue will freeze.


  • Exit Node: The name of the first info_node_hint or path_corner a NPC should head to when leaving the queue. Required.
  • Node 1-20: The info_node_hints that make up this queue.
    • Node 1 is the front of the queue
    • Defines the maximum number of NPCs queuing
  • Must Reach Front: a NPC must strictly be at Node 1 before being able to leave the queue.


  • PlayerStartedBlocking: Informs the goal that the player is blocking the point in the queue passed as a parameter.
  • PlayerStoppedBlocking: Informs the goal that the player is no longer blocking the point in the queue passed as a parameter.
  • MoveQueueUp: Moves all NPCs in the queue up one position, and sends the first NPC to the Exit Node.


  • OnQueueMoved: fires when the queue is moved.
    • Outputs remaining NPCs in queue
  • OnNPCStartedLeavingQueue: fires when the NPC at the head of the queue starts to leave.
    • Activator is NPC
    • Outputs the NPC name
  • OnNPCLeftQueue: fires when the NPC that has just left the queue reaches the Exit Node.


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.


  • Hint: must be set to World: Act Busy Hint to become an actbusy hint.
  • Hint Activity: specifies what the NPC should do while acting busy on this node.
    • Must be an actbusy activity
    • Must be performable by a NPC for NPC to consider hint

Limitations and Bugs

  • There will always be a certain proportion of NPCs covered by an ai_goal_actbusy that do not actbusy. This does not seem to be configurable.
  • Some actbusy activities do not end on their own, and require further input from the I/O system.
  • 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.


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