MaxTools

DISCORD:
https://discord.com/invite/Vr46JHm2kd



WIKI:
https://docs.maxking.lat/

MaxTools
MaxTools is a Paper plugin that turns regular tools into evolving tools.
As players mine blocks with compatible tools, the plugin tracks their progress, updates the item name and lore, unlocks configurable milestones, grants special abilities, opens custom GUI menus, and can send Discord webhook notifications.

Perfect for Survival, SMP, RPG, Lifesteal, BoxPvP, and custom progression servers.

Features

• Evolving tools with block mining progress
• Fully configurable milestones
• Unlockable special abilities
• Custom item names and lore
• Progress display directly on the tool
• GUI menus for progress, milestones, abilities, and stats
• SQLite storage for registered custom tools
• Anti-farm system for player-placed blocks
• Discord webhook support
• Multi-language support
• Admin preview and testing tools
• Configurable menus, sounds, messages, and layouts

How It Works
When a player breaks a block with a compatible tool, MaxTools checks if the tool can evolve.
If the block is valid, the plugin increases the tool progress, updates its display, and checks if the player reached a new milestone.

Milestones can unlock:

• Enchantments
• Special abilities
• Progress tiers
• Custom rewards through configuration

The tool data is stored directly inside the item using PersistentDataContainer, while registered custom tools are also saved in SQLite.

Special Abilities
MaxTools includes several configurable abilities:

• Self Repair — Repairs durability after walking a certain distance.
• Auto Smelt — Automatically smelts compatible block drops.
• Telepathy — Sends drops directly to the player inventory.
• Drill — Breaks blocks in an area.
• Hammer — Area-breaking ability variant.
• Vein Miner — Breaks connected blocks of the same type.
• XP Boost — Increases natural XP drops.
• Haste — Gives passive Haste while holding the tool.
• Saturation Pulse — Restores hunger and saturation.
• Luck Surge — Temporarily increases compatible drops.
• Momentum — Grants stacking Haste by breaking blocks quickly.

Abilities can be enabled, disabled, limited by material, given cooldowns, chances, amounts, and custom triggers.

Requirements

• Paper 1.21+
• Java 21 or higher
• Minecraft server with plugin support
• Maven only required if compiling from source

Installation

1. Download the plugin .jar.
2. Place it inside your server's plugins/ folder.
3. Restart the server.
4. Open the generated folder:

1. Edit the configuration files as needed.
2. Use: /met reload

to reload the plugin after changing configuration files.

REMEMBER TO CHECK THE WIKI TO STAY UP-TO-DATE ON PERMISSIONS AND COMMANDS

Commands:

Command	Description	Permission
Code (Text): /met toolinfo [gui/text/legacy]	Shows information about the tool in hand.	Code (Text): maxtools.toolinfo
Code (Text): /met menu	Opens the main evolution menu.	Code (Text): maxtools.menu
Code (Text): /met reload	Reloads configuration, menus, languages, evolution, and Discord settings.	Code (Text): maxtools.admin.reload
Code (Text): /met preview	Opens an admin preview of the evolution system.	Code (Text): maxtools.admin.preview
Code (Text): /met discordtest	Sends a test message to the Discord webhook.	Code (Text): maxtools.admin.discordtest
Code (Text): /met testtool <material> [ability/all] [level]	Creates a test evolving tool.	Code (Text): maxtools.admin.testtool
Code (Text): /met cleartesttool [id]	Removes the test tool in hand or clears a test tool ID.	Code (Text): maxtools.admin.cleartesttool
Code (Text): /met admintoolsremove confirm	Purges all registered custom tools.	Code (Text): maxtools.admin.admintoolsremove
Code (Text): /met lang	Opens the language selector menu.	Code (Text): maxtools.admin.lang
Code (Text): /met sync	Syncs the tool in hand with the current milestones.	Code (Text): maxtools.admin.sync

Permissions

Permission	Default	Description
Code (Text): maxtools.admin	OP	Gives full access to all admin and user permissions.
Code (Text): maxtools.toolinfo	true	Allows Code (Text): /met toolinfo .
Code (Text): maxtools.menu	true	Allows opening the main menu.
Code (Text): maxtools.admin.reload	OP	Allows reloading the plugin.
Code (Text): maxtools.admin.preview	OP	Allows opening the admin preview.
Code (Text): maxtools.admin.discordtest	OP	Allows sending Discord test messages.
Code (Text): maxtools.admin.testtool	OP	Allows creating test tools.
Code (Text): maxtools.admin.cleartesttool	OP	Allows removing test tools.
Code (Text): maxtools.admin.admintoolsremove	OP	Allows purging registered custom tools.
Code (Text): maxtools.admin.lang	OP	Allows opening the language selector.
Code (Text): maxtools.admin.sync	OP	Allows syncing tools with the current evolution configuration.

⚙️ Configuration Files
MaxTools includes several editable files:

