📘 Ability

---

The Ability Station allows items that have abilities to be modified by increasing or decreasing the stats related to those abilities. It also allows you to add or remove abilities from the item.

Ability GUI

⚙️ How Ability Works

When placing an item with abilities into the item slot, if the item has more than one ability, you will be able to select which ability you want to modify the stats for.

By default, left-click is used to increase the value, and right-click is used to decrease it. These controls can be configured in the config file.

🔐 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.ability.upgrade-ability

---

⭐ 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
      #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. 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
      #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-tier: 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. Material Formula

The Material Formula feature provides a highly flexible way to dynamically calculate the cost and material requirements for item.

Material Increase

When this feature is enabled (enabled: true), the quantity of material items required for an gem add socket 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"

---

4. Cost Upgrade

This feature allows you to use currencies such as PlayerPoints, CoinsEngine, or Vault.

cost:
    enabled: true
    currency: pp
    amount: 5000

cost:
    enabled: true # Enable/disable cost system
    currency: ce;nwcoin
    amount: "{ability_custom_advance_cost_item}" # cost amount

cost:
    enabled: true # Enable/disable cost system
    amount: 100 # cost amount

---

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

---

6. 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: 2
        - tier: RARE
          chance: 15

---

7. Ability Display

It is an important part of configuring the Ability display in the GUI, where you can define which items should appear. For example, ability-items is used to specify the slots that will display the Abilities and also the slots where Abilities can be inserted.

ability-display:
  ability-items:
    slots: [28,29,30,31,32,33,34]
    display-item:
      material: DIAMOND
      name: "&a&lAbility {name}"
      lore:
        - "&7Descriptions"
      cmd: 2601
    add-ability:
      material: DIAMOND
      name: "&a&lAdded Ability"
      lore:
        - "&7Select Ability"
      cmd: 2601

condition-for-add-ability

This feature is used with add-ability to restrict which triggers are allowed in each add-ability slot.

• Each slot can only accept specific triggers

• Must match the add-ability slots: slots: [28,29,30,31,32,33,34]

Example:

add-ability:
  material: DIAMOND
  name: "&a&lAdded Ability"
  lore:
    - "&7Select Ability"
    - "&7Trigger 1: {condition_target_1}"
    - "&7Trigger 2: {condition_target_2}"
  cmd: 2601
  msg-no-condition: "&cYou must have a condition to add an ability"
  condition-for-add-ability:
    1:
      slot: 28
      trigger:
        - "left_click"
    2:
      slot: 29
      trigger:
        - "right_click"

---

This section defines the display item for the various ability stats that can be increased or decreased.It also defines the actions related to how much the value will be increased or decreased, based on the specified settings.

ability-display:
  ability-items:
    .....
  items:
    timer: <-- various ability stats
      display-item:
        material: COAL
        name: "&a&lTimer &f{amount}"
        lore:
          - "&aPoint: {point}"
          - "&7Timer: &f{amount}"
          - "&fCost: &a{cost}"
          - "&fSuccess Chance: &6{chance}%"
          - "&fMaterials:"
          - "{material}"
          - "{requirements}"
        slots:
          - 37
        cmd: 0
      actions: <-- actions when click
        left-click:
          amount: 1
        right-click:
          amount: 1
      required-items: <-- required
        - "PLACEHOLDER;%luckperms_groups%;==;default;display-<red>Default Group"
        - "MMOITEM;MATERIAL;RARE_DIAMOND;10;display-<white>{name} <red>{amount}ea"
        - "vault;123;display-&fCost: &#FCFF00{amount}"
        - "VANILLA;STONE;15"

---

Various Ability Stats

Various ability stats" are the values of ability stats that the player must define if they want them to be displayed on the GUI of the Ability Station, based on what has been defined in the ability from MMOItem.

Ability Edition

---

Actions

This defines how the various ability stats of an item are increased or decreased.

• Left-click is used to increase the value. You can set how much to increase by specifying the value in amount.

• Right-click is used to decrease the value. You can set how much to decrease by specifying the value in amount.

