Data/Upgrades

* To manipulate a units damage you have to modify the weapon it is using, not the unit itself.
* To edit the text of a button, it is essential to have a replacement button availlable so that its "Text Key" may be used (value used to swap the text). Modifying the text itself will not work and will in fact erase the button's current text, causing further mess in data. It is also recommanded to use the XML view for an easier manipulation of text keys.

## Example Usage

### Upgrading with triggers

To apply an upgrade using triggers, use the action "Set Upgrade Level For Player". The Upgrade parameter will define which Upgrade will be applied. The level will define how many times the Upgrade will be stacked and the player is the player number. Most upgrades may only be stacked 1 time, but this value can be modified.

## Fields Description

### Affected Unit Array

An array with all the Unit Types which will be affected by this upgrade. When an upgrade is applied, any units matching the unit types listed here will be notified that their upgrades have changed. This sends an **Upgrade** actor message.

To have your Upgrade actually affect game data, you need to configure the Upgrade: Effects fields. At basis, this field shouldn't affect data, but it kind of does in particular situations:

1. This field is an absolute necessity if one is to use an "Upgrade" event in actors. Be aware that this type of Msg Type is bugged, may sometimes work, sometimes not if the Affected Unit Array field does not contain the unit's actor in its list. Simply imput the unit that owns the actor, from which "Upgrade" Msg type must end up successful.
2. Enabling/Disabling some weapon fields, such as "Enabled" (option). A test shown that creating a weapon that's disabled for start, but required an upgrade to swap it wouldn't work without the concerned unit using the weapon to be in this field. This was tested with the Psionic Storm Upgrade, it has however, not been tested with any other upgrades. This is still a knowledge that may be useful for unbugging.

### Alert

* Sound alert from the Alerts data type that occurs when the upgrade is complete.

### (None): Data Collection

Since some upgrades are designed to work for “all units” (of a certain type), the CUpgrade has this flag to enumerate all Data Collection Units.

### (None): Bonus Resource Per Level

Amount of resource that will be added or removed upon selecting the upgrade.

* This takes effect at the moment an upgrade is clicked and sent to queue (think of it as "Queued or better").
* Works with the logic of the **Max Level** field being higher than 1.
* Will fallback (cancel) to the previous value if the selected upgrade is cancelled/removed from queue.
* Putting numbers in positive increases the cost, while putting them in negative decreases it.
* This field can be upgraded from upgrades (new feature)

### (None): Bonus Time Per Level

Amount of time that will be added or removed upon selecting the upgrade.

* This takes effect at the moment an upgrade is clicked and sent to queue (think of it as "Queued or better").
* Works with the logic of the **Max Level** field being higher than 1.
* Will fallback (cancel) to the previous value if the selected upgrade is cancelled/removed from queue.
* Putting numbers in positive increases the cost, while putting them in negative decreases it.
* This field can be upgraded from upgrades (new feature)

### (None): Level Button

Button that should appear according to the level of the upgrade and the array of the button(s) inserted in this field.

* Requires the Research Ability to have Smart Requirement flag enabled to work properly.

### (None): Level Requirement

Requirement that overides any current requirements using this upgrade, from any abilities using it. The requirement is inserted in the array, according to the current level of the upgrade.

Example use: An upgrade has 3 levels. Requirements from 0 to 2 are: (None/None/RequirementX). The requirement X is an impossible generic requirement that hides the button. What will happen is that the upgrade will be possible to queue 3 times, and will hide once the third one is selected.

* Requires the Research ability to use the Smart Flag: If not using the flag, setting a "Use" requirement that is impossible will prevent the related upgrade to be queue-able, until the previous upgrades are at least completed. This is most likely a bug, as the flag should be used in all situations.

### (None): Effect Array Template

This field is similar to the old EffectArray field with the following exceptions:

* It supports two additional tokens:
	+ **^ParamId^**: The Id of any data collection that uses the upgrade.
	+ **^ParamLevel^**: The current level of upgrade.
