Data/Validators/Unit Filters

## Unit Filters

### Description

One of the most obvious validators to mimic any Filters that can be found on Search Area Effects, abilities like Effect to Target, their auto-cast filters as well. While ressembling to the Enumerate Area validator's filter, this validator is way more direct than anything else. Placed on any effects/validators, it is a reliable method to use filters in the most unreachable places.

### Exemple Use

* Skipping the easiest examples, this validator is underestimated for some aspects: it can be used to validate any Air units and Ground units, useful when using Damage effects. Let's pretend that an explosion is created in the sky, and that explosion generates blast radius, it would make sense that anything around that is flying gets hit, and not the ground? Yes the damage has its own filter, but let's say that this explosion can be sent as well on ground units, and this time, the air units must be spared. In that case, a wise way to use it would be to created 2 damage effects, with each its Unit Filters validator, from which the Unit value's effect field represents the first target of the explosive ability. This will tell: if the explosion is launched on a flying target, then yes, make the damage explode on air units only (using the proper filter in the damage effect).
* Using it as a generic form of valid target filters can be handy too. If a Create Persistant effect isn't channeled, and should stop if the unit is dead or gone, using this validator with common filters (such as Dead Excluded, Hidden) can be useful to stop it in the periodic validator field.

* On Buff Behaviors, the Buff Flag "Disable During Construction" is relatively weak sometimes, as it allows the behavior to pass for a brief moment before being properly disabled (some actors create events even if they shouldn't on construction). This is the case of why this filter is used, as it blocks the behavior from A to Z (if using the Under Construction Excluded Filter). Use it in the **Validator - Disable** Field of the behavior.

#### In transport

* Whether the desire location is, Hidden Required is the way to go. But to make sure even more, exclude Outter in the same filter. This will avoid triggers/map marking situations. This was the case before Unit State was improved with "In Transport".

## Field Categories

### Filters

Filters target, that must return true to the target (**Unit**).

* **Air:** Determined by the unit's plane array that has "Air" checked. A Colossus is also considered as a air unit. Is not determined by height or mover.
* **Air Unit:** (Broken) New filter that was implented by Blizzard, but undocumented. An attempt to target with a "AirUnit" target filters was never able to target any ground unit. It gave an "Error" message on anything.
* **Armored:** Attribute that can checked on a unit's data in the attribute field. Can also be state flaged by a buff behavior.
* **Benign:** State flag that can be checked from a buff behavior only.
* **Burried:** Flag that can be checked on a unit's data in the flag field. Can also be state flaged by a buff behavior. Keep it mind that a Zerg unit that is visualy underground could fail this filter, still. The only reason why it is considered "burried" is because it is flaged so on the unit. In other cases, we could think of units that "Root" themselves in the ground for example, that are not necessarly burrowed, such as a Spine Crawler.
* **Biological:** Attribute that can checked on a unit's data in the attribute field. Can also be state flaged by a buff behavior.
* **Can Have Energy:** The Energy Maximum field on a unit's data must greater than 0. Can also be granted from a buff behavior by adding maximum vital of energy.
* **Can Have Shield:** The Shield Maximum field on a unit's data must greater than 0. Can also be granted from a buff behavior by adding maximum vital of shield.
* **Cloaked:** Flag that can be checked on a unit's data in the flag field. Can also be state flaged by a buff behavior. Not to be mistaken with Visible. A cloaked unit, visible or not, remains considered as "Cloaked". In that very case, even if you cannot target it, it still passes, as long it remains cloaked (although you won't be able to target it without detection or an AOE effect). A buff behavior that suppresses Cloak can invalidate this filter. Take note burried units (most of them) are also cloaked.
* **Dazed:** State flag that can be checked from a buff behavior only.
* **Dead:** State in which the unit dies (0 hp). The fact that the corpse remains or not does not matter. You cannot directly filter a dead unit on sight, which is why this filter is usually used to invalidate an effect or a behavior that cannot remain if the unit dies.
* **Decaying:** A Decaying unit is defined as one that is currently on the ground and has been dead for a while. This is in contrast to one that has already been killed but is still in the midst of falling to the ground and generating a corpse. In technical terms, this is true when Death Time is active, and Revive Delay is over.
	+ This purpose of this filter is so that abilities that target corpses will not work on units that have recently died and are still in the process of generating a corpse
	+ If the unit's Death Time has been set to -1, the decay phase will be skipped. For instance, Warcraft III heroes should never decay.
* **Destructible:** Flag that can be checked on a unit's data in the flag field only. Debris/Rubbles that block paths are usually those.
* **Detector:** State flag that can be checked from a buff behavior only.
* **Ground:** Determined by the unit's plane array that has "Ground" checked. A Colossus is also considered as a air unit. Is not determined by height or mover.
* **Ground Unit:** (Broken) New filter that was implented by Blizzard, but undocumented. An attempt to target with a "Ground Unit" target filters was never able to target any ground unit. It gave an "Error" message on anything.

