物品定义与套装

EmakiItem 的物品文件通常位于 items/*.yml，套装文件位于 sets/*.yml。物品定义决定一个稳定物品 ID 如何生成 ItemStack，套装定义决定多个装备同时穿戴时如何提供额外效果。

物品定义字段

完整字段参考

字段	类型	必填	默认值	说明
`id`	string	是	—	物品唯一 ID。其他模块引用时使用。
`material`	string	是	—	原版材质（Bukkit Material 枚举名）。
`display_name`	string	否	—	物品显示名（MiniMessage 格式，支持 `{变量}` 占位符）。
`item_name`	string	否	—	物品内部名称（1.21+ 物品组件名称，不可被铁砧修改）。
`lore`	list<string>	否	`[]`	Lore 文本列表（MiniMessage 格式，支持 `{变量}` 占位符）。
`effects`	list	否	—	物品效果列表（统一格式，见下方说明）。
`components`	object	否	—	物品组件配置（见下方详细说明）。
`set`	object	否	—	套装信息。
`conditions`	object	否	—	装备条件配置。
`repair`	object	否	—	修复配置。
`update`	object	否	—	自动更新配置。
`actions`	object	否	—	触发动作配置。

效果系统（effects）

物品效果统一使用 effects 列表，通过 type 字段区分类型：

type	说明
`variables`	表达式引擎变量，用于 `display_name` 和 `lore` 中的占位符渲染。
`ea_attribute`	EmakiAttribute PDC 属性，写入物品 PDC。
`es_skill`	EmakiSkills 技能附加，装备时获得技能；payload 使用 `es_skills` 列表。

yaml

effects:
  - type: "variables"
    variables:
      physical_attack: 12
      physical_crit_rate: 5
  - type: "ea_attribute"
    ea_attributes:
      physical_attack: 12.0
      physical_crit_rate: 5.0
  - type: "es_skill"
    es_skills:
      - "fireball"
      - "flame_dash"

当前配置线不再使用 ea_attribute_meta；如果需要真实属性输出，请把属性值写入显式 ea_attributes。variables 只作为显示文本和占位符上下文，不会自动变成 Attribute PDC 属性。

components 物品组件

组件	类型	说明
`custom_model_data`	object/integer	自定义模型数据（1.21.4+ 支持 floats/flags/strings/colors 多字段格式）。
`item_model`	string	物品模型 NamespacedKey（1.21+ 物品模型系统）。
`tooltip_style`	string	Tooltip 样式 NamespacedKey。
`enchantments`	map/list	附魔配置。格式 `{enchant_id: level}` 或 `["enchant_id:level"]`。
`item_flags`	list<string>	物品标志列表（如 `HIDE_ENCHANTS`、`HIDE_ATTRIBUTES`）。
`hide_tooltip`	boolean	是否隐藏整个 tooltip。
`unbreakable`	boolean	是否不可破坏。
`enchantment_glint_override`	boolean	是否强制显示/隐藏附魔光效。
`max_stack_size`	integer	最大堆叠数量（1–99）。
`rarity`	string	物品稀有度（`COMMON`、`UNCOMMON`、`RARE`、`EPIC`）。
`damage`	integer	当前耐久损耗值。
`max_damage`	integer	最大耐久值。
`enchantable`	integer	附魔等级权重。
`attribute_modifiers`	list	原版属性修饰符列表。

attribute_modifiers 格式

yaml

components:
  attribute_modifiers:
    - attribute: "attack_damage"
      amount: 12.0
      operation: "add_number"
      slot: "hand"
      name: "emakiitem:example_item/attack_damage"

字段	说明
`attribute`	原版属性名（如 `attack_damage`、`attack_speed`）。
`amount`	修饰值。
`operation`	运算方式：`add_number`、`add_scalar`、`multiply_scalar_1`。
`slot`	生效槽位：`hand`、`off_hand`、`head`、`chest`、`legs`、`feet`、`any`。
`name`	修饰符名称（唯一标识，推荐 `namespace:item_id/attribute` 格式）。

物品示例

基础武器

yaml

id: "beginner_blade"
material: "iron_sword"
display_name: "<white>新手长剑</white>"
lore:
  - "<gray>一把稳定可靠的基础武器。</gray>"
  - ""
  - "<gray>攻击力：<white>+10</white></gray>"
components:
  unbreakable: true
  item_flags:
    - "HIDE_UNBREAKABLE"
effects:
  - type: "ea_attribute"
    ea_attributes:
      physical_attack: 10.0
set:
  id: "beginner_set"
  piece: "weapon"

带变量的高级装备

yaml

id: "flame_blade"
material: "netherite_sword"
display_name: "<gradient:red:gold>%name%</gradient>"
lore:
  - "<dark_gray>━━━━━━━━━━━━━━━━━━</dark_gray>"
  - "<red>⚔ 物理攻击：<white>+%physical_attack%</white></red>"
  - "<yellow>✦ 暴击率：<white>+%physical_crit_rate%%</white></yellow>"
  - "<dark_gray>━━━━━━━━━━━━━━━━━━</dark_gray>"
  - "<gray>传说中由龙焰锻造的神兵。</gray>"
components:
  item_model: "emaki:flame_blade"
  enchantment_glint_override: true
  rarity: "rare"
  max_stack_size: 1
effects:
  - type: "variables"
    variables:
      name: "烈焰之刃"
      physical_attack: 45
      physical_crit_rate: 12
  - type: "ea_attribute"
    ea_attributes:
      physical_attack: 45.0
      physical_crit_rate: 0.12
  - type: "es_skill"
    es_skills:
      - "flame_slash"
set:
  id: "flame_set"
  piece: "weapon"

消耗品

yaml

id: "health_potion_large"
material: "potion"
display_name: "<red>大型生命药水</red>"
lore:
  - "<gray>右键使用，恢复 50 点生命。</gray>"
  - "<dark_gray>使用后消耗。</dark_gray>"
components:
  max_stack_size: 16
  custom_model_data: 1001
actions:
  interact:
    - 'heal amount=50'
    - 'playsound sound=minecraft:entity.generic.drink volume=1 pitch=1'
    - 'clearitem slot=mainhand source=emakiitem-health_potion_large'
    - 'sendmessage text="<green>恢复了 50 点生命。</green>"'

条件配置

物品可以配置装备条件，不满足时 ea_attributes 不生效：

yaml

conditions:
  entries:
    - "%player_level% >= 10"
    - "%player_class% == 'warrior'"
  type: "all_of"
  required_count: 2
  invalid_as_failure: true
  deny_message: "<red>你不满足装备条件！</red>"
  deny_actions:
    - 'sendmessage text="<red>需要等级 10 以上的战士才能装备此武器。</red>"'

字段	说明
`entries`	条件表达式列表。
`type`	条件组合方式：`all_of`（全部满足）/ `any_of`（任一满足）。
`required_count`	需要满足的最少条件数。
`invalid_as_failure`	表达式解析失败时是否视为不满足。
`deny_message`	不满足时的提示消息。
`deny_actions`	不满足时执行的动作。

修复配置

物品耐久耗尽后可以通过材料或金币修复：

yaml

repair:
  enabled: true
  materials:
    - item_sources:
        - "minecraft-diamond"
      amount: 1
      repair_amount: 250
  economy:
    enabled: true
    currencies:
      - provider: "vault"
        currency_id: ""
        base_cost: 100
        cost_formula: "%base_cost% * %damage_percent%"
        display_name: "<gold>金币</gold>"
  disabled_display:
    name_prefix: "<dark_gray>[已损坏] </dark_gray>"
    lore_append:
      - ""
      - "<red>此物品已损坏，属性不生效</red>"
  on_disabled:
    - 'sendmessage text="<red>你的武器已损坏！</red>"'
  on_repaired:
    - 'sendmessage text="<green>武器已修复！</green>"'

套装定义

套装字段

字段	类型	必填	说明
`id`	string	是	套装唯一 ID。
`display_name`	string	是	套装显示名（MiniMessage 格式）。
`pieces`	map	是	套装部件定义（key 为部件标识）。
`lore`	object	否	套装 Lore 显示格式配置。
`thresholds`	map	是	件数阈值效果配置。

部件定义（pieces）

yaml

pieces:
  blade:
    item: "example_item"
    slot: "main_hand"
    display: "示例之刃"
  helmet:
    item: "example_guardian_helmet"
    slot: "helmet"
    display: "守护者头盔"

字段	说明
`item`	对应的物品 ID（`items/` 目录下的物品定义）。
`slot`	装备槽位（`main_hand`/`off_hand`/`helmet`/`chestplate`/`leggings`/`boots`）。
`display`	在套装 Lore 中显示的部件名称。

Lore 显示配置

yaml

lore:
  header: "<dark_gray>—— <aqua>套装名</aqua> <gray>(%active%/%total%)</gray> ——</dark_gray>"
  equipped_format: "<green>✔ %piece%</green>"
  missing_format: "<gray>✘ %piece%</gray>"
  active_threshold_format: "<green>%line%</green>"
  inactive_threshold_format: "<dark_gray>%line%</dark_gray>"
  separator: ""

套装示例

yaml

id: "example_set"
display_name: "<aqua>示例守护者套装</aqua>"

pieces:
  blade:
    item: "example_item"
    slot: "main_hand"
    display: "示例之刃"
  helmet:
    item: "example_guardian_helmet"
    slot: "helmet"
    display: "守护者头盔"
  chestplate:
    item: "example_guardian_chestplate"
    slot: "chestplate"
    display: "守护者胸甲"
  boots:
    item: "example_guardian_boots"
    slot: "boots"
    display: "守护者战靴"

lore:
  header: "<dark_gray>—— <aqua>示例守护者套装</aqua> <gray>(%active%/%total%)</gray> ——</dark_gray>"
  equipped_format: "<green>✔ %piece%</green>"
  missing_format: "<gray>✘ %piece%</gray>"
  active_threshold_format: "<green>%line%</green>"
  inactive_threshold_format: "<dark_gray>%line%</dark_gray>"
  separator: ""

thresholds:
  2:
    lore:
      - "[2件套] 物理攻击 +5，解锁冲刺技能"
    effects:
      - type: "ea_attribute"
        ea_attributes:
          physical_attack: 5.0
      - type: "es_skill"
        es_skills:
          - "guardian_dash"
  4:
    lore:
      - "[4件套] 物理攻击 +15，物理防御 +10，解锁守护者光环"
    effects:
      - type: "ea_attribute"
        ea_attributes:
          physical_attack: 15.0
          physical_defense: 10.0
      - type: "es_skill"
        es_skills:
          - "guardian_aura"

自动更新

update 配置控制物品在哪些时机自动刷新：

yaml

update:
  enabled: true
  version: 1
  triggers:
    join: true
    held_change: true
    inventory_click: true
    inventory_drag: true
    pickup: true
    interact: true
    command: true

触发项	说明	性能影响
`join`	玩家登录时。	低
`held_change`	切换手持物品时。	低
`inventory_click`	点击背包时。	中
`inventory_drag`	拖拽物品时。	中
`pickup`	拾取物品时。	低
`interact`	交互事件时。	中
`command`	执行 `/ei update` 时。	低

每次修改物品配置后递增 version 字段即可触发更新。建议不要开启过多高频触发，先确保手动 /ei update 正常，再逐步开启自动更新。

物品定义与套装 ​

物品定义字段 ​

完整字段参考 ​

效果系统（effects） ​

components 物品组件 ​

attribute_modifiers 格式 ​

物品示例 ​

基础武器 ​

带变量的高级装备 ​

消耗品 ​

条件配置 ​

修复配置 ​

套装定义 ​

套装字段 ​

部件定义（pieces） ​

Lore 显示配置 ​

套装示例 ​

自动更新 ​

物品定义与套装

物品定义字段

完整字段参考

效果系统（effects）

components 物品组件

attribute_modifiers 格式

物品示例

基础武器

带变量的高级装备

消耗品

条件配置

修复配置

套装定义

套装字段

部件定义（pieces）

Lore 显示配置

套装示例

自动更新