ToolGuardian

ToolGuardian

Warn players when their tools or armor are about to break — configurable thresholds, localized messages, MiniMessage formatting, and per-player toggles with persistence.

Features

• Monitor active equipment: main hand, off hand, helmet, chestplate, leggings, boots (toggle per slot).
• Configurable thresholds in percent (add as many as you like, each with its own message key and optional sound).
• Localized messages (lang/de.yml, lang/en.yml) using MiniMessage formatting.
• Placeholder support in messages: {item}, {percent}, {remaining}, {max}.
• Anti-spam: warn once per threshold per item until the next threshold is reached.
• Gamemode filter: by default only Survival/Adventure.
• Per-player toggle command with persistent storage (toggles.yml).

Requirements

• Paper (Minecraft 1.21.10)
• Java 21

Installation

1. Download the release JAR (or build from source, see below).
2. Put the JAR into your server's plugins folder.
3. Start or restart the server.
4. Optional: adjust plugins/ToolGuardian/config.yml and localization files under plugins/ToolGuardian/lang/.

Configuration

Default config.yml (you can add or remove thresholds freely):

language: de

enabled-gamemodes:
  - SURVIVAL
  - ADVENTURE

monitor:
  main-hand: true
  off-hand: true
  head: true
  chest: true
  legs: true
  feet: true

thresholds:
  - percent: 20
    message: warn.medium
  - percent: 10
    message: warn.low
  - percent: 5
    message: warn.critical
    sound: BLOCK_NOTE_BLOCK_BELL
    sound-volume: 1.0
    sound-pitch: 1.0

check-interval-ticks: 20

Notes:

• Thresholds should be listed in ascending order by percent.
• A sound plays only if configured on that threshold.
• The plugin checks at a fixed interval (20 ticks = 1s by default).

Localization

Two language files are provided: lang/de.yml and lang/en.yml. Example:

warn:
  medium: "<yellow><bold>Heads up:</bold></yellow> {item} at <yellow>{percent}%</yellow> durability (<gray>{remaining}/{max}</gray>)."
  low: "<gold><bold>Warning:</bold></gold> {item} at <gold>{percent}%</gold> durability (<gray>{remaining}/{max}</gray>)."
  critical: "<red><bold>CRITICAL:</bold></red> {item} only <red>{percent}%</red> durability left (<gray>{remaining}/{max}</gray>)!"
toggle:
  now-enabled: "<green>ToolGuardian warnings: <bold>ON</bold></green>"
  now-disabled: "<red>ToolGuardian warnings: <bold>OFF</bold></red>"
  usage: "<gray>Usage:</gray> <yellow>/toolguardian toggle</yellow>"
  no-permission: "<red>You don't have permission.</red>"

Placeholders are written as {item}, {percent}, {remaining}, {max} and can be styled with MiniMessage tags around them. The plugin converts these placeholders and resolves them at runtime.

Commands

• /toolguardian toggle (alias /tg): Toggle warnings for yourself.

Permissions

• toolguardian.toggle — default: true

How it works

• The plugin periodically scans configured slots. If an item has durability and enters a configured threshold (e.g., 20% → 10% → 5%), the player receives exactly one message per threshold step for that item. When the item changes or durability goes above the highest threshold again, the internal state resets, allowing future warnings as appropriate.

Troubleshooting

• No messages?
  • Ensure your gamemode is enabled in enabled-gamemodes.
  • Check that the slot (e.g., main-hand, head) is enabled under monitor.
  • Verify the item actually has durability.
• Placeholders appear literally?
  • Make sure you kept the curly-brace placeholders ({item}, {percent}, {remaining}, {max}) in your locale file.
  • Avoid conflicting chat formatters that strip MiniMessage formatting.
• No sound at critical?
  • Ensure the sound field exists on the desired threshold and uses a valid Bukkit sound name.