Upgrade Item Configuration
| Key | Type | Default | Description |
|---|---|---|---|
name |
text |
— | Display name of the book (use color codes). |
lore |
list |
— | List of lore lines shown in tooltip before applying. |
material |
MATERIAL_TYPE |
— | The item’s base material (e.g. ENCHANTED_BOOK). |
glow |
boolean |
false |
If true, adds the “enchanted glow” visual effect. |
custom-model-data |
int |
0 |
Custom model data in resource pack (set to 0 to disable). |
Enchantments
| Key | Type | Default | Description |
|---|---|---|---|
enchantments |
text |
— | List of enchantments to apply, formatted as <enchant> <level>:<max-level> (max-level optional). |
enchantments-conflict-check |
boolean |
false |
If true, prevents application of mutually exclusive enchants (e.g. Sharpness vs Smite). |
sum-existing-enchantments |
boolean |
false |
If true, adds levels to any existing identical enchantment on the target item. |
sum-existing-enchantments-like-in-vanilla |
boolean |
false |
If true mimics the vanilla book behavior: merging same-level enchants up to the higher vanilla cap (requires sum-existing-enchantments). |
Attributes & NBT
| Key | Type | Default | Description |
|---|---|---|---|
attributes |
list |
— |
List of attribute modifiers, format: (e.g. |
nbt-added-to-item-when-applied |
string |
'' |
Raw NBT tag(s) to add to the target item on successful application. |
needed-nbt-to-apply |
string |
'' |
Requires this NBT on the target item in order to allow application. |
needed-nbt-to-not-apply |
string |
'' |
If the target item has this NBT, application will be blocked. |
Application Rules
| Key | Type | Default | Description |
|---|---|---|---|
can-be-applied-to-damaged-item |
boolean |
true |
Allow application even if the target item is damaged. |
can-be-applied-to-unbreakable-item |
boolean |
true |
Allow application even if the target item is marked unbreakable. |
chance |
double |
100.0 |
Percentage chance of a successful application (e.g. 75.0 = 75%). |
repair-amount |
int |
0 |
Amount of durability restored on success. -1 makes the item unbreakable. |
commands |
list |
— | List of console commands to run upon successful application. |
lore-added-to-item-when-applied |
list |
— | Lore lines to append to the target item’s tooltip after application. |
Target-Item Filtering
| Key | Type | Default | Description |
|---|---|---|---|
allowed-items-mode |
enum |
DISABLED |
One of WHITELIST, BLACKLIST, or DISABLED. |
allowed-items |
list |
— |
List of materials (and optional model-data) to include or exclude. Format: Any model-data you include here will be applied to the item and will override the |
can-be-combined-into |
string |
'' |
(Optional) recipe key for combining multiple books into one. |
¶ Example
items:
bookofswords:
name: '&8[&d✫&8] &f&lBook of &b&lSwords'
lore:
- ''
- '&f┃ &6Drag and Drop onto &aANY SWORD &6to apply:'
- ''
- '&f┃ &7Sharpness VII'
- '&f┃ &7Smite VI'
- '&f┃ &7Sweeping edge V'
material: ENCHANTED_BOOK
glow: false
# 0 for disabled | Model data of this item
custom-model-data: 0
# Enchantments which should be added to the target item when applied. The format is 'enchantment level:max-level'
enchantments:
- 'sharpness 7:10'
- 'smite 6:20'
- 'sweeping_edge 5'
# Should the plugin check for conflicts between enchantments? Example: Item has Sharpness 5 and you apply Smite 3 from the book. If this is true, the plugin will block the application of Smite 3.
enchantments-conflict-check: false
# Should the same types of enchantments on an item be summed up? Example: Item has Sharpness 5 and you apply Sharpness 3 from the book. If this is true, the item will have Sharpness 8 after applying the book.
sum-existing-enchantments: false
# Should the same types of enchantments on an item be summed up like in vanilla?
# Example: Item has Sharpness 3 and you apply Sharpness 3 from the book. If this is true, the item will have Sharpness 4 after applying the book.
# It blocks application of enchantments with higher levels than the existing ones.
# It will only work if sum-existing-enchantments is set to true
sum-existing-enchantments-like-in-vanilla: false
# Attributes which should be added to the target item when applied
#https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html
# Equipment slots: HAND, OFF_HAND, FEET, LEGS, CHEST, HEAD
attributes:
- 'GENERIC_MAX_HEALTH 10:HAND'
# 0 for disabled | Make the item change model data when applied
changed-model-data: 0
# NBT which should be added to the target item when applied
nbt-added-to-item-when-applied: ''
can-be-applied-to-damaged-item: true
can-be-applied-to-unbreakable-item: true
# Chance to apply the item to the target item. 100.0 means 100% chance.
chance: 100.0
# 0 for disabled | -1 to make the item unbreakable | Repair amount
repair-amount: 0
# Commands which should be executed when the item is applied
commands:
- 'say Player %player% successfully applied Book of Swords onto %item%'
lore-added-to-item-when-applied:
- ''
- '&f┃ &7Sharpness VII'
- '&f┃ &7Smite VI'
- '&f┃ &7Sweeping edge V'
# Needed nbt to apply the item to the target item
needed-nbt-to-apply: ''
# Needed nbt to not apply the item to the target item
needed-nbt-to-not-apply: ''
# WHITELIST or BLACKLIST or DISABLED
allowed-items-mode: WHITELIST
allowed-items:
# The number 10 means that to the item will be added model data number 10 (It has higher priority than setting changed-model-data)
- 'DIAMOND_SWORD:10'
- 'IRON_SWORD'
- 'NETHERITE_SWORD'
- 'WOODEN_SWORD'
- 'GOLDEN_SWORD'
- 'STONE_SWORD'
can-be-combined-into: ''