物品修复系统

物品修复系统包含两块: 装备耐久归零后怎样变成禁用状态而不是直接消失, 以及用哪些材料或货币把它修回来

物品修复系统允许装备在耐久归零后进入"禁用"状态而非消失, 玩家可以使用指定材料修复装备恢复使用

耐久度禁用机制

装备耐久快用完时, 插件会按下面四步处理:

PlayerItemDamageEvent 被取消, 物品不会消失
物品 damage 设为 max_damage, 标记为禁用状态
PDC 写入 emakiitem:disabled (BYTE=1)
执行 on_disabled 动作列表

这套流程只对启用了 repair 的物品生效; 没启用 repair 的物品仍按原版规则损坏

主手拿着被禁用的物品时, 这件物品的触发器不再执行; 攻击实体时 attack 判定不通过, 伤害事件会被取消

配置字段

修复相关字段都写在物品定义文件的顶层 repair 下:

字段	类型	必填	默认值	取值范围	说明	示例
`enabled`	boolean	否	`false`	`true` / `false`	是否启用修复系统. 为 `false` 或缺失时整个 `repair` 块失效 (等价于没配)	`true`
`materials`	list	否	空	—	材料修复列表; 条目必须同时具备可解析来源 (或 `matcher`) 与非空 `restore` 才会加载	见下方
`economy`	object	否	禁用	—	货币修复配置	见下方
`disabled_display`	object	否	空	—	禁用状态下的显示覆盖	`name_prefix: "<dark_gray>[已损坏] </dark_gray>"`
`disabled_display.name_prefix`	string	否	`""`	—	禁用时加在物品名前面的字符串	`"<dark_gray>[已损坏] </dark_gray>"`
`disabled_display.lore_append`	list	否	空	—	禁用时追加到物品 Lore 的行列表	`- "<red>此物品已损坏, 属性不生效</red>"`
`on_disabled`	list	否	空	—	物品变为禁用状态时执行的动作列表	`- 'send_message text="..."'`
`on_repaired`	list	否	空	—	物品修复成功后执行的动作列表	`- 'play_sound sound=...'`

materials 条目字段

字段	类型	必填	默认值	取值范围	说明	示例
`item_sources`	list	否	空	—	允许的材料物品来源列表 (ItemSource 短横线写法). 这是唯一可用的键名 (`item_source` 与 `item` 已下线)	`- "minecraft-diamond"`
`matcher`	object	否	无	见物品匹配器	可选的通用物品匹配器, 只写组件, PDC, Lore 等非物品源条件, 与同级的 `item_sources` 取 AND	`type: component`
`amount`	integer	否	`1`	`>= 1` (源码按 `max(1, 值)` 处理)	需要消耗的数量	`1`
`restore`	string	是	无	固定整数, 或 `N%` 百分比	恢复的耐久量, 百分比相对于 `max_damage`. 缺失或非数字时该条目被丢弃 (等于没有有效恢复量)	`"50%"`

一个材料条目必须同时有可解析的来源和非空 restore, 才会被加载

DANGER

repair.materials[].matcher 可以写, 但同一个文件里的 item.source 不能写 matcher

item.source 是"用哪个原版物品构造出这个自定义物品", 在那里写 matcher 会让物品无法生成; repair.materials[] 是"玩家放进来的物品算不算修复材料", 才是匹配器用得上的地方. 两者形状相似, 含义完全不同, 详见只有输入匹配点支持 matcher

下面这个例子用 matcher 收窄修复材料 -- 物品源写 item_sources, 组件条件写 matcher, 两者取 AND:

yaml

repair:
  enabled: true
  materials:
    - item_sources:
        - minecraft-netherite_ingot
      matcher:
        type: component
        component: custom_name
        operator: absent
      amount: 1
      restore: "50%"

这样就只接受没有被重命名过的下界合金锭, 避免玩家用改过名的特殊材料来修复

WARNING

matcher 内部不能写物品源条件 (type: item_source / item_sources / source / sources 会被拒绝并告警). 两个字段都省略时该材料条目永不命中. 完整语法见物品匹配器

economy 字段

