pluginiPlugin

物品配置

学习如何创建自定义物品

概述

Zaphkiel 物品通过 YAML 配置文件定义。物品配置文件位于 plugins/Zaphkiel/item/ 目录下。

基础配置

创建第一个物品

每个物品都需要一个唯一的 ID 和基本配置：

item/weapon/swords.yml
# 唯一的 ID
my_sword:
  icon: diamond_sword
  name:
    item_name: '&6我的剑'
  lore:
    item_type: '&9武器'
    item_description:
      - '&f一把强大的剑'

必需配置项

配置项说明示例
icon物品材质diamond_sword

可选配置项

配置项说明
display显示模板
name名称变量
lore描述变量
data自定义数据
data-mapper数据映射
event事件脚本

显示配置

使用显示模板

显示模板让多个物品共享相同的外观格式：

item/weapon/swords.yml
my_sword:
  display: weapon_display  # 引用显示模板
  name:
    item_name: '&6魔法剑'
  lore:
    item_type: '&9传说武器'

模板配置

display/weapon.yml
weapon_display:
  name: '&6<item_name> &7[<level_text>&7]'
  lore:
  - '&9类型: <item_type>'
  - '&f<item_description...>'
  - ''
  - '&c伤害: <damage>'
  - '&b等级: <level>'

自定义名称和描述

item/weapon/swords.yml
my_sword:
  name:
    item_name: '&6魔法剑'
    item_title: '&l传说'
  lore:
    item_type: '&9武器'
    item_description:
      - '&f一把充满魔力的剑'
      - '&7右键释放技能'

数据和映射

存储自定义数据

item/weapon/swords.yml
my_sword:
  data:
    damage: 100
    level: 5
    durability: 1000

动态显示数据

使用 data-mapper 将数据显示在物品上：

item/weapon/swords.yml
my_sword:
  data:
    damage: 100
    level: 5
  data-mapper:
    damage: it  # 直接显示伤害值
    level: it   # 直接显示等级
    level_text: |-  # 根据等级显示文字
      case &level [
        when < 10 -> "新手"
        when < 50 -> "熟练"
        else -> "专家"
      ]

事件系统

添加交互功能

my_sword:
  event:
    on_right_click:
      if check player level >= 2 then {
        tell color '&a释放了魔法攻击！'
        tell color inline '&7造成了 &c{{ item data damage }} &7点伤害'  
      } else {
        tell color '&c等级不足，需要 2 级！'  
        cancel
      }

常用事件类型

事件触发时机
on_right_click右键点击
on_left_click左键点击
on_attack攻击实体
on_consume消耗物品

完整示例

item/weapon/swords.yml
magic_sword:
  display: weapon_display
  icon: diamond_sword
  name:
    item_name: '&6魔法剑'
  lore:
    item_type: '&9传说武器'
    item_description:
    - '&f一把充满魔力的神器'
    - '&7右键释放魔法技能'
  data:
    damage: 150
    level: 10
    mana_cost: 20
    player-mana: 50
  data-mapper:
    damage: it
    level: it
    level_text: |-
      case &level [
        when < 5 -> "&f普通"
        when < 15 -> "&d稀有"
        else -> "&6传说"
      ]
    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 '&a释放了魔法攻击！'
        tell color inline '&7造成了 &c{{ item data damage }} &7点伤害'  
      } else {
        tell color '&c魔法不足，需要更多法力值！'  
        cancel
      }
display/weapon_display.yml
weapon_display:
  name: '&6<item_name> &7[<level_text>&7]'
  lore:
  - '&9类型: <item_type>'
  - '&f<item_description...>'
  - ''
  - '&c伤害: <damage>'
  - '&b等级: <level>'

实用技巧

锁定配置

使用 !! 后缀锁定配置项，确保重载后强制更新现有物品：

my_sword:
  # 锁定名称，重载后会更新现有物品
  name!!:  # 锁定名称，重载后会更新现有物品
    item_name: '&6终极剑'

目录