# 🔵 Upgrade

The Upgrade feature allows you to enhance your items, making them significantly more effective by improving their stats. You have full control to customize the upgrade mechanics, including success rates, material requirements, and stat increases, through the plugin's configuration file to perfectly suit your server's design.

<figure><img src="https://1245303946-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEMKTTfYtO1c14jr3rkcH%2Fuploads%2F1BcoleaERmNrjRn0JikQ%2Fimage.png?alt=media&#x26;token=d17320d9-45f1-47f5-9758-c93cf3e833a0" alt="" width="523"><figcaption><p>Upgrade GUI</p></figcaption></figure>

## 🔧 How Upgrading Works

For an item to be eligible for an upgrade using **nwMMOUpgrade**, it must first be assigned an **Upgrade-Template**.

This template dictates the specific upgrade path and potential stat progressions for that particular item.

The plugin will reference the stats and upgrade rules defined within the Upgrade-Template that the item possesses.\
If an item does not have an Upgrade-Template applied to it, **it cannot be processed by the upgrade system.**

***

## 🔑 Permission

Each station has its own permission requirement in order to be used.\
You can customize or change the permission to suit your needs.

```yaml
settings:
  permission: nwmmoupgrade.upgrade.sword
```

***

## 1. Material Item

🧱 **Material Requirement System**

If enabled, this means the operation of the station will require the specified materials in order to function as intended. You can define one or more material items, and the station will only execute if the player provides the required materials.

```yaml
materials:
  enabled: false
  items:
    - type: MATERIAL
      id: STEEL_INGOT
      amount: 5
      slot: 30
      #match-item-type: SWORD #filter option
      #match-tier-type: RARE #filter option
      #match-item:
      # - SWORD:KATANA
```

Note:\
type is the type of the MMOItem.\
id is the ID of the MMOItem.\
amount is the quantity of the material required.\
slot is the GUI slot where the material must be placed.

Options\
These are additional conditions that enhance material requirements:

* match-item-type: The material will only be accepted if the item placed in the item slot has the matching type specified here.
* match-item-tier: The material will only be accepted if the item placed in the item slot has the matching tier specified here.
* match-item: The material will only be accepted if the item placed in the item slot has the matching According to the item defined in match-item specified here.

***

## 2. Protection Item

🛡️ **Prevent Item Damage or Loss**

If enabled, this feature allows you to protect your item in cases where the upgrade settings include downgrade levels, item destruction, or other effects that may negatively impact the item. The protection item will act as a safeguard to prevent your item from being damaged or lost during these risky processes.

```yaml
protection-item:
  enabled: false
  items:
    - type: MATERIAL
      id: RARE_DIAMOND
      amount: 5
      slot: 34
      #match-item-type: SWORD #filter option
      #match-tier-type: RARE #filter option
      #match-item:
      # - SWORD:KATANA

    - type: MATERIAL
      id: SILVER_INGOT
      amount: 1
      slot: 34
      #match-item-type: ARMOR #filter option
      #match-tier-type: RARE #filter option
      #match-item:
      # - SWORD:KATANA
```

Note:\
type is the type of the MMOItem.\
id is the ID of the MMOItem.\
amount is the quantity of the material required.\
slot is the GUI slot where the material must be placed.

Options\
These are additional conditions that enhance material requirements:

* match-item-type: The material will only be accepted if the item placed in the item slot has the matching type specified here.
* match-item-tier: The material will only be accepted if the item placed in the item slot has the matching tier specified here.
* match-item: The material will only be accepted if the item placed in the item slot has the matching According to the item defined in match-item specified here.

***

## 3. Chance Item

🍀 **Extra Success Chance**

If enabled and used in conjunction with chance-based mechanics, the Chance Item provides an additional success rate boost on top of the existing base chance. This item acts as a support to increase the overall likelihood of success during actions such as upgrading.