字段	类型	必填	默认值	取值范围	说明	示例
`enabled`	boolean	否	有有效货币条目时 `true`	`true` / `false`	是否启用货币修复. 缺失时按"存在有效货币条目就启用"处理	`true`
`restore`	string	否	`"100%"`	固定整数, 或 `N%` 百分比	单次货币修复恢复的耐久量, 百分比相对于 `max_damage`	`"100%"`
`currencies`	list	否	空	—	货币成本列表	见下方

currencies 条目字段:

字段	类型	必填	默认值	取值范围	说明	示例
`provider`	string	否	`auto`	—	经济提供者; 空白时回退 `auto`, 非空时统一转小写	`vault`
`currency_id`	string	否	`""`	—	货币 ID; 留空则用提供者的默认货币	`default`
`amount`	number	否	`0`	`>= 0` (源码按 `max(0, 值)` 处理)	固定费用. 大于 0 时直接生效, 并忽略公式	`100`
`base_cost`	number	否	`0`	`>= 0` (源码按 `max(0, 值)` 处理)	基础费用, 可以在公式里用 `base_cost` 引用	`100`
`cost_formula`	string	否	`""`	—	费用公式, 可以使用 `max_damage`, `damage`, `current_damage`, `missing_durability`, `missing_ratio`, `restore_amount`, `restore_ratio` 与 `base_cost`	`"100 + missing_durability * 0.25"`
`display_name`	string	否	`""`	—	提示消息里显示的货币名称; 留空时依次回退为 `currency_id`, `provider`	`金币`

费用只在会产生正数时才保留条目; 相同 provider + currency_id 的条目会合并累加. 扣费失败时会回滚已经扣掉的货币

修复触发方式

游戏里有两种修复方式

背包直接修复: 你用光标拿着修复材料, 点击被禁用的物品. 光标上的数量不能少于该材料条目的 amount, 命中后扣掉材料, 恢复耐久并执行 on_repaired

修复界面: 用 /ei repair 打开 gui/repair_gui.yml. 界面提供待修复装备槽 (target_item), 四个材料槽 (material_input_1 到 material_input_4), 预览槽 (preview_display) 以及材料修复 (material_repair) 和经济修复 (economy_repair) 按钮. Shift 点击背包物品可以快速放入. 修复完成或关闭界面时, 装备与没消耗的材料都会归还玩家; 背包已满则改为掉落并提示

不管走哪条路, 修复后都会:

按 restore 值减少 damage;
damage 低于 max_damage 时自动清除 PDC 禁用标记;
执行 on_repaired 动作列表

走修复界面这条路, 成功后还会刷新玩家物品, 重算套装并触发 Attribute 装备同步

修复事件

无论材料修复还是货币修复, 在扣费和恢复耐久之前都会触发一个可取消的 ItemRepairEvent, 监听器可以改写恢复量或取消这次修复. 详见事件 API

完整示例

yaml

id: legendary_sword
item:
  source: minecraft-netherite_sword
  components:
    custom_name: "<gold>传说之剑</gold>"
repair:
  enabled: true
  materials:
    - item_sources:
        - "minecraft-netherite_ingot"
      amount: 1
      restore: "50%"
    - item_sources:
        - "minecraft-diamond"
      amount: 3
      restore: 200
  economy:
    enabled: true
    restore: "100%"
    currencies:
      - provider: "vault"
        currency_id: "default"
        display_name: "金币"
        cost_formula: "100 + missing_durability * 0.25"
  on_disabled:
    - 'send_message text="<red>你的装备已损坏！</red>"'
    - "play_sound sound=minecraft:entity.item.break volume=1 pitch=0.5"
  on_repaired:
    - 'send_message text="<green>装备修复成功！</green>"'
    - "play_sound sound=minecraft:block.anvil.use volume=1 pitch=1.2"

动作上下文

on_disabled 会注入 item_id. on_repaired 在界面路径下注入 item_id, repair_source (material 或 economy) 和 restore; 背包直接修复路径只注入 item_id

物品修复系统 ​

耐久度禁用机制 ​

配置字段 ​

materials 条目字段 ​

economy 字段 ​

修复触发方式 ​

修复事件 ​

完整示例 ​

动作上下文 ​