BotchedDurability Configuration Guide

================
GENERAL SETTINGS
================

settings:
  lore-display: true
  lore-format: "&7Durability: &a%current% &7/ &c%max%"

lore-display
- true = Show durability in lore
- false = Disable lore display

lore-format
Available placeholders:
%current%
%max%

Example:

Durability: 4500 / 5000

===============
DAMAGE SETTINGS
===============

damage:
  weapon-hit: 1
  block-break: 1
  armor-hit: 1
  vanilla: 1

weapon-hit
Durability lost when attacking entities.

block-break
Durability lost when breaking blocks.

armor-hit
Durability lost when armor takes a hit (mobs, players, arrows,
explosions). Fall damage, poison, freezing and starving never wear
armor down.

vanilla
Durability lost for anything else that wears an item down (shears,
hoes, flint and steel, bows...).

Each use is counted once, so a tool loses exactly 1 durability per
block or hit with the default values.

==============
COMPAT SETTINGS
==============

compat:
  ignore-botchedskills-items: true
  ignore-botchedmobs-items: true

Items from BotchedSkills (knives, jackhammers...) and BotchedMobs gear
look after their own durability and Self Repair. BotchedDurability
leaves them alone while these are true.

==============
BREAK SETTINGS
==============

break:
  destroy-item: true
  play-sound: true
  sound: BLOCK_ANVIL_BREAK

  item-message: "&cYour item has broken!"
  armor-message: "&cA piece of your armor has broken!"

  minimum-durability: 1

destroy-item
true = item is destroyed
false = item remains at minimum durability

play-sound
Plays a sound when an item breaks.

minimum-durability
Used when destroy-item is false.

===============
REPAIR SETTINGS
===============

repair:
  money:
    enabled: true
    cost: 8
    currency: auto
    botchedeconomy-currency: ''
    money-multiplier: 10
    use-vault: true
    item: EMERALD
    item-name: Emerald
    item-name-plural: Emeralds
    currency-name: "Coins"
    take-command: "eco take %player% %cost%"

enabled
Enable paid repairs.

cost
Default repair cost, in emeralds.

currency
auto           = BotchedEconomy, otherwise a Vault economy (when
                 use-vault is true), otherwise emerald items. auto
                 never uses take-command, because its balance can't
                 be checked
botchedeconomy = same as auto (emeralds if no economy is installed)
command        = always take-command. The player's balance can't be
                 checked first, so the command itself must refuse
                 players who can't pay
item           = always emerald items

botchedeconomy-currency
BotchedEconomy currency to charge. Blank = its default currency.

money-multiplier
With money, each emerald of a price costs this much.
cost: 8 with money-multiplier: 10 = $80.

use-vault
true  = without BotchedEconomy, charge any economy plugin through
        Vault (EssentialsX, CMI and others)
false = without BotchedEconomy, use the item instead

item / item-name / item-name-plural
The item players pay with when there is no economy, and how it is
named in messages.

currency-name / take-command
Only used by the command currency.

BotchedDurability uses the same money as BotchedSkills and
BotchedMobs when BotchedEconomy is installed. No other plugins
are needed: without any economy, players pay with emeralds.

=======================
RANK DURABILITY BONUSES
=======================

durability-multipliers:
  enabled: true
  default: 1.0

  ranks:
    Premium:
      permission: "botcheddurability.rank.premium"
      multiplier: 0.90

    VIP:
      permission: "botcheddurability.rank.vip"
      multiplier: 0.80

enabled
Enable rank durability bonuses.

default
Normal durability multiplier.

multiplier values:

1.00 = No bonus
0.90 = 10% save chance
0.80 = 20% save chance
0.70 = 30% save chance
0.60 = 40% save chance

Works with any permission plugin (or none). Give players
botcheddurability.rank.<name>, for example botcheddurability.rank.vip.
A LuckPerms group permission like group.vip also works.

Rank names can be changed.

Example:

Donator
Hero
Mythic
Titan

===========
BOOK PRICES
===========

book-prices:
  reinforced:
    1: 16
    2: 32
    3: 64
    4: 128
    5: 256

  fortified:
    1: 24
    2: 48
    3: 96
    4: 192
    5: 384

Prices are in emeralds, and use the same currency and
money-multiplier as repairs.

Used by:

/bd buybook

============
CUSTOM ITEMS
============

