View source for NPC Sensing

{{stub}}
'''Sensing''' is the first stage of an NPC's [[Decision_Making_Overview|Think Routine]] where the NPC generates a list of entities that it can see, and another list of NPC sounds that it can hear. The NPC ignores entities and sounds that it doesn't care about.
<br>{{TODO|More information on sensing (visual and by sound) would be very helpful.}}

==Concepts==
Two of the key concepts for spatialised NPC senses are PVS and LOS:
*[[PVS]] '''Potentially Visible Set''' - the group of visleafs which are visible from the NPC's [[visleaf]]. PVS is the spatial area (measured in visleafs) that is potentially visible to the NPC from his current location. If another entity (usually a Player or NPC) enters this area, the NPC might consider doing a Viewcone test and/or an LOS test. In contrast to the NPC's [[line of sight|LOS]] (Line of Sight), PVS is not restricted by props and func_detail brushes, or the direction in which the NPC happens to be looking. 

*[[Viewcone]] represents the spatial geometry of the NPC's current Visual Field - the angle or scope of the cone is the NPC's [[FOV]] angle and the length or depth of the cone's long axis is the NPC's [[Range]]. The Viewcone ''direction'' is determined by the NPCs current orientation, or [[Angles]]. The edges or boundries of the Viewcone represent the NPC's Periphery of Vision.

:*[[Range]] is the maximum distance between the target and the NPC where the NPC will recognise/react to the target's presence. If [[FOV]] is the "Scope" of the Viewcone, [[Range]] is the "Depth" of the Viewcone. It appears to be the same for all NPCs; 2048 units. If the '''Long Visibility''' flag is set, range seems to be unlimited. The '''Think Outside PVS''' flag does not affect viewcone range. By default if you shoot an NPC from outside its range it does nothing about it. 

:*[[FOV]] '''Field of View''' - In Source, an NPC's FOV value is the '''Angular Field of View''' used to calculate its Viewcone. The edge of the FOV, or projected sides of the viewcone represent the periphery of vision. (By contrast, the ''Player's'' FOV value represents the ''Horizontal Angular Field of View'' of a ''Viewwedge'' rather than a viewcone. The wedge's rectangular cross-section corresponds to the Player's rectangular screen.)

:*[[line of sight|LOS]] '''Line of Sight''' -  If a potential target is within the NPC's Viewcone, the LOS 'ray trace' test checks if the target is hidden from view by another object; LOS is blocked by all [[Solid]] geometry (Models, func_detail brushes, etc.) unless the brush/model is has a [[CollisionProperty|SolidMask]] that is '''NotSolid to LOS''', ie ''Transparent''. (e.g. SolidMask:Grate is NotSolid to bullets & LOS, whereas Unbreakable Glass ...?)

*[[PAS]] '''Potentially Audible Set''' is the spatial area (measured in visleafs) in which sound sources are potentially audible to the NPC. Unlike Vision, Hearing is not limited to a directional Viewcone.

==NPC Configuration==
A quick overview of NPC entity configuration within Hammer to accomplish various NPC behaviour.

=== KeyValues ===

==== Squad Name ====
NPCs that are in the same squad (i.e. have matching squad names) will share information about enemies, and (depending on AI capabilities) will take turns attacking and covering each other.

==== Sleep State ====
''Sleep State Holds the NPC in stasis until specified condition.''

Sleeping prevents the NPC from being rendered or thinking. Instead it waits for a ''Wake'' input or for the specified condition to become active.
Sleeping NPCs do not play idle sounds either. It is common to have NPCs in 'inactive' portions of the map sleep, for performance reasons.

* '''sleepstate = 0 : None (default)'''
: NPC does not sleep when spawned.

* '''sleepstate = 1 : Waiting for threat'''
: NPC sleeps initially. Wakes the NPC once it establishes [[LOS]] with a threat.
: The LOS test is independent of NPC [[Viewcone]]. If a line can be drawn between the NPC and the threat, the NPC is woken up.
: This setting can make the NPC pop into view e.g. when turning around a corner.
: {{clarify}}: What exactly constitutes a ''threat'', besides enemies?

* '''sleepstate = 2 : Waiting for PVS'''
: NPC sleeps initially. Wakes the NPC once the player enters the NPC's [[PVS]].
: This can be very early depending on the world geometry. But it should ensure that the NPC does not suddenly pop into view.

* '''sleepstate = 3 : Waiting for input, ignore PVS'''
: NPC sleeps initially. Can only be woken through external inputs, such as the Wake input, or by squad mates (if they have ''Wake Squad'' set), or through the ''Wake Radius'' (see below).

* '''sleepstate = 4 : Auto PVS'''
: NPC sleeps initially. Wakes the NPC once the player enters the NPC's PVS. Puts it to sleep again, once outside PVS. This will even pause enemies pursuing the player. They won't forget their target, though, and continue pursuing once woken up again.
: Should not be used with ''Wake Radius'', it can create an infinite wake-sleep loop when the player is inside the wake radius, but not inside its PVS.

* '''sleepstate = 5 : Auto PVS after PVS'''
: NPC doesn't sleep initially. After establishing 'PVS contact' once, it goes to ''Auto PVS'' mode.

==== Wake Radius ====
'''Auto-wake if player within this distance.'''

If non-zero, this wakes the NPC as soon as the player is within this distance. Waking by distance complements the ''Sleep State'' waking conditions, it does not override them.

==== Wake Squad ====
If set to '''"Yes"''', the NPC automatically wakes all squad mates when waking up.

=== Flags ===
* '''Wait for Script'''
: Not the same as sleeping. 
: The NPC's Sensing only becomes active after playing a script such as [[scripted_sequence]] or [[aiscripted_schedule]]. That means it will initially not acquire enemies. This can be used to keep the NPC in place before triggering the script. After the script has been completed, the NPC leaves the waiting state. The same happens when the NPC is being attacked.

* '''Wait Till Seen'''
: The NPC's Sensing only becomes active after the Player has seen the NPC. The "seen by player" test does not seem to use the Player's entire FOV. 

=== I/O for NPC scripting ===
* '''BaseNPC Input : "Wake" :''' Wakes up the NPC if it is sleeping.
* '''BaseNPC Input : "UpdateEnemyMemory" (targetname) :''' Updates the NPC's memory of the specified target. Useful for making NPCs aware of an enemy, such as !player.
* '''BaseNPC Output : "OnSleep" :''' Fired when this NPC enters a sleep state.
* '''BaseNPC Output : "OnWake" :''' Fired when this NPC comes out of a sleep state.
* '''BaseNPC Outputs : "OnFoundPlayer" / "OnFoundEnemy" (targetname) :''' Fired when the NPC finds the player / an enemy. NPC must not be sleeping or scripting for this to work.