```yaml
chance-item:
  enabled: false
  items:
    - type: MATERIAL
      id: RARE_DIAMOND
      amount: 5
      slot: 32
      chance: 50
      #match-item-type: SWORD #filter option
      #match-tier-type: RARE #filter option
      #match-item:
      # - SWORD:KATANA

    - type: MATERIAL
      id: SILVER_INGOT
      amount: 1
      slot: 32
      chance: 50
      #match-item-type: ARMOR #filter option
      #match-tier-type: RARE #filter option
      #match-item:
      # - SWORD:KATANA
```

Note:\
type is the type of the MMOItem.\
id is the ID of the MMOItem.\
amount is the quantity of the material required.\
slot is the GUI slot where the material must be placed.\
chance This sets the success chance for the Chance Item

Options\
These are additional conditions that enhance material requirements:

* match-item-type: The material will only be accepted if the item placed in the item slot has the matching type specified here.
* match-item-tier: The material will only be accepted if the item placed in the item slot has the matching tier specified here.
* match-item: The material will only be accepted if the item placed in the item slot has the matching According to the item defined in match-item specified here.

***

## 4. Upgrade Case

Upgrade operations are divided into two types:

***

### 4.1 Decay-Level-Upgrade

📉 **Success Rate Decreases Per Level**

This mode reduces the success chance as the item's level increases. You can customize settings such as the base success chance, minimum success chance, and the percentage reduction in success chance per level.

```yaml
decay-level-upgrade:
  enabled: true # Enable/disable decay success rates per item level
  keep-level-on-failure: true # Enable/disable keeping item level on failure
  base-success: 35.0 # Base success rate
  decay-per-level: 5.0 # Success rate decay per item level
  min-success: 10.0 # Minimum success rate
  min-downgrade-level:
      enabled: False
      amount: 1
```

***

### 4.2 Custom-Level-Upgrade

⚙️ **Define Success Rate Per Level**

This mode allows you to dynamically define the success chance for each item level. You can set a custom success chance for every individual level.

```yaml
custom-level-upgrade:
    enabled: false # Enable/disable custom success rates per item level
    allow-downgrade: false # Enable/disable item level downgrade on failure
    min-downgrade-level: 1 # Minimum downgrade level
    level-protect: [1,2,3,4,5] #can use 1 or 1-5 when allow-downgrade: true
    rates:
      1: 100 # Success rate at level 1
      2: 95 # Success rate at level 2
      "3-20": 25 # Success rate at levels 3 to 20
```

#### Min-downgrade-level

The **`min-downgrade-level`** system has been extended to provide more flexible and precise downgrade control during upgrade failures.

This enhancement allows you to define **downgrade behavior based on upgrade level ranges**, rather than using a single fixed value.

***

#### ⚙ Configuration Format

You can now configure `min-downgrade-level` using **level ranges**:

```yml
min-downgrade-level:
  "1-4": "0"
  "5-8": "1-2"
```

***

#### 🧩 How It Works

* The key (`"1-4"`, `"5-8"`) represents the **current upgrade level range**
* The value defines the **possible downgrade levels** when an upgrade fails

**Example**

* If an item fails between **level 1–4**, it will **not downgrade**
* If an item fails between **level 5–8**, it can downgrade by **1 to 2 levels**

This allows higher upgrade levels to carry greater risk while keeping early upgrades safer.

#### Downgrade  Rate

An additional option has been introduced to control **how often downgrades occur**.

```yml
downgrade-rate: 50
```

#### 📉 Downgrade Chance

* The value represents the **percentage chance** that a downgrade will happen on failure
* Example:\
  `downgrade-rate: 50` → **50% chance** to apply a downgrade when an upgrade fails
* If the downgrade does not trigger, the item will remain at its current level

***

### 4.3 Chance-Formula

🧮 **Use Custom Placeholder Formula**

This mode allows you to use a custom formula to calculate the success chance (Custom Placeholder).

```yaml
chance-formula:
      enabled: false # Enable/disable custom success rates per item level
      allow-downgrade: false # Enable/disable item level downgrade on failure
      min-downgrade-level: 1 # Minimum downgrade level
      chance: "1"
```

