# π Gem Add Socket
***
The Gem Add Socket feature lets you add sockets to desired items, with customization options based on the available features.
Add Socket Gui
## π οΈ How Add Socket Works
When you place an item in the Item slot and press the Confirm button, a socket will be added to your item.
***
## π 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.
```yaml
settings:
permission: nwmmoupgrade.gem.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.
```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. 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
* match-item-tier
* match-item
***
### **3. Add Socket Case**
#### **3.1 Default Add Socket**
This method adds sockets to items up to a maximum defined by max-sockets for all items.
```yaml
default-add-socket:
socket-color: "Uncolored" #Default value is ANY, but if using a colored GEM STONE, that color will be the primary one.
max-sockets: 50
```
**#default**
```yaml
socket-color: "Uncolored"
```
**#random**
```yaml
socket-color:
- "Uncolored"
- "Red"
- "Blue"
- "Green"
```
***
#### **3.2 Tiers Add Socket**
This method checks the Tier of the item you're adding sockets to.\
If it matches any condition in the tier-list, items with that Tier will reference their max-sockets setting.\
You can add more than one Tier to the list.
```yaml
tiers:
enabled: false
no-tier-chance: 10
no-tier-max-sockets: 1
socket-color:
- "Uncolored"
- "Red"
- "Blue"
- "Green"
tier-list:
- tier: COMMON
chance: 2
max-sockets: 1
- tier: RARE
chance: 15
max-sockets: 1
```
***
### **4. 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 higher-level upgrades demand a greater investment from players.
**In Short:**\
Level Up = Material Requirements.
#### **Formula Configuration**
The core lies in the `formula` field, where you can define mathematical expressions.
```yaml
material-formula:
enabled: true
formula: "1"
```
***
### **5. Cost**
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: "{global_custom_advance_cost_item}"
```
```yaml
cost:
enabled: true # Enable/disable cost system
amount: 100
```
***
### **6. 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
```
***
### **7. Tiers**
This feature allows you to set the success chance based on the tiers of the item placed in the item slot.
```yaml
options:
....
tiers:
enabled: false
no-tier-chance: 10
no-tier-max-sockets: 1
socket-color:
- "Uncolored"
- "Red"
- "Blue"
- "Green"
tier-list:
- tier: COMMON
chance: 2
max-sockets: 1
- tier: RARE
chance: 15
max-sockets: 1
```
***
### **8. Remove Durability When Fail**
If you fail to add a socket, your item's durability will be completely removed.
```yaml
remove-durability-when-fail:
enabled: true
```
***
### **9. Destroy Item When Fail**
If an item upgrade fails, the item will be replaced with a predefined material.
```yaml
destroy-item-when-fail:
enabled: false
item-return:
type: MATERIAL
id: STEEL_INGOT
amount: 1
```
***
### **10. Match item socket color**
The **`match-item-socket-color`** feature allows you to control **socket creation behavior** based on the item being upgraded.
When a socket is added to an item, the plugin will check the configured rules and **apply the socket settings** that match the itemβs type, ID, and tier.
***
#### β Configuration Example
```yml
match-item-socket-color:
enabled: true
lists:
- SWORD;KATANA;4;ultra_red
- SWORD;;3;Yellow;COMMON,RARE,LEGENDARY
- SWORD;;2;Red
- armor;;1;Blue
```
***
#### π Rule Format
Each entry in `lists` follows this format:
```
;;;;
```
**Parameters**
* **`type`**\
Item type (e.g. `SWORD`, `armor`)
* **`id`** *(optional)*\
MMOItem ID\
Leave empty to apply the rule to all items of this type
* **`empty_socket`**\
Number of empty sockets to add
* **`color`**\
Socket color to apply (e.g. `Red`, `Blue`, `Yellow`, `ultra_red`)
* **`tier`** *(optional)*\
Item tiers this rule applies to\
If not specified, the rule applies to **all tiers**
***
#### π Matching Logic & Priority
* Rules are evaluated from **top to bottom**
* More **specific rules** (type + ID + tier) take priority
* Less specific rules act as **fallbacks**
This allows you to define detailed behavior while keeping a simple default setup.
***
#### π§ How It Works
When a socket is added:
1. The plugin checks if `match-item-socket-color` is enabled
2. It scans the `lists` for a matching rule
3. The first matching rule is applied
4. The socket is created with the configured **amount** and **color**