actions:
  min-max-bility:
    - <ABILITY_ID>;<min>;<max>;<tier>,<tier1>
  left-click:
    amount: 1
  right-click:
    amount: 1

The min-max-ability feature allows each ability_id to define its own minimum and maximum values.

This provides more control over how abilities behave, making it possible to enforce limits per ability instead of relying on global rules.

---

✨ Key Features

• Define minimum and maximum values per ability_id

• Optional item tier filtering

• Min/Max checks can change depending on the tier of the item

• Fully backward compatible

---

🔍 Tier-Based Filtering (Optional)

When an item tier is specified:

• The system will apply different min/max limits based on the item's tier

• This allows higher-tier items to have higher (or different) ability limits

If no tier filter is defined:

• The min/max values will apply globally to all items using that ability

---

⚙ Default Behavior

If min-max-ability is not configured:

• The system will behave exactly the same as before

• No additional checks or restrictions will be applied

This ensures existing setups continue to work without any changes.

---

✅ Benefits

• Fine-grained control over individual abilities

• Better balance across different item tiers

• Prevents abilities from exceeding intended limits

• Safe to enable on existing servers

---

Required-Items

Required Item are the results that players receive when the process is successfully completed.

Here is a table of condition types and their formats:

Type	Format	Example	Description
MMOItems	MMOITEM;<type>;<id>;<amount>	MMOITEM;MATERIAL;RARE_DIAMOND;10	Requires a specific MMOItem and amount
Vanilla	VANILLA;<material>;<amount>	VANILLA;STONE;15	Requires a specific vanilla item and amount
Placeholder	PLACEHOLDER;<placeholder>;<syntax>;<result>	PLACEHOLDER;%luckperms_groups%;==;default	Checks placeholder value matches result
Vault	vault;<amount>	vault;123	Requires the player to have a certain amount of money
Level	LEVEL;<amount>	LEVEL;123	Requires the player to have a certain level
CoinsEngine	COINSENGINE;<currency>;<amount>	COINSENGINE;nwcoin;100	Requires the player to have a certain amount of money
PlayerPoint	playerpoint;<amount>	playerpoint;100	Requires the player to have a certain amount of money
Nexo	nexo;<material>;<amount>	Nexo;Custom_block;15	Requires a specific nexo item and amount
ItemsAdder	ia;<namespace>;<amount>	ia;<test:test>;1	Requires a specific ItemsAdder item and amount

These conditions give you a flexible way to control when a player is allowed to process items.

Condition Syntax

PLACEHOLDER;<placeholder>;<syntax>;<result>

Available syntax options include:

Examples:

• "PLACEHOLDER;%player_level%;>=;30"

• "PLACEHOLDER;%luckperms_group%;==;vip"

• "PLACEHOLDER;%player_health%;<;10"

• "PLACEHOLDER;%some_placeholder%;has_value"

These conditions give you a flexible way to control when a player is allowed to process items.

Here's an explanation in simple English of how to use <syntax> in:

PLACEHOLDER;<placeholder>;<syntax>;<result>

This condition checks the value of a placeholder using a comparison operator (<syntax>) and compares it with a result.

Available <syntax> Options:

<syntax>	Meaning	Example	Description
== (EQUALS)	Equals	%player_level% == 10	True if the placeholder equals 10
!= (NOT_EQUALS)	Not equals	%player_level% != 5	True if not equal to 5
> (GREATER_THAN)	Greater than	%player_level% > 20	True if greater than 20
< (LESS_THAN)	Less than	%player_level% < 15	True if less than 15
>= (GREATER_OR_EQUAL)	Greater than or equal	%player_level% >= 30	True if 30 or more
<= (LESS_OR_EQUAL)	Less than or equal	%player_level% <= 50	True if 50 or less
has_value (HAS_VALUE)	Check if has any value	%some_placeholder% has_value	True if the placeholder is not empty or null

Example Usages:

- "PLACEHOLDER;%player_level%;>=;30"
- "PLACEHOLDER;%luckperms_group%;==;vip"
- "PLACEHOLDER;%player_health%;<;10"
- "PLACEHOLDER;%some_placeholder%;has_value"

