Assault

The purpose of an assault is to make one or more NPC(s) tactically advance along a predesigned route, securing tactical points along the way. It is much more flexible than a path_corner entity.
An assault consists of two or three component entities:
* ai_goal_assault (1 per assault, optional)
* assault_rallypoint (1 per NPC)
* assault_assaultpoint (any number)
This article will show you the overall picture on how to set up an assault. (For entity specific information, see the related entity.)
__TOC__
==Structure==
An assault consists of an AI goal (the ai_goal_assault entity) gathering a set of one or more NPCs (called actor(s)) to one or more "rally point" locations (assault_rallypoint entities) where they will normally await a cue to commence the assault. On this cue, they will proceed to the first "assault point" location (assault_assaultpoint entity) to secure, or 'clear' it, and then proceed on to the next assault point (if any), clear it, and then proceed to the next, and so on.
Clearing an assault point, by default, consists of standing on its location and ensuring that there are no hostiles in sight for the timeout period, but this is completely configurable.
Assaults can be triggered in one of two ways:
# When activated, an ai_goal_assault entity can send its actor(s) to the associated assault_rallypoint(s), where they wait for the assault cue. This is the most common usage. The ai_goal_assault entity can either be activated by an Activate input, or set to start active through its Start Active keyvalue, which causes the assault to begin as soon as the map is loaded.
# Combine soldiers may be instantly associated with a rally point without the use of an ai_goal_assault entity. Using the entity I/O system, you can fire the Assault input on the soldier, providing the name of the assault_rallypoint as an input parameter. When a Combine soldier receives this input, it will search for the specified assault_rallypoint entity, move to it, and then proceed immediately to the associated assault_assaultpoint. Please note that although the Assault input can be sent to any NPC it is only supported for Combine soldiers. You may use wildcards when specifying the rally point in the parameter. You may also use the priority keyvalue of an assault_rallypoint entity as a parameter to influence this decision, if providing a wildcard which specifies more than one assault_rallypoint entity.
==Advantages==
While an assault requires extra work to set up, and the end result is very similar to other ai entities, such as aiscripted_schedule, assaults do allow for more flexibility than other scripting entities.
* You can select a group of NPCs
** Other scripting options can do this too, but this often results in the entire group heading toward a specific point, or only one member of the group moving. To create similar results, each individual npc would need to be scripted.
* More control
** With options such as "allow diversion" and "clear on contact", the mapper has more control of when an ai stops moving. Unlike an aiscripted_schedule set to interrupt on "general", which can be broken by gunfire or other sounds.
* An NPC will realistically stick to one place
** Without a combination of hintgrouping and moving to a path_corner there aren't any other options to have an ai stay at one point. Also, unlike the hintgroup set up, the ai will move to avoid grenades or reload.
==Major options==
The assault behaviour offers a flexible degree of customisation among the entities that make up an assault. This list's purpose is to provide an overview of the major options (beyond entity placement). Consult each entity's individual page for more detailed information.
* ai_goal_assault:
:Keyvalue AssaultCue: Determines what will cause the NPC to move off their rally point and begin the assault.
* assault_rallypoint:
:Keyvalue priority: Determines how appealing the rally point will be to an NPC when it has multiple rally points to choose between.
:Keyvalue assaultdelay: Time to wait at rally point after assault cue, before beginning assault.
* assault_assaultpoint:
:Keyvalue assaultgroup: Constrain an NPC's hint node use to this hint group.
:Keyvalue assaulttimeout, nevertimeout: How long to wait without seeing enemies before considering the point cleared.
:Keyvalue clearoncontact: Whether to clear assault point if the NPC encounters enemies while moving to it.
:Keyvalue allowdiversion: Whether the NPC should move to engage enemies it encounters or ignore them and follow the assault points.
:Spawnflag 1: Clear point upon arrival, unconditionally.
==Examples==
===Example map===
This example map contains a single NPC on a linear chain using all the major options available to designers when moving NPCs from assaultpoint to assaultpoint. There are four points, and each is configured differently:
# Clear on contact with enemies is enabled. When the NPC sees the hostiles, it clears out the assaultpoint and continues to 2.
# Clear this point on arrival, UNCONDITIONALLY is flagged. When the NPC reaches this point it clears it regardless of the fact that there are still hostiles in sight and begins to move towards 3.
# Allow diversion is set to No. The NPC will charge towards the assaultpoint without stopping or giving chase. It will however attack enemies in view.
# Allow diversion is set to Yes. The NPC will divert from moving to this point until there are no hostiles visible.
Note that the Metropolice cannot harm the NPC and will not attack the player in this example.
===Prefabs===
The npc_metrocop_assault and the npc_soldier_assault prefabs contains complete setups of a mass assault of metrocops and soldiers respectively.
==Notes==
* If "clear on contact" is set, a single enemy might clear not only the current assaultpoint but the next one(s). A consequence of this is that if an NPC encounters an enemy on the way to a "clear on contact" assaultpoint the assaulting NPC may never proceed to another rallypoint. This occurs regardless of the subsequent assaultpoints "Clear on contact" and "Allow diversion" settings.
* If "allow diversion" is set and the NPC encounters an enemy, the assaulting NPC will pause for a while after killing the enemy before proceeding. The article says that this pause is the length of the "timeout" setting, but in my tests it was several times as long.
* If an NPC encounters an enemy on the way to an assaultpoint marked "allow diversion" but not "clear on arrival" the assaulting NPC will be pausing twice. Mappers might need to consider this if timing is important.
* An assaultpoint with both "clear on contact" and "allow diversion" causes weirdness: if an enemy is encountered on the way to the assaultpoint the assaulting NPC will kill it, but then upon reaching the assaultpoint will not pursue or return fire from other enemies until the next assaultpoint is reached. In fact, the assaulting NPC doesn't even change direction to face the fire. This happens regardless of the "clear on arrival" or "never time out" settings.
* I didn't observe any effect of the "never time out" setting. However, all firefights were fairly brief, so it might not have had a chance to come into effect.
* All-settings-off is great for making the NPC dash to a point regardless of enemy fire and then attack everyone at the point.
* Having only "clear on arrival" on is great for making the NPC dash from point to point without pausing, regardless of enemy fire.
* The OnAssaultClear output is only fired for the last assaultpoint in a chain. All assaultpoints will fire their OnArrival output, however.
* The delay after a "Allow diversions" diversion is about 18 seconds for a 3-second "timeout" time.
* A diversion causes another such delay immediately upon reaching the assaultpoint, and then the assaultpoint OnArrive re-fires. If the NPC is again diverted before the timeout, the OnArrive output will fire again, ad infinitum. So don't spawn enemies during from the OnArrive output.
* If the first assaultpoint is set to "Clear on contact" and an enemy is sighted before reaching the assaultpoint, the assaulting NPC will never make it to the assaultpoint. If the subsequent assaultpoint has "Allow diversion" off, this will cause that (or perhaps the final) assaultpoint to fire the OnArrival output—despite the assaulting NPC being nowhere nearby and having not even gotten to the first assaultpoint, nor having yet finished dealing with the enemies. If, on the other hand, the second assaultpoint has "Allow diversion" on, no messages are sent whatsoever.
* In Half-Life 2: Episode One and Half-Life 2: Episode Two rally points behave differently than in Half-Life 2. If there is an assault point with "Never Time Out" in the assault chain connecting to a rally point, than that rally point will be "locked" and unusable until the NPC on the chain dies.
==See also==
* Dynamic assaults - A simpler system, for assaulting the player or other NPCs.
Category:AI