Item Configuration
Learn How to Create Custom Items
Overview
Zaphkiel items are defined through YAML configuration files. Item configuration files are located in the plugins/Zaphkiel/item/ directory.
Basic Configuration
Create Your First Item
Each item requires a unique ID and basic configuration:
# Unique ID
my_sword:
icon: diamond_sword
name:
item_name: '&6My Sword'
lore:
item_type: '&9Weapon'
item_description:
- '&fA powerful sword'Required Configuration Items
| Configuration Item | Description | Example |
|---|---|---|
icon | Item material | diamond_sword |
Optional Configuration Items
| Configuration Item | Description |
|---|---|
display | Display template |
name | Name variables |
lore | Description variables |
data | Custom data |
data-mapper | Data mapping |
event | Event scripts |
Display Configuration
Use a Display Template
Display templates allow multiple items to share the same appearance format:
my_sword:
display: weapon_display # Reference the display template
name:
item_name: '&6Magic Sword'
lore:
item_type: '&9Legendary Weapon'Template Configuration
weapon_display:
name: '&6<item_name> &7[<level_text>&7]'
lore:
- '&9Type: <item_type>'
- '&f<item_description...>'
- ''
- '&cDamage: <damage>'
- '&bLevel: <level>'Custom Name and Description
my_sword:
name:
item_name: '&6Magic Sword'
item_title: '&lLegendary'
lore:
item_type: '&9Weapon'
item_description:
- '&fA sword filled with magic'
- '&7Right-click to release skills'Data and Mapping
Store Custom Data
my_sword:
data:
damage: 100
level: 5
durability: 1000Dynamically Display Data
Use data-mapper to display data on the item:
my_sword:
data:
damage: 100
level: 5
data-mapper:
damage: it # Directly display the damage value
level: it # Directly display the level
level_text: |- # Display text based on level
case &level [
when < 10 -> "Novice"
when < 50 -> "Skilled"
else -> "Expert"
]Event System
Add Interactive Functions
my_sword:
event:
on_right_click:
if check player level >= 2 then {
tell color '&aReleased magical attack!'
tell color inline '&7Dealt &c{{ item data damage }} &7damage'
} else {
tell color '&cInsufficient level, level 2 required!'
cancel
}Common Event Types
| Event | Trigger Timing |
|---|---|
on_right_click | Right-click |
on_left_click | Left-click |
on_attack | Attacking an entity |
on_consume | Consuming the item |
Complete Example
magic_sword:
display: weapon_display
icon: diamond_sword
name:
item_name: '&6Magic Sword'
lore:
item_type: '&9Legendary Weapon'
item_description:
- '&fA divine weapon filled with magic'
- '&7Right-click to release magical skills'
data:
damage: 150
level: 10
mana_cost: 20
player-mana: 50
data-mapper:
damage: it
level: it
level_text: |-
case &level [
when < 5 -> "&fCommon"
when < 15 -> "&dRare"
else -> "&6Legendary"
]
player-mana: it
event:
on_right_click: |
if check item data player-mana >= item data mana_cost then {
item data player-mana to 5
item update
tell color '&aReleased magical attack!'
tell color inline '&7Dealt &c{{ item data damage }} &7damage'
} else {
tell color '&cInsufficient mana, more mana required!'
cancel
}weapon_display:
name: '&6<item_name> &7[<level_text>&7]'
lore:
- '&9Type: <item_type>'
- '&f<item_description...>'
- ''
- '&cDamage: <damage>'
- '&bLevel: <level>'Practical Tips
Lock Configuration
Use the !! suffix to lock configuration items, ensuring forced updates to existing items after reloading:
my_sword:
# Lock the name, existing items will be updated after reloading
name!!: # Lock the name, existing items will be updated after reloading
item_name: '&6Ultimate Sword'