***

## 5. Material Formula

📈 **Dynamic Material Scaling Based on Level**

The Material Formula feature provides a highly flexible way to dynamically calculate the cost and material requirements for item upgrades, allowing them to scale with the item's level.

Cost & Material Increase\
When this feature is enabled (enabled: true), the quantity of material items required for an upgrade will increase as the item's level rises.\
This ensures that higher-level upgrades demand a greater investment from players, providing a more balanced progression.

The increase is determined by a custom formula you define, giving you precise control over the scaling.

In Short:\
Level Up = Material Requirements.

Formula Configuration\
The core of this feature lies in the formula field, where you can define a mathematical expression.

Basic: you can use the basic default chance calculation or create your own custom formula to control how the chance is calculated.

Custom Placeholders: The formula supports specific placeholders that will be replaced with dynamic values during calculation.

```yaml
material-formula:
  enabled: true
  formula: "1"
```

***

## 6. Random Stat Upgrade

🎲 When an upgrade is successful, a random stat from the item's template will be upgraded, rather than all stats present in the template.

```yaml
random-stat:
  enabled: false # Enable/disable
  amount: 1 #Amount Stat
```

***

## 7. Give Random Stats

🎁 The stats defined in the list will be randomly applied to your item when upgrading, based on the number set in amount. Each line should follow this format:

```yaml
give-random-stats:
   enabled: false
   amount: 3
   lists:
      - "ATTACK_DAMAGE;5-20;3;COMMON,RARE,LEGENDARY;SWORD"
      - "ATTACK_SPEED;1-10;3;COMMON,RARE"
      - "WEAPON_DAMAGE;10-30;3;RARE,LEGENDARY;SWORD"
      - "PVE_DAMAGE;7-15;3;RARE"
      - "DEFENSE;5-25;100;;SWORD,ARMOR;10"
```

Explanation of Each Part:\
The stats defined in the list will be randomly applied to your item when upgrading, based on the number set in amount. Each line should follow this format:

```
"ATTACK_DAMAGE;5-20;3;COMMON,RARE,LEGENDARY;SWORD,ARMOR;9"
```

Stat Name – The stat to apply to the item (e.g., ATTACK\_DAMAGE).\
Stat Value Range – The range of values to randomly choose from (e.g., 5-20).\
Chance – The success chance (as a percentage). Note: Chance Item does not affect this.\
Tier Filter – Only applies if the item's tier matches any listed here (e.g., COMMON,RARE,LEGENDARY).\
Type Filter – Only applies if the item's type matches this (e.g., SWORD).\
Type Level– Only applies if the item's Level matches this (e.g., 9).

***

## 8. Destroy Item When Fail

💥 If an item upgrade fails, the item will be replaced with a predefined material.

Important:\
If a Protection Item is used, the item will not be destroyed upon failure.

```yaml
destroy-item-when-fail:
  enabled: false
  level-protect: [] #can use 1 or 1-5
  destroy-chance: 1
  item-return:
    type: MATERIAL
    id: STEEL_INGOT
    amount: 1
```

***

## 9. Action When Success

When an upgrade is successful, you can define actions to be performed based on the item's level.

```
#placeholder {player_name} / {player} / {player_uuid} / {level} / {item_name}
#syntax [sound], [broadcast], [message], [console], [player]
```

```yaml
action-when-success:
  enabled: false
  level:
    1:
      - '[sound] BLOCK_ANVIL_USE'
      - '[broadcast] &7{player} กำลังทำให้ &f{item_name}&7 แข็งแกร่งขึ้น!'
      - '[message] &bพลังของ {item_name} เพิ่มขึ้นอีกระดับ! &e{level}'

    2-15:
      - '[sound] ENTITY_DRAGON_FIREBALL_EXPLODE'
      - '[console] execute console command "crate givekey %player_name% epic_upgrade_key 1"'
      - '[message] &6{player} ได้ปลดปล่อยพลังอันยิ่งใหญ่ของ &a{item_name}&6!'
```

