🔵 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.

🔧 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.

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.

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.

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.

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.

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.

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:

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.

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).

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.

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.

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:

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.

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]

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.

cost:
    enabled: true
    currency: pp
    amount: 5000

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

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.

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.

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.

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

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

##########################################################################
#
#                         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"

PreviousStations Next🔧 Repair

Last updated 3 months ago

hashtag🔧 How Upgrading Works

hashtag🔑 Permission

hashtag1. Material Item

hashtag2. Protection Item

hashtag3. Chance Item

hashtag4. Upgrade Case

hashtag4.1 Decay-Level-Upgrade

hashtag4.2 Custom-Level-Upgrade

hashtagMin-downgrade-level

hashtag⚙ Configuration Format

hashtag🧩 How It Works

hashtagDowngrade Rate

hashtag📉 Downgrade Chance

hashtag4.3 Chance-Formula

hashtag5. Material Formula

hashtag6. Random Stat Upgrade

hashtag7. Give Random Stats

hashtag8. Destroy Item When Fail

hashtag9. Action When Success

hashtag10. Cost

hashtag11. Default Chance

hashtag12. Tiers

hashtag13. Default Template

hashtag14. Upgrade Fail Point

hashtag🔄 How It Works

hashtag⚙ Configuration

hashtagExample

hashtag📘 Rule Format

hashtag🧠 Rule Priority

hashtag✅ Benefits

🔧 How Upgrading Works

🔑 Permission

1. Material Item

2. Protection Item

3. Chance Item

4. Upgrade Case

4.1 Decay-Level-Upgrade

4.2 Custom-Level-Upgrade

Min-downgrade-level

⚙ Configuration Format

🧩 How It Works

Downgrade Rate

📉 Downgrade Chance

4.3 Chance-Formula

5. Material Formula

6. Random Stat Upgrade

7. Give Random Stats

8. Destroy Item When Fail

9. Action When Success

10. Cost

11. Default Chance

12. Tiers

13. Default Template

14. Upgrade Fail Point

🔄 How It Works

⚙ Configuration

Example

📘 Rule Format

🧠 Rule Priority

✅ Benefits