Upgrade

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.

Upgrade GUI

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. Of course, you can customize or change the permission to suit your needs.

settings:
  permission: nwmmoupgrade.upgrade.sword

Features

1. Material Item

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

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.

2. Protection Item

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
    - type: MATERIAL
      id: SILVER_INGOT
      amount: 1
      slot: 34
      #match-item-type: ARMOR #filter option
      #match-tier-type: RARE #filter option

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.

3. Chance Item

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
    - type: MATERIAL
      id: SILVER_INGOT
      amount: 1
      slot: 32
      chance: 50
      #match-item-type: ARMOR #filter option
      #match-tier-type: RARE #filter option

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.

4. Upgrade Case

Upgrade operations are divided into two types:

4.1 Decay-Level-Upgrade

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

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

4.3 Chance-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

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"

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"

  1. Stat Name – The stat to apply to the item (e.g., ATTACK_DAMAGE).

  2. Stat Value Range – The range of values to randomly choose from (e.g., 5-20).

  3. Chance – The success chance (as a percentage). Note: Chance Item does not affect this.

  4. Tier Filter – Only applies if the item's tier matches any listed here (e.g., COMMON,RARE,LEGENDARY).

  5. Type Filter – Only applies if the item's type matches this (e.g., SWORD).

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
  item-return:
    type: MATERIAL # Item type (MATERIAL, MMOITEM)
    id: STEEL_INGOT # Item ID
    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"' # ตัวอย่างการให้ crate key
      - '[message] &6{player} ได้ปลดปล่อยพลังอันยิ่งใหญ่ของ &a{item_name}&6!'

10. Cost Upgrade

This feature allows you to use Vault (Money) for each Upgrade addition. And it also supports using custom placeholders from the system itself.

cost:
    enabled: false #Cost
    amount: 5000
cost:
    enabled: true # Enable/disable upgrade cost system
    amount: "{upgrade_custom_upgrade_cost}" # Upgrade cost amount

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

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: "<white> </white>" # Filter name (not displayed)
      material: BLACK_STAINED_GLASS_PANE # Filter material
      cmd: 1 # Custom Model Data (if any)


materials:
  enabled: true
  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: true
  items:
    - type: ICON
      id: BAHAMUT_SWORD_ICON
      amount: 1
      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: true
  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: true # 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"
         - "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
      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
      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"
PreviousStationsNextRepair

Last updated