HTools - Time-Expiring Custom Tools for Paper & Folia
HTools is a high-performance, lightweight utility plugin for Minecraft 1.21.11 (Paper, Folia, Leaf, and PaperShredded) that introduces time-expiring "Evil" tools with unique custom mining abilities.The plugin currently features two distinct tools:
- Evil Axe: Features a chain-mining "timber" mechanic. Breaking a single log block automatically fells the entire connected tree.
- Evil Pickaxe: Features a 3x3 "excavator" mining mechanic. Breaking a block also mines the surrounding 3x3x1 area facing the player.
Technical Architecture and Optimizations
- Persistent PDC Data: All tool properties are written directly to item NBT using the Bukkit PersistentDataContainer API (tool_type and expires_at). This ensures the expiry data survives server restarts, player drops, /give commands, and inventory movements.
- Folia-Safe Global Timer: Instead of intensive per-player loops, a single global timer fans out countdown update scans to each player's local region thread. This provides thread safety on Folia and scales comfortably to hundreds of players.
- Zero Memory Footprint: The plugin does not cache active player data. Players who log out are instantly skipped during iterations, preventing potential memory leaks.
- Anti-Glitch Item Updates: Item updates never rewrite the active tool currently held in the player's main or off-hand, preventing the common client-side "item bobbing" visual glitch. Instead, the held tool's lore is refreshed only during switch events (hotbar selection, hand swapping, or server joining), which are moments when the client naturally re-equips the item. Off-hand/inventory items update smoothly via the background timer, and slot packets are sent to the client only when an active value changes.
- Native Thread Scheduling: All tasks are coordinated natively through Paper/Folia region schedulers. The same compiled JAR runs on Paper, Folia, or any hybrid fork without platform-specific checks.
Color and Formatting Support
Names, lore, and chat messages accept mixed formatting syntaxes within the same string:- MiniMessage: <gradient:#ff0000:#8b0000>, <red>, <bold>, etc.
- Hex Codes: &#ff0000, <#ff0000>, or bare #ff0000 values.
- Legacy Formatting: Standard &c, &7, and &l codes.
Commands and Permissions
| Command | Description | Permission |
| /htools give <player> <tool> [amount] | Gives a player an evil-axe or evil-pickaxe. | htools.admin (Default: OP) |
| /htools reload | Reloads the plugin configuration (config.yml). | htools.admin (Default: OP) |
Configuration (config.yml)
The configuration file allows you to define per-tool attributes and global behaviors:- Tool Settings: Customize the base material, display name, lore layout, custom enchantments, item flags, unbreakable status, durability-bar visibility, tool duration (days/hours/minutes/seconds), and mining behaviors (max blocks mined, timber limits, and area configurations).
- Global Settings: Control the background update interval, expired item removal options, and custom sound effects or alert messages triggered upon tool expiration.
Technical Considerations and Limitations
- Block Interception: Extra blocks broken via the tree-feller or 3x3 mining mechanic are broken natively and do not trigger separate BlockBreakEvent instances. Land-claim, anti-grief, and world-protection plugins are only consulted for the single initial block mined by the player (tracked at MONITOR priority to respect cancellations). If absolute land protection is required for all affected blocks, dedicated region API checks should be added.
- Folia Bounded Searching: The tree-feller search logic is designed with a strict max-blocks cap. This ensures that log-searching operations remain localized to the player's active region thread and do not trigger unexpected cross-region lag spikes.
