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:

plugins/MaxTools/

5. Edit the configuration files as needed.
6. 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 |
| ------------------------------------------------ | ------------------------------------------------------------------------- | --------------------------------- |
| /met toolinfo [gui/text/legacy] | Shows information about the tool in hand. | maxtools.toolinfo |
| /met menu | Opens the main evolution menu. | maxtools.menu |
| /met reload | Reloads configuration, menus, languages, evolution, and Discord settings. | maxtools.admin.reload |
| /met preview | Opens an admin preview of the evolution system. | maxtools.admin.preview |
| /met discordtest | Sends a test message to the Discord webhook. | maxtools.admin.discordtest |
| /met testtool <material> [ability/all] [level] | Creates a test evolving tool. | maxtools.admin.testtool |
| /met cleartesttool [id] | Removes the test tool in hand or clears a test tool ID. | maxtools.admin.cleartesttool |
| /met admintoolsremove confirm | Purges all registered custom tools. | maxtools.admin.admintoolsremove |
| /met lang | Opens the language selector menu. | maxtools.admin.lang |
| /met sync | Syncs the tool in hand with the current milestones. | maxtools.admin.sync |

Main command:

/maxtools

Alias:

/met

---

Permissions

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

---

⚙️ Configuration Files

MaxTools includes several editable files:

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

Generated runtime files:

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

---

Tracked Tools

You can configure which tools are allowed to evolve.

Example:

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:

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:

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

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

EFFICIENCY
FORTUNE
SILK_TOUCH
MENDING
UNBREAKING

---

Progress Display

Tools can show their progress directly in the item name.

Example:

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 |
| ----------- | ---------------------- |
| {current} | Current progress. |
| {target} | Next milestone target. |
| {unit} | Progress unit. |

---

Placeholders

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

Common placeholders:

| Placeholder | Description |
| --------------- | ----------------------- |
| {player} | Player name. |
| {player_uuid} | Player UUID. |
| {tool} | Readable tool name. |
| {tool_type} | Bukkit material name. |
| {blocks} | Current mined blocks. |
| {ability} | Unlocked ability. |
| {reward} | Milestone reward. |
| {server} | Configured server name. |
| {plugin} | Plugin name. |
| {current} | Current progress. |
| {target} | Current target. |
| {tier} | Calculated rarity tier. |
| {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:

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

---

Languages

Included languages:

• English
• Spanish

Players or admins can use:

/met lang

to open the language selector.

If language profile sync is enabled, the plugin can automatically sync config.yml and menus.yml with the selected language profile.

---

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

2. 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

/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.