---

8. Use Ability Point

If use-ability-point is enabled, the increase and decrease actions will be based on the ability points available in the item.

• When left-clicking to increase a various ability stat, 1 ability point will be consumed.

• When right-clicking to decrease a various ability stat, 1 ability point will be restored.

....
settings:
  ....
  options:
    use-ability-point: false

Ability Points are generated directly from nwMMOUpgrade, and you can view them using the /mi browse command.

Ability Point

---

9. Add Ability In Item

When added-ability-in-item is enabled, players can add Abilities to their own items. To do this, you must first define the slots where items containing Abilities can be placed, using the can-add-ability setting. Additionally,

settings:
  ....
  options:
    ....
    added-ability-in-item:
      enabled: true
      can-add-ability: 3
      mmoitem-item-type-can-added-ability: ABILITY_ITEM

the slots where Abilities are displayed must be defined using the ability-display configuration:

ability-items:
  slots: [28, 29, 30, 31, 32, 33, 34]

Here's an example of how it works: If you define 7 slots in total and the item already has 4 Abilities, those 4 Abilities will be shown as available for customization. The remaining 3 slots can be used to insert items that contain additional Abilities, based on the 3 slots defined in can-add-ability.

Added Ability

Next, the item to be placed must be defined using mmoitem-item-type-can-added-ability. It’s recommended to create a separate MMOItem type specifically for adding Abilities to your items, to make the process easier.

The method is simple: just drag and drop the item into the Added Ability slot. Once completed, the Ability will be added to your item.

The item type defined in mmoitem-item-type-can-added-ability must contain exactly one Ability — if it has more than one, the process will not work.

Drag an Drop

---

11. Remove Ability In Item

The remove-ability-in-item feature allows players to remove an Ability from an item. When enabled, players can drag and drop a designated item onto the Ability they want to remove. Once removed, the Ability will immediately disappear from the item.

However, if players want to keep the Ability after removing it from the item, they can enable the keep-ability: true setting.

settings:
  ....
  options:
    .....
    remove-ability-in-item:
      enabled: true
      keep-ability: true
      mmoitem-item:
        type: ABILITY_ITEM
        id: SCROLL_REMOVE
    remove-item-match-id-mmoitem: #required keep-ability: true
        enabled: false
        mmoitem-category-type: ABILITY_ITEM #category type of mmoitem
        filter-ability-match-id-mmoitem:
          # <ability>;<type>;<id>
          - HUMAN_SHIELD;ABILITY_ITEM;HUMAN_SHIELD_ABILITY_RUNE
          - FIRE_DRADON_ABILITY;ABILITY_ITEM;FIRE_DRADON_ABILITY_RUNE

remove-item-match-id-mmoitem A new feature has been added to improve how skills are removed from items and how the original item is returned.

🔄 How It Works

When a skill is removed using this feature:

• The removal item will be consumed

• The system will return the original item that had the skill applied

• The modified (skilled) item will not remain

This ensures a clean and accurate rollback of the item state.

🔍 Item Matching Logic

The system determines which item to return using the following priority order:

1️⃣ Primary Filter (Type Match)

• If an item in the target category has a type name that matches the Ability ID, that item will be immediately returned.

2️⃣ Secondary Filter (Ability Match)

• If no type match is found, the system will use filter-ability-match-id-mmoitem to identify and return the correct item.

• filter-ability-match-id-mmoitem

  Added support for removing abilities from items by defining the ability to be removed inside the item itself, and requiring them to match.

  Example:

  Ability_1,Ability_2,Ability_3,Ability_4,Ability_5,Ability_6;MATERIAL;GEM_ABILITY

3️⃣ Fallback Behavior

• If no matching item is found using either filter:

  • The system will fall back to the default behavior

  • The removed skill will be added back into the original item

✅ Benefits

• Prevents leftover or duplicated skilled items

• Ensures the correct original item is always returned

• Provides a safer and more predictable skill removal process