Data/Effects/UserData

## User Data

### Description

Controls the amount usage of effects. Think of this effect to be nearly like a Set Effect, but that ends up with a choice of only 1 effect of the 2. Most likely, there are 3 outcomes:

1. "Effect Success" (runs the effect in that field, can be emtpy).
2. "Effect Failure" (runs the effect in that field, can be emtpy).
3. Validation fail / chance did not pass, the effect did not start.

* The main usage of this effect lies in the **result** of the effect being proceeded, which is some kind of numeric meter, an **invisible number** resulting from the mathematical formulae (amount+operation). It passes the test of Validate Max / Validate Min in order to determine if it will trigger the Effect Success or the Effect Failure. Note that it is not because we call it "Failure" that it means the effect failed. It only means that amount did not pass the validate test. Also, contrary to most effect and abilities using a Minimum / Maximum system, a value of 0 in the Validate Min/Max is considered. For example, a Set Effect with a maximum of 0 means there's no limit, same for Arm Magazine ability with its max count set to 0. Now with User Data, if the maximum is 0, it is in fact going to effect failure by default if not using proper settings.

* In of Tree of effects, User Data has a memory of its own, using the keys as locations for remembering the settings (the **invisible number**). The result of the amount being operated (ex: amount is 3 and operation is multiply, the final result of this effect is 9) will then be registered in the related chain of effects with the "Key" as string name. This is only true for one chain of effect. Starting a new chain of effects starts from scratch. Note that it is not required to step back in a loop to the same (or either one with the same source key) User Data effect in order to modify its amount further. For example: if a Create Persistent periodically creates a user data, each instance are still connected to each other in terms of amount check, even if they were created seperatly. They belong to the same tree of effects. The Tree of effect rule is however false, if we speak of a buff behavior running a periodic User Data. While of course each periodic effect is a new chain of effect, these are still kept in memory to allow each User Data to remain for as long the behavior is "Removed" or "Refreshed". Disabling the behavior does not count. Also, see the **Behavior Scope** field.

* You can loop an effect without touching the default keys (Default), for a simple loop system. Example: User Data A(EffectSucess) > Search Effect > User Data A(EffectSucess) > Etc. In this very example, you can set validate max 6, allowing the User Data to loop only 6 times and put nothing in the EffectFailure, ending the loop to nothing after 6 repeats. Of course, it is possible to overflow this effect, if not properly set.
* Hitting on a validate max / min value doesn't stop the effect from executing, thus, keeps adding up to the mathematical formuale.

##### Understanding the key system

Keys are the strings used to be recalled by other User Data effects, or when looping back to it. If the amount is modified, it is possible to alter it from a different User Data effect ID that recalls it using the **Source Key** field. Here's the role of each keys:

* Source Key: Loads/Recalls the latest User Data in the parent effects that ended up with a **key** named as such.
* Key: Is the final string name that identifies the final numeric value of the effect once proceeded. It will only be relevant if recalling it later in the effect tree with a User Data recalling it with the **Source Key** named as such. Any other User Data Effects can recall this key and it is not important if looping back to the very same User Data effect ID or not. What matters is the string name.
* What happens if **Source Key** is named "Flow" and the **Key** ends up being named "Flower" in the very same effect? This will cause the User Data to load anything that was named "Flow", proceed it, and register the final result as "Flower" for further use. If any other User Data later recalls "Flow" again with its source key, only the latest result of a key named "Flow" will be used. It will not touch the result variable named "Flower", even if that one was issued from the Source Key named "Flow".
* How can a Source Key Fail to load a previous string?
	1. It has a string name that was never used as a **Key** by a previous user data (hence being the first UD effect for example).
	2. Is blank.

User Data effect can be seen such as:

1. Source Key is the start point of the effect. It looks for a String named "Default" in the parent effects (it looks for an User Data effect in the parent effects from which its "Key" field string was named "Default"). If loaded successfully, the latest amount of that string name is loaded and becomes the latest variable of this effect. If no string could be found, the Source Fail Back Value is used for start up, so 0. Indeed, the first User Data in the chain of effect always uses it because Source Key couldn't recall anything that never existed before.
2. The amount is operated with the actual amount of this effect (or the Failback value if failed to load key) and the operation, leading to a final variable.
3. That variable (final amount) is being proceeded toward Validate Max / Validate Min. This will only tell which of the Effect Success/Failure is chosen.
4. That variable is registered with the name of the Key, which is the finality of the effect; A child effect can be read from it by recalling it with a Source Key field named as such.

[Source Key] -> [Amount + Operation] -> [Validate Max/Min] -> [Effect Success or Failure] -> [Key].

### Hint

When testing, use a buff behavior on the unit that is affected by the user data and set the life armor bonus based on an accumulator that checks out the User Data value of the specific "key". With this method, you can monitor the current amount (that's not invisible anymore!).

## Fields Description

### None - Amount

The amount that is used to modify the value. By default is +1. Since the first User Data automaticaly uses the Failback value of 0, running this effect starts at 0 (failback value) + 1 (amount)

### None - Behavior Scope

Allows modders to specify a behavior on a given unit in the effect tree.

* As long as a behavior is specified, the effect/validator/accumulator will store/load user data from the given behavior instead of from the current effect tree.

### None - EffectFailure

If the value is equal or greater than ValidateMax or less than ValidateMin then this effect is executed.

### None - EffectSuccess

If the value is less than ValidateMax and also greater than ValidateMin then this effect is executed.

### None - Key

Closes up the effect, registering its numeric result and naming it with the String name.

* If left empty, the EffectSuccess will never occur since this effect has no "identity". It is one thing to recall it later, but it can invalidate itself at creation if left blank.

### None - Operation

Operates the current value of the effect. This value is this "unseen" number that either starts from Failback value, either is the loaded with the Source Key system retrieving previous keys.

### None - Source Fail Back Value

At the very moment that **Source Key** fails to recall/load a previous value, this amount becomes the variable number that will be operated by the effect.

Example: Putting 10 (with amount field +1 by default) in this field means that proceeding this User Data will add +1 amount to it. Effect Success awaits only if Validate Max equals 11 or greater.

### None - Source Key

Value of a previous Key (from a parent effect User Data Effect), which a numeric value. If nothing is found, Source Fail Back value is the latest value that will be operated in this effect.

### None - ValidateMax

Maximum value allowed for EffectSuccess to take place.

* Setting to -1 is not considered as "any values" is accepted. It is in fact a maximum oriented in negative.

### None - ValidateMin

Minimum value allowed for EffectSuccess to take place.