Item Repair

The repair system lets equipment enter a disabled state when durability would break instead of disappearing. Players can repair disabled equipment with configured materials or currency.

Disabled durability behavior

When durability is about to reach zero:

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; other items still break under vanilla rules.

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

Configuration

repair is a top-level field in an item definition.

Field	Description
enabled	Whether repair is enabled. When false or missing, the whole repair block is inactive.
materials	Material repair list.
economy	Currency repair configuration.
on_disabled	Actions executed when the item becomes disabled.
on_repaired	Actions executed after repair.

Material fields

Field	Description
item_sources	List of material item sources (ItemSource shorthand such as minecraft-diamond). item_source and item are also accepted as key names.
amount	Required amount, minimum 1.
restore	Durability restored. Supports fixed values like 250 or percentages like 50% of max damage.

An entry is loaded only when it has both a resolvable source and a non-blank restore.

Economy fields

Field	Description
enabled	Whether currency repair is enabled. When missing, it is treated as enabled if any valid currency entry exists.
restore	Durability restored per currency repair; supports fixed values or percentages. Defaults to 100%.
currencies	Currency cost list.

currencies entry fields:

Field	Description
provider	Economy provider, defaults to auto.
currency_id	Currency ID; leave blank to use the provider default.
amount	Fixed cost. When greater than 0 it applies directly and the formula is ignored.
base_cost	Base cost, referenced as %base_cost% in the formula.
cost_formula	Cost formula. Available variables are max_damage, damage, current_damage, missing_durability, missing_ratio, restore_amount, restore_ratio, and base_cost.
display_name	Currency name shown in messages.

Only entries producing a positive cost are kept; entries sharing a provider and currency_id are merged and summed. If charging fails, already-debited currency is rolled back.

Repair paths

There are two repair paths.

Direct inventory repair: the player holds repair material on the cursor and clicks 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: /ei repair opens 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.

Both paths result in:

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

The interface path additionally refreshes player items, recalculates sets, and schedules Attribute equipment sync after a successful repair.

Repair event

Both material and currency repair fire the cancellable ItemRepairEvent 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:
    - 'sendmessage text="<red>Your equipment broke!</red>"'
    - "playsound sound=minecraft:entity.item.break volume=1 pitch=0.5"
  on_repaired:
    - 'sendmessage text="<green>Equipment repaired!</green>"'
    - "playsound 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.