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.
disabled_display	Display overrides while the item is disabled: name_prefix (name prefix) and lore_append (extra lore lines).
on_disabled	Actions executed when the item becomes disabled.
on_repaired	Actions executed after repair.

Material fields

Field	Description
item_sources	Allowed material item sources (ItemSource shorthand such as minecraft-diamond). item_source and item are also accepted as key names.
matcher	Optional. Non-item-source conditions (component, PDC, lore, variable), ANDed with the sibling item_sources. See Item Matcher.
amount	Required amount, minimum 1.
restore	Durability restored. Supports fixed values like 250 or percentages like 50% of max damage.

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.

An entry is loaded 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	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:
    - '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.