Item Repair

The repair system lets equipment enter a disabled state when durability would break instead of disappearing; players then repair disabled equipment with the configured materials or currency

Disabled durability behavior

As durability approaches zero, the plugin runs these four steps:

1. PlayerItemDamageEvent is cancelled so the item does not disappear
2. Item damage is set to max damage and the item is marked disabled
3. PDC stores emakiitem:disabled (BYTE=1)
4. The on_disabled action list runs

This flow applies only to items with repair enabled; items without repair still break under vanilla rules

While you hold a disabled item in the main hand, its triggers no longer run, and attacking an entity fails the attack check so the damage event is cancelled

Configuration

All repair fields live at the top level of an item definition under repair:

Field	Type	Required	Default	Range	Description	Example
enabled	boolean	No	false	true / false	Whether repair is enabled. When false or missing, the whole repair block is inactive (equivalent to being unconfigured)	true
materials	list	No	empty	—	Material repair list; an entry is loaded only with a resolvable source (or matcher) and a non-blank restore	see below
economy	object	No	disabled	—	Currency repair configuration	see below
disabled_display	object	No	empty	—	Display overrides while the item is disabled	name_prefix: "<dark_gray>[Broken] </dark_gray>"
disabled_display.name_prefix	string	No	""	—	String prepended to the item name while disabled	"<dark_gray>[Broken] </dark_gray>"
disabled_display.lore_append	list	No	empty	—	Lore lines appended while disabled	- "<red>This item is broken; its stats are inactive.</red>"
on_disabled	list	No	empty	—	Actions executed when the item becomes disabled	- 'send_message text="..."'
on_repaired	list	No	empty	—	Actions executed after repair	- 'play_sound sound=...'

Material fields

Field	Type	Required	Default	Range	Description	Example
item_sources	list	No	empty	—	Allowed material item sources (ItemSource shorthand). This is the only accepted key name (item_source and item are retired)	- "minecraft-diamond"
matcher	object	No	none	see Item Matcher	Optional non-item-source conditions (component, PDC, lore, variable), ANDed with the sibling item_sources	type: component
amount	integer	No	1	>= 1 (the source applies max(1, value))	Required amount	1
restore	string	Yes	none	a fixed integer or an N% percentage	Durability restored; a percentage is relative to max_damage. A missing or non-numeric value drops the entry	"50%"

item_sources and matcher are sibling fields and both must hold. Item source conditions must not be written inside matcher — type: item_source and its aliases are rejected at load time and never match

A material entry loads only when it has both a resolvable source and a non-blank restore

DANGER

repair.materials[].matcher is supported, but item.source in the same file is not

item.source says which vanilla item to build the custom item from; a matcher there stops the item from being created. repair.materials[] decides whether an incoming item counts as repair material, which is what matchers are for. The two look alike and mean entirely different things — see Only input-matching fields support matcher

repair:
  enabled: true
  materials:
    # Accepts only netherite ingots that have never been renamed
    - item_sources:
        - minecraft-netherite_ingot
      matcher:
        type: component
        component: custom_name
        operator: absent
      amount: 1
      restore: "50%"

Economy fields

Field	Type	Required	Default	Range	Description	Example
enabled	boolean	No	true when a valid currency entry exists	true / false	Whether currency repair is enabled. When missing, it is treated as enabled if any valid currency entry exists	true
restore	string	No	"100%"	a fixed integer or an N% percentage	Durability restored per currency repair; a percentage is relative to max_damage	"100%"
currencies	list	No	empty	—	Currency cost list	see below

currencies entry fields:

Field	Type	Required	Default	Range	Description	Example
provider	string	No	auto	—	Economy provider; blank falls back to auto, and a non-blank value is lowercased	vault
currency_id	string	No	""	—	Currency ID; leave blank to use the provider default	default
amount	number	No	0	>= 0 (the source applies max(0, value))	Fixed cost. When greater than 0 it applies directly and the formula is ignored	100
base_cost	number	No	0	>= 0 (the source applies max(0, value))	Base cost, referenced as base_cost in the formula	100
cost_formula	string	No	""	—	Cost formula. Available variables are max_damage, damage, current_damage, missing_durability, missing_ratio, restore_amount, restore_ratio, and base_cost	"100 + missing_durability * 0.25"
display_name	string	No	""	—	Currency name shown in messages; falls back to currency_id, then provider, when blank	Coins

A cost entry is kept only when it produces a positive amount; entries sharing a provider and currency_id are merged and summed. If charging fails, already-debited currency is rolled back

Repair paths

The game offers two repair paths

Direct inventory repair: you hold repair material on the cursor and click the disabled item. The cursor amount must be at least the material entry's amount. On a match, the material is consumed, durability is restored, and on_repaired runs

Repair interface: use /ei repair to open gui/repair_gui.yml. The interface provides a target equipment slot (target_item), four material slots (material_input_1 through material_input_4), a preview slot (preview_display), and material repair (material_repair) and economy repair (economy_repair) buttons. Shift-clicking inventory items inserts them quickly. When repair finishes or the interface closes, the equipment and any unconsumed materials are returned to the player; if the inventory is full they are dropped and the player is notified

Whichever path you take, the repair:

• damage reduced by the restore value;
• the PDC disabled flag cleared automatically once damage is below max damage;
• the on_repaired action list running

Going through the interface additionally refreshes player items, recalculates sets, and schedules Attribute equipment sync after a successful repair

Repair event

Whether you repair with materials or currency, the cancellable ItemRepairEvent fires before charging and restoring durability; listeners may override the restore amount or cancel the repair. See Events API

Example

id: legendary_sword
item:
  source: minecraft-netherite_sword
  components:
    custom_name: "<gold>Legendary Sword</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: "Coins"
        cost_formula: "100 + missing_durability * 0.25"
  on_disabled:
    - 'send_message text="<red>Your equipment broke!</red>"'
    - "play_sound sound=minecraft:entity.item.break volume=1 pitch=0.5"
  on_repaired:
    - 'send_message text="<green>Equipment repaired!</green>"'
    - "play_sound sound=minecraft:block.anvil.use volume=1 pitch=1.2"

Action context

on_disabled injects item_id. On the interface path, on_repaired injects item_id, repair_source (material or economy), and restore; the direct inventory path injects only item_id