Register a custom item:

/bd register FireSword 5000 2500 false

Result:

custom-items:
  FireSword:
    material: IRON_SWORD
    max-durability: 5000

    repair:
      cost: 2500

    damage:
      weapon-hit: 1
      block-break: 1
      armor-hit: 1

    unbreakable: false

=================
UNBREAKABLE ITEMS
=================

Register:

/bd register AdminSword 5000 0 true

Result:

unbreakable: true

Unbreakable items never lose durability.

========
ENCHANTS
========

Reinforced

Reinforced I = 10%
Reinforced II = 20%
Reinforced III = 30%
Reinforced IV = 40%
Reinforced V = 50%

Effect:
Chance to ignore durability damage.

Fortified

Fortified I = +500
Fortified II = +1000
Fortified III = +1500
Fortified IV = +2000
Fortified V = +2500

Effect:
Increases maximum durability.

=============
ENCHANT BOOKS
=============

Apply Books:

1. Hold enchant book in main hand.
2. Hold BotchedDurability item in offhand.
3. Right-click.
4. Book is consumed.
5. Enchant is applied.

Books cannot downgrade existing enchants.

Example:

Reinforced V item
+
Reinforced III book

Result:

Book will not apply.

=========================
CUSTOM ITEM COMPATIBILITY
=========================

BotchedDurability has been tested with:

* Vanilla Minecraft Items
* Nexo Custom Items

Custom item support preserves:

* Custom Models
* Custom Names
* Durability Data
* Enchantments
* Persistence Across Restarts

Additional custom item plugins may be compatible but have not been officially tested.

=============
DAMAGE EDITOR
=============

Change the attack damage (and attack speed) of ANY item.

damage-editor:
  enabled: true

  materials:
    DIAMOND_SWORD:
      damage: 10
      speed: 1.6

    STICK:
      damage: 4

enabled
true  = Damage editor active
false = /bd damage disabled and no automatic updates

materials
Default damage for every item of that material.
speed is optional. Leave it out to keep the item's normal speed.

Custom items (registered with /bd register) can have their own values:

custom-items:
  FireSword:
    material: IRON_SWORD
    max-durability: 5000
    attack-damage: 14
    attack-speed: 1.8

How values work:
- Values are totals, exactly as shown in the tooltip.
  Vanilla diamond sword = 7 damage / 1.6 speed.
- Max damage 2048, max speed 1024.
- The plugin writes real Minecraft attributes, so attack cooldown,
  critical hits, Sharpness, Strength and armor still work normally.

Priority (highest first):
1. Manual edits with /bd damage set/add/multiply/speed
2. custom-items.<id>.attack-damage
3. damage-editor.materials.<MATERIAL>

Manual edits are stored on the item itself and are never
overwritten by config changes. Use /bd damage reset to clear one.

When items update:
- Player joins
- Item is held / swapped to main hand
- Item is picked up or crafted
- Inventory is closed
- /bd reload and /bd damage setdefault

If you remove a material or custom-item entry, items that got their
damage from that entry return to normal the next time they update.

====================
PLACEHOLDERAPI
====================

With PlaceholderAPI installed, these placeholders work anywhere
PlaceholderAPI is supported (scoreboards, tab lists, holograms...).

%botcheddurability_<slot>_<value>%

Slots:
held (or hand, mainhand), offhand, helmet, chestplate, leggings, boots

Values:
tracked      - yes or no
current      - current durability
max          - maximum durability
percent      - durability left, 0-100
reinforced   - Reinforced level (0 if none)
fortified    - Fortified level (0 if none)
repair_cost  - what /bd repair would cost for that item

Example:
%botcheddurability_held_percent%

===========
GUIDE BOOKS
===========

/guide or /bd guide opens the player guide. Add give for a physical
copy. Staff with botcheddurability.guide.staff can read the staff guide
with /bd guide staff. Books are never handed out automatically.

The book text is in plugins/BotchedDurability/guide.yml. Changes show
up as soon as you save the file.

=======================
SERVER COMPATIBILITY
=======================

BotchedDurability-<version>.jar (universal)
- Paper 1.21.8, 1.21.9, 1.21.10, 1.21.11
- Paper 26.1.x, 26.2, 26.3
- Java 21 or newer
- Paper forks such as Purpur work too. Plain Spigot is not supported.