***

## 10. Cost

💰This feature allows you to use currencies such as PlayerPoints, CoinsEngine, or Vault. If you want to use a currency other than Vault, you must specify it using the currency: option — for example: currency: pp for PlayerPoints, or currency: ce; for CoinsEngine. And it also supports using custom placeholders from the system itself.

```yaml
cost:
    enabled: true
    currency: pp
    amount: 5000
```

```yaml
cost:
    enabled: true
    currency: ce;nwcoin
    amount: "{upgrade_custom_upgrade_cost}"
```

```yaml
cost:
    enabled: true
    amount: 100
```

***

## 11. Default Chance

This feature allows you to set the success chance of this station yourself, in cases where Tier is not enabled.

```yaml
options:
    default-chance: 0
```

***

## 12. Tiers

This feature allows you to set the success chance based on the tiers of the item placed in the item slot. If the item's tier matches the specified tiers, the chance will be applied accordingly. If none of the tier conditions are met, the chance will be taken from the no-tier-chance setting.

```yaml
options:
    tiers:
      enabled: false
      no-tier-chance: 10
      tier-list:
        - tier: COMMON
          chance: 30
        - tier: RARE
          chance: 40
```

***

## 13. Default Template

This feature allows you to set a default template in case the item has never had a default template assigned before in the MMOItems system.

```yaml
default-template:
  enabled: false
    template:
      template: weapon-default
      max: 15
```

***

## 14. Upgrade Fail Point

The **`use-upgrade-fail-point`** feature adds a fail-stack style system using **`UPGRADE_FAIL_POINT`** to improve the upgrade experience.

When an upgrade attempt **fails**, the system will grant **UPGRADE\_FAIL\_POINT** based on your configuration. These points are **carried over** and can be used to increase the success chance of future upgrade attempts.

***

#### 🔄 How It Works

* When an upgrade **fails**, the player receives **UPGRADE\_FAIL\_POINT**
* The amount gained depends on the configured rules
* **UPGRADE\_FAIL\_POINT** is added to the **success chance** of the next upgrade attempt
* Fail points can accumulate up to a defined **maximum limit**

This system rewards persistence and reduces frustration from repeated failures.

***

### ⚙ Configuration

#### Example

```yml
use-upgrade-fail-point:
  enabled: true
  add-fail-point:
    - sword;KATANA;6;30;COMMON,RARE,LEGENDARY
    - sword;;5;30
    - armor;6;30;COMMON
    - armor;1;10
```

***

#### 📘 Rule Format

Each entry in `add-fail-point` follows this structure:

```
<type>;<id>;<upgrade_fail_point>;<max_upgrade_fail_point>;<tier>
```

**Parameters**

* **`type`**\
  Item category (e.g. `sword`, `armor`)
* **`id`** *(optional)*\
  MMOItem ID\
  Leave empty to apply to all items of the given type
* **`upgrade_fail_point`**\
  Amount of fail points gained when an upgrade fails
* **`max_upgrade_fail_point`**\
  Maximum fail points that can be accumulated
* **`tier`** *(optional)*\
  Item tiers this rule applies to (e.g. `COMMON`, `RARE`, `LEGENDARY`)\
  If not specified, the rule applies to **all tiers**

***

#### 🧠 Rule Priority

* Rules with **more specific filters** (type + ID + tier) are applied first
* More general rules act as **fallbacks**
* This allows fine-grained control while keeping configurations flexible

***

#### ✅ Benefits

* Reduces frustration from repeated upgrade failures
* Encourages continued upgrading
* Fully configurable per item type, ID, and tier
* Optional and backward compatible

***

**Example Full Config**