* It supports data references and use of arithmetic. Use brackets, “{“ and “}”, to create formulas as you would in the text editor.
* Data collections already encourage modders to name all related data with a specific naming convention, so modders can easily use ^ParamId^ for data entries related to the unit using them.
* For example:
	+ EffectArrayTemplate Reference="Effect,^ParamId^@Weapon,Amount" Value="{DataCollection,^ParamId^,UpgradeInfoWeapon.DamagePerLevel+3}"/
	+ This upgrade will increase the weapon damage amount of the unit it’s used on by the unit’s data collection’s UpgradeInfoWeapon.DamagePerLevel field plus three.
	+ You can put a fixed number into the value column, e.g., Value=”4”.

### Upgrade - Effects

* An array of resources that should be manipulated when the Upgrade is applied to a players Tech-tree.
* **Data Reference:** A list where the effects of the upgrade will be listed.
* **Data Type:** The type of resource that should be manipulated. The types available for manipulation are:
	+ Abilities
	+ Actors
	+ Behaviors
	+ Buttons
	+ Effects
	+ Game UI Value
	+ Item Containers
	+ Target Finds
	+ Units - armor, shield, movement speed
	+ Weapons - damage, weapon speed
* **Object:** A list of all available resources that can be manipulated, of the type specified in the Data Type field.
* **Field:** A list of all available resources that can be manipulated, of the type specified in the Data Type field.
* **Operation:** The method of manipulating values.

Patch 5.0 has added new operations: **AddBaseMultiply** and **SubtractBaseMultiply:** These operations modify the target field based on its default value instead of its current value, which is generally more useful than the Multiply operation. For example, if you have 100 levels of an “increase unit life by 10%” upgrade, you probably want this upgrade to increase life by a fixed number on each level rather than multiplied by the life of the last level every time. Also, Add/SubtractBaseMultiply supports tech downgrades because it can undo itself at any time, which Multiply cannot.

* **Value:** The new value that should be applied. The type of the value will depend on the resource data type.
* Do not use multiplication or division as operation, even though they are options.

### Enum Excluded User Flags

Allow upgrades to filter through all the data collection units based on their flags.

### Enum Required User Flags

Allow upgrades to filter through all the data collection units based on their flags.

### Flags

* **Cheat:** When checked, the upgrade will be enabled while using the cheat **IAmIronMan**.
* **Enum Data Collection Units:** Enumerate all Data Collection Units
* **Ignore Invalid Reference In Template:** (Unknown)
* **Tech Tree Cheat:** When enabled, the upgrade will be enabled while using the cheat **SoSayWeAll**.

### Leader Alias

* Alias used for the upgrade in the Leader Panel for spectators

### Leader Level

* Determines the number that appears on the upgrade icon in the leader panel for spectators, used for weapon / armor upgrades
* If upgrades have matching Leader Priority and Leader Alias the one with higher leader level will be shown.

### Leader Priority

* Determines the sorting priority that upgrades appear in the leader panel for spectators, if upgrades have matching priority and Leader Alias they will be combined.

### Max Level

* The maximum number of times the upgrade can be stacked. The default value is 1.
* The highest amount of levels should not be more then 100, even though it allows 255. It is buggy.

### Score Count

* Score category related to the Replay Upgrade tab.

### Score Result

* In which category of the ending Score Screen the upgrade will be shown. But practically, has no effect on custom upgrades/results different from Build Order.

### Score Value

* Score category related to the Score Screen tab.

### Tech Alias

* Alias for the Upgrade that can be used to link multiple upgrade in a Requirement Node.

### Tooltip Priority

* Tooltip priority to determinate it's position in alert section

### Unit Allowed

Enables the use of a unit. This works more directly, but with less precision on certain aspects than requirements (for example, you cannot set a text that stipulates what is required for producing this unit).

### Unit Disallowed

Disables the use of a unit. This works more directly, but with less precision on certain aspects than requirements.

## Related

* Research
* Requirements
* Modify Player