# 📘 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.

## ⚙️ 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. ```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-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. ```yaml material-formula: enabled: true formula: "1" ``` *** ### **4. Cost Upgrade** This feature allows you to use currencies such as PlayerPoints, CoinsEngine, or Vault. ```yaml cost: enabled: true currency: pp amount: 5000 ``` ```yaml cost: enabled: true # Enable/disable cost system currency: ce;nwcoin amount: "{ability_custom_advance_cost_item}" # cost amount ``` ```yaml 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. ```yaml 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. ```yaml 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. ```yaml 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:** ```yaml 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. ```yaml 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-Default Group" - "MMOITEM;MATERIAL;RARE_DIAMOND;10;display-{name} {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.

*** #### 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`. ```yaml actions: min-max-bility: - ;;;, 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;\;\;\ 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 `` in: ``` PLACEHOLDER;;; ``` This condition checks the value of a **placeholder** using a **comparison operator (``)** and compares it with a **result**. #### Available `` Options: | `` | 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: ```yaml - "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. ```yaml .... settings: .... options: use-ability-point: false ``` **Ability Points** are generated directly from **nwMMOUpgrade**, and you can view them using the **/mi browse** command.

*** ### **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, ```yaml 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: ```yaml 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**.

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.

*** ### **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. ```yaml 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: # ;; - 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\ \&#xNAN;**`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