Data/Effects

## Effects

### Description

Effects are one of the Data Types used when making custom abilities or weapons. Damage, picking the units to hit, adding behaviors, "interactions in general" between units are achieved through effects. Individual effect types are listed below and are linked to their own pages in which each field is explained in detail.

### Hints

* Not all effects directly do something. Some are for the purpose of executing other effects (Switch and Set are examples of this)
* Some effects cannot be placed first in an ability. For example, you cannot put an Issue Order effect for start, since it cannot relate to a launch point.
* Further on the same topic, the first effect put in an ability usually determines how the targeting will occur. For example, if you put a Set effect with a Unit Location, you will never be able to target the ground, even if the child effects create an aoe.
* There is a way to bug/glitch an auto-cast with effects. If you use a set effect on a point location as a first effect of an Effect - Target ability, which possess an apply behavior effect inside it (from which the effect's location is "Target") , it will not do anything for manual cast since the point location resolves to no unit (the ground). However for an auto-cast ability, it will be considered as the ability targeted a unit for basis (even if targeting the ground) and will mark the triggering target of the auto-cast as the Target location of the apply behavior.

## Effect: Sub Types (Classes)

* Add Tracked Unit
* Add Tracked Units
* Apply Behavior
* Apply Force
* Apply Kinetic
* Cancel Order
* Clear Tracked Units
* Create Healer
* Create Persistent
* Create Unit
* Creep
* Damage
* Destroy Healer
* Destroy Persistent
* Enum Tracked Units
* Issue Order
* Iterate Inventory
* Iterate Magazine
* Iterate Transport
* Last Target
* Launch Missile
* Load Container
* Modify Player
* Modify Unit
* Morph
* Random Point In Circle
* Redirect Missile
* Release Magazine
* Remove Behavior
* Remove Kinetic
* Remove Tracked Unit
* Return Magazine
* Search Area
* Set
* Switch
* Teleport
* Transfer Behavior
* Use Calldown
* Use Magazine
* User Data

## Common Fields

The following fields are ones found on most if not all effect types, and have the same functionality among them. This is to provide a common reference point for those shared fields as to not have conflicting definitions within each effect type

### (None) - Can Be Blocked

Determines whether the effect can be blocked. By default, set to off.

* When an effect is executed, the game will query the response structure on the impact unit and check its Block Chance and any validators.
* If blocked, the effect will be canceled and won’t execute. The effect will then send an actor Effect event with Blocked as its sub name so that users can set appropriate actors.
* This feature is useful for creating spell blocking behaviors.

### (None) - Debug Trace

Check this field to create visual effects when testing effects in the Test Mode. The indicators also indicate the Launch Location by pointing at it. There's much more about this field, but it's best giving it a try to see what it can do.

### (None) - Owning Player

(Unknown) We might be able to understand from the Lurker; If the target of a lurker attack goes out of range, it triggers a Destroy Persistent that uses this field.

### Effect - AI Notify Effect

Interpellates (awares) the AI that a follow up child effect of "this" effect should be evaluated upon its "AI Notify Flag" field.

* It goes without saying the "Response Flags" field is also connected.

Ex: The liberator Defender mode creates a Persistent in the circle, and uses this field by indicating the search effect that will occur in the child effects.

### Effect - AI Notify Flags

These flags are used by the Tactical AI to determine how to assess and react to this effect vs others occuring around it. It is also used to generate the danger maps that are used by the AI for navigation purposes (in order to avoid AoE attacks like Nukes).

Ex: The Liberator Defender Mode search area effect (that applies a behavior on ememies to be potential target for the Concord cannon) was previously announced by a previous effect using the AI Notify Effect. Now, the flags here represents how the AI will behave.

* **Help Friend:** This effect helps the friend (of the casting unit)
* **Hurt Enemy:** This effect hurts the enemy (of the casting unit)
* **Hurt Friend:** This effect hurts the friends (of the casting unit)
* **Major Danger:** This effect will cause major damage
* **Minor Danger:** This effect will cause some damage
* **Workers Only:** (Unknown)

### Effect - Alert

The Alert that is run when this effect is run.

### Effect - Chance

This field controls the probability the effect will be executed. Values range from 0 (0%) to 1 (100%). Normally we always want the effect to be executed so by default every effect has this set to 1.

### Effect - Kill Hallucination

* This flag, when enabled, will destroy any unit marked as a hallucination that is targeted by this effect (this will only work when the target is a unit, and not a point).

### Effect - Player

**Value / Effect**

Specifies the player that should issue the requested order which is useful for checking whether that player is allowed to issue that order (due to shared control, resources, etc). If a player is not specified then the alliance states are ignored.

* Issue Order and Modify Player have this field.

What differs many of these entries is perhaps the fact that a unit can change owner at any moment, and even while an effect tree is on going. There are permanent player changes (done by Modify Unit effect) and temporary changes (done by Buff behaviors ex: Neural Parasite). Fields qualified with (unsure) will require testing.

* Caster: Relates to the player that owned the caster before any temporary player changes. (Unsure) May not uncover permanant player changes.
* Caster Outer: Relates to the transport directly carrying the caster.
* Creator: Relates to the player that currently owns the caster.
* Hostile: Relates to player 15 (Enemy neutral). Take note that some maps have different setting, hence having Hostile player as another value than 15 (or totally removed). 15 remains the usual value by default.
* Neutral Player: Relates to player 0 (Passive neutral)
* None: Invalidates this effect.
* Outer: Relates to the first transport, above all any others that currently transports the target.
* Player Origin: Relates to the player that owned the caster before any temporary or (unsure) permanent player changes.
* Source: Relates to the source. See **Source** explanation in the Location section.
* Target: Relates to the target of the previous or specified effect.
* Target Outer: Relates to the transport directly carrying the Target.

### Effect - Response Flags

How a unit reacts to this effect being executed on it.

* Acquire: causes the targeted unit to acquire the casting unit if possible.
* Flee: causes the target unit to flee from the casting unit.

### Effect - Tech Aliases

Gives an alias to the effect that it can be refered in requirements in bulk.

* Requirement are not customized to check effects, which makes this field plainly useless for the moment.

### Effect - Validators

The set of validators that must return true for the effect to execute. Putting a list in this field is by default verified as logic "AND" (all must be true to pass).

* If an effect is prevented, so is the actor linked to that effect.
* To understand how they work between effect, always think that a validator comes first before the effect. In that sense, a validator always validates the result of the PREVIOUS effect. Then the effect runs. It does not validate the effect in which it's imputed. Ex: Using a search effect, you can use filters. Then, the next effect which is an Apply behavior, can have a behavior unit type that requires a Marine. This means that the search will end up passing the condition that it searched for a marine to continue with the apply behavior.
* Do not confuse with the Create Persistent effect that uses a "Periodic Validator". This one validates its own effect. (in fact it has both fields).
* Fun fact: An Effect-Target ability could avoid using target filters, and instead put a Filter validator in its first effect, resulting of the same outcome. In other words, an ability can be considered as the greatest parent effect that start everything. Use this knowledge at your advantage when upgrade an ability to change its target filters; Instead of making a second one, you can just operate with a validator (or) that will select the proper rules.
* In a particular case, the validator will not prevent the effect to execute but rather, direct it. If the following effect of a Random Point In Circle contains a validator that prevent the chosen random location from being chosen, another location will be pin pointed. It is unknown how many attempts there can be (thus leading to a game crash? yet this hasen't happened).

### Target - Impact Location / Effect - Unit / Impact Unit / Which Location / Which Unit / Launch Location / Launch Unit

This field has multiple names, field categories (new effects since latest patch are (None):) and all are the main field to designate the epicenter of where the effect will be generated at.

**Effect**

* Sets the effect that is used as the reference for targeting. Can be used to refer to units utilized further back in an effect tree. The best way to use this, is to keep in mind that "previous/parent effect" of the effect is the location of the target. For example, if setting "Target Unit" of a Search Effect as a referal in this case, it is not the result of the search that will be the "Target Unit", but rather, the target unit which preceded the effect. Sometimes, to change the focus of what is the target unit, one can use a "Create Persistent" effect to aim at a particular target. This is useful in some cases such as preceding Issue Orders effect that are badly configured when attempting to identify the target, the caster, etc (Random Point In Circle Effect has a bug that prevents it from launching an Issue Order from within the Caster has the "Unit", and while this is an unfortunate bug, this is a situation where you need to fix it).
* Using this field can also change the perspective of a point in the following way: If an effect is casted at "Caster Point", it will only look where the caster was when the chain of effects started. If using a more recent effect with the "Caster Point" involved, the point will be where the caster was when "this" effect was launched.

**Value**

* The target of the effect. Not to be mistaken with the initial target of the ability/behavior/effect that leads to the execution of this effect. All of these are relative to the Effect: Unit - Effect
	+ **Target:** The target of the ability or effect that caused this effect to be executed (the parent effect or ability). As in most fields/data of the editor, target location often falls back to caster in the absence of a logical target. For example, setting an innate buff behavior on a unit, makes any child effect from it target the caster if using "Target". Same goes for Effect-Instant abilities, which the first effect doesn't have a valid "target" other than self.
	+ **Caster:** The unit that started the chain of effects that included this effect.
	+ **Source:** A unit location where specific chains of effects come from. At first, the caster is always the source, but that location can change its scope according to certain effects. For example if a behavior is applied to some unit, and that behavior then uses another effect, the \*\*Source\*\* of the new child effect will the behavior unit. This can be seen as a checkpoint. Note that the behavior cannot use itself as a source for its own validation, only its child effects; Therefore putting a validator that checks "Source" in the behavior's validators sections will check the previous source before that behavior in the first place. Be also advised that it is possible to bug out a source within a certain logic, example: if you add a behavior on a unit, and that behavior leads to a Create Persistent effect that periodically creates Launch Missile effect, based on source location as for where it originates from, the launch effect will fallback to the Caster unit if the behavior is disabled or removed (or the previous source that is still alive or even fail if there is nothing left). Because the launch effect was created periodically after the behavior was removed/disabled, the source didn't exist anymore (even if the unit carrying the "said" behavior is still alive) at the exact moment when the launch started. Summary, a source unit is valid for as long as it exists, and that includes the behavior that designates it. You can also create a source when launching a unit with the Launch Missile effect, which the launched unit or missile becomes the source. Use Calldown will cause the next effect to validate the "called down" unit as a source. A Set effect can transform its current target location into a Source target as well. Be careful if using a Create Unit effect afterward, because this effects sets origin by setting the caster the source, which removes any source reference aside from caster. You can however set its origin field as "Source" to fix this. Damage effect's field Damage Inherit Effect causes the impact unit of the damage to become a source.
	+ **Outer:** The unit that is the containing unit for the target. This is used in conjunction with effects that target units inside a unit with a transport, inventory or magazine (Iterate Transport, Iterate Inventory or Iterate Magazine) or with Redirect Abilities which allow the caster to be inside the hangar of a Transport, Inventory or Arm Magazine ability. Does not trace the owning magazine unit from "External Magazine units", they really must be inside it. Be careful when setting an effect cast on outer when the unit leaves the transport, because at the moment the unit is out, the outer becomes itself, not the tranport anymore.
	+ **Unit Origin:** The original unit which created this effect chain. This is still unknown in some practical cases, for example, if applying a behavior and this behavior has a periodic effect that targets the Unit Origin, it will not, for unknown reasons.
* More precise locations in other cases can be found in some effects where it is relevant (such as Create Persistent). Take note that there are a lot of "Outer" locations. This can be explained by the fact that transports can be inside other transports (or magazine) and etc. For locations that are Unit/Point, they can also mean to target the Unit, Or the Ground if used by Effect-Target abilities. They might in other situations only seek the unit but then stop at their last location when they become invalid/dead. In summary, while their meaning can differ in various situations/circumstances, here's an overall description of each location:
	+ **Caster Outer Point:** Only the ground point of the unit carrying the Caster in transport or Magazine. The transport/magazine unit will not be a target in child effects, unless using an "Effect" field demanding the Unit of this effect.
	+ **Caster Outer Unit:** Only the unit carrying the Caster in transport or Magazine. The transport/magazine unit will still be a target in child effects.
	+ **Caster Outer Unit/Point:** The ground of the Unit carrying the Caster in transport or Magazine at the exact moment when this effect was launched. The transport/magazine unit will still be a target in child effects.
	+ **Caster Point:** Only the ground point of the Caster unit.
	+ **Caster Unit:** Only the caster unit.
	+ **Caster Unit/Point:** The ground of the Caster unit at the exact moment when this effect was launched. The Caster unit will still be a target in child effects.
	+ **None:** Voids the location, voiding the effect itself. This might allow the effect to execute in some cases, while in others not. It is rarely used.
	+ **Origin Point:** (Unsure) Only the ground point of the Caster unit. It is not clear how this differs from the Caster locations and fails in some situations.
	+ **Origin Unit:** (Unsure) Only the caster unit. Seems to be useful in cases of Create Unit effect creating a unit that would cast ability returning to its creator (ex: Parasitic Bomb dummy unit returns kills to Origin Unit).
	+ **Origin Unit Or Point:** (Unsure) Only the caster unit, or its point, according to the situation.
	+ **Outer Unit:** Only the transport or Magazine unit carrying everything, the first one above all. The transport/magazine unit will still be a target in child effects.
	+ **Outer Unit/Point:** The ground of the transport or Magazine unit carrying everything, the first one above all at the exact moment when this effect was launched. The transport/magazine unit will still be a target in child effects.
	+ **Source Point:** Only the ground point of the Source unit.
	+ **Source Unit:** Only the source unit.
	+ **Source Unit/Point:** The ground of the Source unit at the exact moment when this effect was launched. The Source unit will still be a target in child effects.
	+ **Target Outer Point:** Only the ground point of the unit carrying the Target in transport or Magazine. The transport/magazine unit will not be a target in child effects, unless using an "Effect" field demanding the Unit of this effect.
	+ **Target Outer Unit:** The ground of the Unit carrying the Target in transport or Magazine at the exact moment when this effect was launched. The transport/magazine unit will still be a target in child effects.
	+ **Target Outer Unit/Point:** The ground of the Unit carrying the Target in transport or Magazine at the exact moment when this effect was launched. The transport/magazine unit will still be a target in child effects.
	+ **Target Point:** Only the ground point of the Target unit.
	+ **Target Unit:** Only the Target unit.
	+ **Target Unit/Point:** The ground of the Target unit at the exact moment when this effect was launched. The Target unit will still be a target in child effects.

**Theory to understand**

When indicating the source or target into an effect, you have to locate the latest location of that target or source. The easiest way to put it, is that if your weapon targets a unit that creates this chain of effects: "Set > Set > Set > Set > Damage" (and set is usually set to unit location by default), well believe it or not, the first target location will carry on up the farthest child effect which is the Damage effect. This happened because the Set, as other effects, can carry on the target location for its next childs effects.

Knowing that, it will be in most case the parent effect, in other cases not. For example, you have Search (Impact location is Target Unit/Point Location)> Set (Point Location) > Damage (Target Unit Location). If the damage effect must be created at "Target Unit" of a parent effect which was a Set with a point location, there will be no unit found by that damage effect since its previous/parent Set effect only looked upon the ground, of its own parent search effect's result. In that very case, using the effect field on the damage can tell to damage the Target Unit of that "Set" effect, meaning the result target unit location of the search effect. You would not use the Search Effect as the specified effect in the damage impact location, because then, it would mean to aim the damage at the parent effect of that Search effect, which could be another target.

It also essential to understand that effects can carry on the target location, while others create their own. A create persistent with a Caster Location will have any of its child effects currently set to target location, reoriented to caster when applying their effect; Otherly put, they aim at the target of their parent effect, which is the Caster location. They could however aim at the Target of the Create Persistent (as an Effect Location), meaning the target unit of the effect that created that persistent effect,

Random Point in Circle (its result becomes target of its child effect), Search Effect (its result becomes target of its child effect), Launch Missile (missile becomes source), an apply behavior creates a behavior (which creates child effects that can refer the source as the behavior unit. Be aware that a behavior validator (remove or disable) validating source is not the unit behavior itself, but rather the source unit before that behavior. Only its child effect will have their new source location update to it. Create Unit created unit becomes the target for its child effect. Iterate effects give to their child effect the transported/magazine/item unit as a target and surprisingly, even modify unit effect can lead to other child effect location with its Turret modify. "Iterate" type of effects, Enum Tracked Units also generate a result target. There is many more examples, it is just essential to understand that some effects generate a target location, others not.

### Target - Marker

Used by some effects and abilities to mark or remove the mark from a location, later used in the child effects if using marker target sorts, or validators. Location that are marked can be compared later, as the effect is able to identify where to look up for repetitions prevention or not.

* The game is very fussy as to what effect trees can apply markers so using a stacking Buff behaviour with a caster history is preferable in most situations.
* Testing shows that a marker is usually limited to 1 effect tree (1 weapon shot, 1 ability casting, etc.). The second cast, weapon fire is considered as a different effect tree, so not the same marker. For example, Colossus attack has periodic damage, but that will only hit once because of it's "No Marker" state. Note that in some cases you need to indicate the Match Flags, in others not. For example, you can't put match flags on a Create Healer effect, because the effect is periodic on its own and will cancel over itself. Using the Match flags also indicates, that in the very same effect tree, the effect cannot occur again. Be aware that all of this can be false if putting a duration to the marker. See the duration section below.
* On the same topic, Colossus Thermal lance seems to set a marker Match ID on the Create Persistent, which leads further to a Search, and then a damage effect with the validator "No Markers". This limits only to once the damage dealt, even for every periodic search. That being said, we could think that setting the match flag on the Persistent was used to indicate at which point of the effect three that the validator should look up to, to be aware from which parent effect the "no marker" damage effect comes from, to be not repeated. It seems, as far as tested, that the place where the marker field needs to be set with match flags has to be equal or earlier than the parent effect/behavior that is the epicenter of the repetition. For example, if a buff behavior periodically casts a damage effect with area effect, this area of effect can have the "no markers" flag, but will only work if previously before that behavior, an effect (such as apply behavior for example) that applied this behavior has its match flag set. Setting it on the very same damage effect will fail, as it seems to be unable to track its own executing effect. There is a way to counter this if the buff is innate: have the initial effect of the behavior reapply it on itself and set a marker on that initial apply behavior effect.
* Weapons are somehow trickier. Since the repetition is not located on the weapon itself, but between the player's units, it is most likely only possible to use a marker acquire target sort **if** the marker on the weapon identifies the "Casting Player" as the mark location. The logic remains that, since a target sort is used to sort the result of the weapon acquire, the marker being set on it is early enough to be allow a follow up with a valid marker target sort (because you can't set a marker and a TS on the same effect to make it work). As a counter example: setting Unit will only limit to the casting unit. Since you can't compare with other units shooting at the target (or not), it won't do any good.
	+ Remember to disabled Priorities on the weapon to make it successful.
	+ It's best to build up a secondary marker target sort and to add it a "Target" location, which will allow the TS to track the target of the weapon as a reference location to avoid or not. Setting target on the core marker TS would work, but remember that will also impact all other instances of data that are currently using that marker TS.
	+ It seems that "Damage Point" field is not accounted for when verifying if any unit is currently shooting at the target.
	+ Sadly, the target sort marker may fail.
* Setting a marker over again seems to ruin a previous marker. Setting a duration seems to affect the same casting. It is probably why they use "Mismatch", to end the mark.

**Count**

* The number of markers added by this effect.

#### **Duration**

* Sets a duration to the marker. Like buff behaviors, leaving duration 0 means that it stays forever. On marker, this means that is stays until a new effect tree/version is launched. Putting a duration means that along the way, the effect may be repeated again (if "no markers" validator is used) according to the duration being expired.

**Link**

* The ID string allowing several effects to share the same pool of markers (used by Marker type Target Sorts)

**Match Flags**

* Determines how markers are shared. Match means that if the effect in question has the validator "No Markers", this effect will match and be prevented.
	+ **Casting Player:** The marker is shared between all units of the same player
	+ **Casting Unit:** The marker is shared only by effects from the same unit
	+ **Id:** The marker is shared only by effects from the same effect tree
	+ **Link:** The marker is shared only by effects with the same link

**Mismatch Flags**

* Determines how markers are not shared. Mismatch means that if the effect in question has the validator "No Markers", this effect will not be matched and will persue.
	+ **Casting Player:** The marker is not shared between all units of the same player
	+ **Casting Unit:** The marker is not shared by effects from the same unit
	+ **Id:** The marker is not shared by effects from the same effect tree
	+ **Link:** The marker is not shared by effects with the same link