Item Upgrading

Item upgrades are a way of adding some progression to your items. When successfully upgrading an item, its item statistics are increased which essentially makes the item better. Players can upgrade their items either using the right consumable, or by using a station upgrading recipe.
When upgraded, items gain one level. The level is displayed next to the item display name. The display name suffix can be changed in the main plugin config file (item-upgrading.name-suffix). Make sure your item has a custom display name, otherwise the suffix with not show up.

upgrading recipe

Setting up the upgrading template

The upgrade templates can be setup in the upgrade-templates.yml config file. This step is pretty straight forward but might require a bit of time to spend in the configs balancing your upgrading setup. Open your templates config file:

# Template ID, only used as reference. This is the
# text you need to enter in the edition GUI in order
# to setup item upgrading for a specific item.
weapon-default:

    # Every time the item is upgraded, its attack damage
    # is increased by 3% (relative to the current value)
    attack-damage: 3%
    
    # Every time it is upgraded, it gets +2% aboslute 
    # critical strike chance (independant of current val.)
    critical-strike-chance: 2
    
    pve-damage: 1%

armor-template-example:
    armor: 3%
    armor-toughness: 2%
    block-rating: 5%
    dodge-rating: 5%
    parry-rating: 5%

Every configuration section in that config file corresponds to one upgrading template. You can add as many templates as you like, you may even add one per item (although multiple items may have the same upgrading template). Once setup, you will be able to bind these templates to specific items to determine how they behave when they are upgraded. Let's try to read what the config says step by step.

weapon-template-example: This is an upgrading template example for weapons. Every item upgrade, the weapon will 3% of its current attack damage (meaning his current attack damage will be multiplied by 1.03), because the input ends with %. Every item upgrade, the weapon also gains 2% critical strike chance (not relative to its current critical strike chance, but since crit strike chance is in %, the item still gains 2% crit chance), as well as 1% PvE damage, relative to its current attack speed.

armor-default: When upgraded, an item with this upgrade template will gain 3% armor, 2% toughness, 5% block, dodge and parry rating, relative to its current stats since there is a %.

The % specified in the upgrade template does not have anything to do with the stat itself. It only means that the stat value gained by the item when upgrading is relative to the stat value that the previously item had. For instance, for a 8 Atk. Damage sword, gaining 3% attack damage (relative) isn't the same as gaining 3 attack damage (absolute).

Let's have a look at another example. Let's say we have a sword with 10 Attack Damage being upgraded, bound to the weapon-default upgrade template. This sword will thus gain 3% of its current damage, so at the end it will have 10 + (3% * 10) = 10 + 10 * 0.03 = 10.3 Atk. Damage, as well as 2% Crit Chance since it didn't have any before, and since the crit chance earned per upgrade is independant of the current stat value. The sword does not have any PvE damage, so gaining 1% PvE damage relative to its current value doesn't increase the PvE damage, since 1% of 0 is still 0.

Currently, item upgrading only applies for numeric stats like crit chance, attack damage, armor, PvE damage, etc.

Setting up the upgrading options for the consumable

Players may use a consumable in order to upgrade an item. If so, you need to specify two options: the upgrading reference, which we will get back to later, and the upgrade chance. You can configurate both of these options in the edition menu.

Setting up the upgrading options for the weapon/armor/...

Any item, including armors, weapons, etc. can be upgraded, however you need a few options set up in order to upgrade an item. Just like consumables, weapons/armors also have an upgrading chance. The upgrading chances of the weapon and the consumable stack, i.e total-upgrade-chance = <item-upgrade-chance> * <consumable-upgrade-chance>. If both items have a 40% upgrade chance, the total upgrade chance is 40% * 40% = 16%. When the item does not have 100% chance to be upgraded, you can enable an extra option which makes the item break when failing to upgrade it.

An item may also have a maximum amount of upgrades, meaning that once the item reaches a specific level, it cannot be upgraded anymore. This is an important option if you don't want specific items to get too OP with upgrades. An item can also be upgradable only via crafting stations and upgrading recipes.

Don't forget to bind an upgrading template to your item using the corresponding option in the edition GUI! Options described previously can also be setup using the item edition GUI.

Upgrade reference

This option can be used for both upgrading consumables and upgradable items. The upgrade reference dictates whether or not a specific consumable can upgrade an item.
There are only one rule and two exceptions: a consumable may only upgrade an item if its upgrade reference matches the reference of the upgraded item. If a consumable has no upgrade reference specified, it can upgrade any item. If an item has no upgrade reference, it can be upgraded by any consumables, unless you have the workbench-only option toggled on.

The upgrade reference is a piece of text which is not displayed in the item lore. It is only used internally to check if the two references match, therefore it could be anything, just make sure they match (just like the gem socket colors).