* **Hallucination:** State flag that can be checked from a buff behavior only.
* **Has Energy:** If the unit's energy pool currently has 1 or more energy.
* **Has Shields:** If the unit's shield pool currently has 1 or more shield.
* **Hero Unit:** Flag that can be checked on a unit's data in the flag field only (Named Hero). This is different from “Heroic”, which is an attribute.
* **Heroic:** Attribute that can checked on a unit's data in the attribute field. Can also be state flaged by a buff behavior.
* **Hidden:** Hidden units are usually units that either inside other units (magazine units), inside a transport or inside inventory. Units that are "No Draw" from buff behavior or unit's flags are not considered. Can also be given from triggers or marked as such in the map without the unit being in an actual transport/magazine/inventory. Vespene Geyser under their built on are considered "Hidden".
* **Hover:** Attribute that can checked on a unit's data in the attribute field. Can also be state flaged by a buff behavior.
* **Invulnerable:** Flag that can be checked on a unit's data in the flag field. Can also be state flaged by a buff behavior.
* **Item:** Field "Item" on a unit's data. In order to be considered an item, the field must have an entry. If left blank, the unit is not considered to be an "Item".
* **Light:** Attribute that can checked on a unit's data in the attribute field. Can also be state flaged by a buff behavior.
* **Map Boss:** Attribute that can checked on a unit's data in the attribute field only.
* **Map object:** Attribute that can checked on a unit's data in the attribute field only.
* **Massive:** Attribute that can checked on a unit's data in the attribute field. Can also be state flaged by a buff behavior.
* **Mechanical:** Attribute that can checked on a unit's data in the attribute field. Can also be state flaged by a buff behavior.
* **Missile:** Flag that can be checked on a unit's data in the flag field only.
* **Neutral Hostile:** Unit that belongs to player 15.
	+ There 2 are logical rules for using this:
		1. Player 15 is an enemy player for everyone, so it is important the enemy filter does not conflict with this one being validated. In most cases, enemy filter should be allowed.
		2. A buff behavior that changes the owner, which is not innate or based on a duration will not successfully change the owner to player to 15 and will not be considered as it is a "temporary" change.
* **Non Building Unit:** Flag that can be checked on a unit's data in the flag field only. Since this is newly implented, any faillure to target a unit with this will rend the "Error" message.
* **Outer:** The most external source of a unit. What is "most" is the unit itself, but what could be more would be an external transport/magazine of the unit. For example: Location target = If the target is in a transport: We're filtering its transport instead of the target. If the target is not in a transport, we're filtering the target itself, that is the most external (outer) location of itself. Think of being into a pile of blankets, and to try to always validate what's the first blanket on top; that'd also be helpful to remember when trying to validate a transport, that is currently inside another transport, that's inside a magazine, etc etc. Note that external magazine do not have an "outer unit". Wisely, a unit has an outer unit when it's hidden.
* **Passive:** State flag that can be checked from a buff behavior only.

* **Powerup**: True when the CUnit\_PowerupEffect field value is valid.

* **Powerup Or Item:** A powerup or an item.

* **Prevent Defeat:** Flag that can be checked on a unit's data in the flag field only.
* **Prevent Reveal:** Flag that can be checked on a unit's data in the flag field only.
* **Psionic:** Attribute that can checked on a unit's data in the attribute field. Can also be state flaged by a buff behavior.
* **Radar:** State flag that can be checked from a buff behavior only.
* **Raisable:** State of the unit that is modified from a Modify Unit effect. Tests have failed, it is not clear how to use this filter.
	+ Patch note from 5.0: CEffectModifyUnit can now set if a corpse is **Unraiseable**.
	+ Unraiseable allow us to mark whether a corpse has already been used.
		- For example, while a Ghoul is eating a corpse, the corpse still exists, but the modder might not want it to be revivable or raised as Undead. In this case, the modder can set abilities to only accept Raiseable corpses and set corpses to Unraiseable while being eaten.
* **Resistant:** Flag that can be checked on a unit's data in the flag field. Can also be state flaged by a buff behavior.
* **Resource (Harvestable):** Field "Resource State" on a unit's data. Harvestable must be selected. This is usually Mineral fields. Refinery, Extractor or Assimilator are true as well.
* **Resource (Raw):** Field "Resource State" on a unit's data. Raw must be selected. This is usually unused Vespene Geysers (no structure built on it). Refinery, Extractor or Assimilator are false.
* **Revivable:** Flag that can be checked on a unit's data in the flag field only.
* **Robotic:** Attribute that can checked on a unit's data in the attribute field. Can also be state flaged by a buff behavior.
* **Self:** The caster of the effect.
* **Silenced:** State flag that can be checked from a buff behavior only.
* **Stasis:** State flag that can be checked from a buff behavior only.
* **Structure:** Attribute that can checked on a unit's data in the attribute field only.
* **Stunned:** State flag that can be checked from a buff behavior only.
* **Summoned:** Attribute that can checked on a unit's data in the attribute field. Can also be state flaged by a buff behavior.
* **Uncommandable:** Flag that can be checked on a unit's data in the flag field. Can also be state flaged by a buff behavior.
* **Unstoppable:** Flag that can be checked on a unit's data in the flag field. Can also be state flaged by a buff behavior.
* **Visible:** If the unit is visible. The limitations are not fully detailed, but usually, it should not be hidden or in no draw state. A unit can be cloaked, but still visible if detected, otherwise it will not be considered as visible. It is unsure if it's unit actor being visible is considered, but it shouldn't be.
* **Worker:** Flag that can be checked on a unit's data in the flag field only.

### Other Unit

Probably evaluates another unit at the same occasion. In this case, both units should return true to the filters to have it work.

### Unit

Which unit is filtered.

In certain cases, use the Effect field to specify a parent effect that contains which unit to be filtered. This will allow this validator to be placed further in a child effect where it is relevant to know what the parent unit conducting this effect was.