```yaml
##########################################################################
#
#                         nwMMOUpgrade - Upgrade
#      Created By Discord NN#7999 (Newworld Server)
#
#      Supports RGB and standard color codes.
#      1.RGB = &#ffffff
#      2.Standard = &f
#      3. MiniMessage = <red>
#      4. Legacy Hex = &x
#      https://www.birdflop.com/resources/rgb/
#
##########################################################################


#Contact&Support: https://discord.gg/gwXcr7c6Gq

# MMOItems Type for this menu
applies-to:
  - SWORD

# Sound settings
# https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html
sounds:
  confirm-success: ENTITY_EXPERIENCE_ORB_PICKUP # Sound on successful upgrade
  confirm-fail: BLOCK_ANVIL_DESTROY # Sound on failed upgrade
  confirm-no-item: BLOCK_NOTE_BLOCK_PLING # Sound when confirming with no item

# GUI customization
gui:
  title: "&bSword Upgrade Station" # GUI title
  rows: 6 # GUI rows (1-6)
  display-slots:
    item:
      material: LIME_STAINED_GLASS_PANE
      name: "<color:#00FF4F>Place the item to upgrade<color:#57E342>"
      lore:
        - "&7Drag and drop your item here"
      cmd: 1
    material:
      material: YELLOW_STAINED_GLASS_PANE
      name: "<color:#E7FF00>Place the materials<color:#F2FF08>"
      lore:
        - "&7Drag and drop the required materials here"
      cmd: 1
    chance:
      material: PINK_STAINED_GLASS_PANE
      name: "<color:#FF00F8>Place a chance-enhancing stone (if any)<color:#E68DFF>"
      lore:
        - "&7Drag and drop the chance-enhancing stone here"
      cmd: 1
    protection:
      material: BLUE_STAINED_GLASS_PANE
      name: "<color:#FF00F8>Place a protection stone (if any)<color:#E68DFF>"
      lore:
        - "&7Drag and drop the protection stone here"
      cmd: 1
  slots:
    item: 13 # Slot for the item to upgrade
    confirm:
      material: GREEN_STAINED_GLASS_PANE # Confirm button material
      name: "&a&lConfirm Upgrade" # Confirm button name
      lore: # Confirm button lore
        - "&7Click to upgrade"
        - ""
        - "&fCost: &a{cost}"
        - "&fSuccess Chance: &6{chance}%"
        - "&fMaterials:"
        - "{material}"
      slot: 40 # Confirm button slot
      cmd: 1 # Custom Model Data (if any)
    filter:
      name: "&f" # Filter name (not displayed)
      material: BLACK_STAINED_GLASS_PANE # Filter material
      cmd: 1 # Custom Model Data (if any)


materials:
  enabled: false
  items:
    - type: MATERIAL
      id: STEEL_INGOT
      amount: 5
      slot: 30
      match-item-type: SWORD #filter option
      #match-tier-type: RARE #filter option
    # - type: MATERIAL
    #   id: FIRE_ESSENCE
    #   amount: 5
    #   slot: 31
    #   match-item-type: SWORD #filter option

chance-item:
  enabled: false
  items:
    - type: MATERIAL
      id: RARE_DIAMOND
      amount: 5
      slot: 32
      chance: 50
      match-item-type: SWORD #filter option
      # match-tier-type: RARE #filter option
    - type: MATERIAL
      id: SILVER_INGOT
      amount: 1
      slot: 32
      chance: 50
      # match-item-type: ARMOR #filter option
      # match-tier-type: RARE #filter option

protection-item:
  enabled: false
  items:
    - type: MATERIAL
      id: RARE_DIAMOND
      amount: 5
      slot: 34
      match-item-type: SWORD #filter option
      # match-tier-type: RARE #filter option
    - type: MATERIAL
      id: SILVER_INGOT
      amount: 1
      slot: 34
      match-item-type: ARMOR #filter option
      # match-tier-type: RARE #filter option

settings:
  permission: nwmmoupgrade.upgrade.sword
  close-gui-when-not-confirm: false
  default-template:
    enabled: false
    template:
      template: weapon-default
      max: 15
  #cost settings
  cost:
    enabled: false # Enable/disable upgrade cost system
    amount: "{upgrade_custom_upgrade_cost}" # Upgrade cost amount
  options:
    default-chance: 0
    tiers:
      enabled: false
      no-tier-chance: 10
      tier-list:
        - tier: COMMON
          chance: 30
        - tier: RARE
          chance: 40

    #Material Increase:
    # - When enabled, both upgrade material needs rise with the item's level.
    # - This increase is based on a set formula.
    #In short:
    # - Level up = higher material.
    material-formula:
      enabled: false
      formula: "{upgrade_custom_default_custom_formula}"

    random-stat:
      enabled: false
      amount: 1

    give-random-stats:
      enabled: false
      amount: 3
      lists:
         - "ATTACK_DAMAGE;5-20;3;COMMON,RARE,LEGENDARY;SWORD;1"
         - "ATTACK_SPEED;1-10;3;COMMON,RARE"
         - "WEAPON_DAMAGE;10-30;3;RARE,LEGENDARY;SWORD"
         - "PVE_DAMAGE;7-15;3;RARE"
         - "DEFENSE;5-25;100;;SWORD,ARMOR"

    destroy-item-when-fail:
      enabled: false
      level-protect: [1,2,3,4,5] #can use 1 or 1-5
      destroy-chance: 100
      item-return:
        type: MATERIAL # Item type (MATERIAL, MMOITEM)
        id: STEEL_INGOT # Item ID
        amount: 1

    #placeholder {player_name} / {player} / {player_uuid} / {level} / {item_name}
    #syntax [sound], [broadcast], [message], [console], [player]
    action-when-success:
      enabled: true
      level:
        1-7:
          - '[sound] BLOCK_ANVIL_USE'
          - '[broadcast] &7{player} กำลังทำให้ {item_name}&7 แข็งแกร่งขึ้น!'
          - '[message] &bพลังของ {item_name}เพิ่มขึ้นอีกระดับ! &e{level}'
        8-15:
          - '[sound] ENTITY_DRAGON_FIREBALL_EXPLODE'
          - '[console] mi give MATERIAL RARE_DIAMOND {player} 1'
          - '[message] &6{player} <color:#eb933c>ได้ปลดปล่อยพลังอันยิ่งใหญ่ของ &a{item_name}&6!'

    # Case 1: Default Upgrade Behavior
    # This is the standard or default configuration for upgrades.

    # Case 2: Custom Level Upgrade (When custom-level-upgrade: true)
    # If you opt to use the custom level upgrade system by setting custom-level-upgrade to true,
    # then the allow-downgrade feature will become active and effectively replace keep-level-on-failure.
    # To ensure this works correctly, you should set keep-level-on-failure
    # to false and explicitly enable allow-downgrade by setting it to true.

    #case 1 #default
    decay-level-upgrade:
      enabled: true # Enable/disable decay success rates per item level
      keep-level-on-failure: false # Enable/disable keeping item level on failure
      base-success: 35.0 # Base success rate
      decay-per-level: 5.0 # Success rate decay per item level
      min-success: 10.0 # Minimum success rate
      min-downgrade-level:
        enabled: false
        amount: 1

    #case 2
    custom-level-upgrade:
      enabled: false # Enable/disable custom success rates per item level
      allow-downgrade: false # Enable/disable item level downgrade on failure
      min-downgrade-level: 1 # Minimum downgrade level
      level-protect: [1,2,3,4,5] #can use 1 or 1-5 enabled when allow-downgrade = true
      rates:
        1: 100 # Success rate at level 1
        2: 95 # Success rate at level 2
        "3-20": 80 # Success rate at levels 3 to 20

    #case 3
    chance-formula:
      enabled: false # Enable/disable custom success rates per item level
      allow-downgrade: false # Enable/disable item level downgrade on failure
      min-downgrade-level: 1 # Minimum downgrade level
      chance: "1"


```