iPlugin | Item Configuration

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:

item/weapon/swords.yml

# 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:

item/weapon/swords.yml

my_sword:
  display: weapon_display  # Reference the display template
  name:
    item_name: '&6Magic Sword'
  lore:
    item_type: '&9Legendary Weapon'

Template Configuration

display/weapon.yml

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

item/weapon/swords.yml

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

item/weapon/swords.yml

my_sword:
  data:
    damage: 100
    level: 5
    durability: 1000

Dynamically Display Data

Use data-mapper to display data on the item:

item/weapon/swords.yml

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

item/weapon/swords.yml

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
      }

display/weapon_display.yml

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'

Item Configuration

On this page