File	Purpose
Code (Text): config.yml	Main settings, language, Discord, update checker, bStats, and evolution lore.
Code (Text): evolution.yml	Tracked tools, block counting rules, milestones, progress display, and abilities.
Code (Text): menus.yml	GUI texts, layouts, materials, sounds, and visual placeholders.
Code (Text): lang/messages_en.yml	English messages, tool names, and enchantment names.
Code (Text): lang/messages_es.yml	Spanish messages, tool names, and enchantment names.

File / Folder	Purpose
Code (Text): custom_tools.db	SQLite database for registered custom tools.
Code (Text): player-placed-blocks.yml	Anti-farm data for player-placed blocks.
Code (Text): language_profiles/	Editable language profiles for config and menu syncing.

Tracked Tools
You can configure which tools are allowed to evolve.

Example:

Code (YAML):

tracked-tools :
 - DIAMOND_PICKAXE
  - NETHERITE_PICKAXE
  - DIAMOND_AXE
  - NETHERITE_SHOVEL

By default, the plugin supports pickaxes, axes, and shovels from common vanilla tiers.

Milestones
Milestones are configured in evolution.yml.

Example:

Code (YAML):

milestones:
  milestone-1:
    blocks : 100
    enchantment : EFFICIENCY
    level : 3
  milestone-2:
    blocks : 300
    unlock-abilities :
     - self-repair

Each milestone can apply enchantments or unlock abilities.

Supported enchantment aliases include:

Code (Text):

DURABILITY -> UNBREAKING
DIG_SPEED -> EFFICIENCY
LOOT_BONUS_BLOCKS -> FORTUNE

You can also use valid Bukkit/Paper enchantment names such as:

Code (Text):

EFFICIENCY
FORTUNE
SILK_TOUCH
MENDING
UNBREAKING

Progress Display
Tools can show their progress directly in the item name.

Example:

Code (YAML):

progress-display:
  enabled : true
  format : "&8« &#FFD700{current} &8/ &#FFAA00{target} &7{unit} &8»"
  completed-format : "&8« &#55FF55&lMAXED &8»"

Available placeholders include:

Placeholder	Description
Code (Text): {current}	Current progress.
Code (Text): {target}	Next milestone target.
Code (Text): {unit}	Progress unit.

Placeholders
MaxTools supports placeholders for menus, Discord embeds, progress displays, and messages.

Common placeholders:
[/CENTER]

Placeholder	Description
Code (Text): {player}	Player name.
Code (Text): {player_uuid}	Player UUID.
Code (Text): {tool}	Readable tool name.
Code (Text): {tool_type}	Bukkit material name.
Code (Text): {blocks}	Current mined blocks.
Code (Text): {ability}	Unlocked ability.
Code (Text): {reward}	Milestone reward.
Code (Text): {server}	Configured server name.
Code (Text): {plugin}	Plugin name.
Code (Text): {current}	Current progress.
Code (Text): {target}	Current target.
Code (Text): {tier}	Calculated rarity tier.
Code (Text): {percent}	Progress percentage.

Discord Webhooks
MaxTools can send Discord notifications when players unlock milestones or abilities.

Supported Discord events:

• 
  
  
  • Milestone unlocked
  • Ability unlocked
  • Test message

Webhook embeds are configurable and support placeholders such as:

Code (Text):

{player}
{tool}
{blocks}
{ability}
{reward}
{server}
{timestamp}

Languages
Included languages:

• 
  
  
  • English
  • Spanish

Players or admins can use: /met lang

Storage
MaxTools stores tool data in two ways:

1. 
   
   
   • PersistentDataContainer inside the item
     • Mined blocks
     • Unlocked abilities
     • Last applied milestone
     • Base name
     • Progress name
     • Managed lore lines
     • Ability activation counters
     • Custom tool ID
     • Test tool data
   • Plugin files and database
     • custom_tools.db
     • player-placed-blocks.yml

This helps keep tools persistent and protected from invalid duplicates.

Important Notes

• 
  
  
  • If you change milestones or ability rewards, use /met sync on existing tools.
  • If you use abilities like Drill, Hammer, or Vein Miner, test them with your protection or claims plugin.
  • The plugin can apply enchantment levels above vanilla limits.
  • Keep allowed-mentions.parse: [] in Discord settings to avoid accidental mass pings.
  • /met admintoolsremove confirm is destructive. Use it carefully and always make backups.
  • Test tools are designed for QA and visual testing.

Useful Admin Examples

Code (Text):

/met toolinfo gui
/met menu
/met testtool DIAMOND_PICKAXE all 5000
/met testtool NETHERITE_PICKAXE vein-miner 5000
/met cleartesttool
/met admintoolsremove confirm
/met sync
/met reload

Support
If you find a bug or need help with configuration, please provide:

• 
  
  
  • Server version
  • Java version
  • Plugin version
  • Console error, if any
  • Your config.yml or relevant configuration section

This helps solve issues faster.