P-Pickaxe — Features README

Overview

P-Pickaxe is a plugin for Paper servers that creates evolving items. Players use an item normally, build progress through gameplay actions, and automatically receive rewards when configured goals are reached. The plugin was prepared for Paper 1.21.3, Java 21, and version 1.0.0.

The plugin does not need to rename the item or change the item's real lore to track evolution. Progress is saved inside the item itself and can be shown through commands, the actionbar, and the menu.

Summary

• What the plugin can do
• Commands
• Permissions
• How evolution works
• Progress types
• Menu and interface
• Rewards
• Available settings
• Plugin files
• Default evolving items
• Important notes

What the plugin can do

• Create evolving items by category, such as pickaxes, axes, shovels, hoes, swords, bows, crossbows, tridents, and armor.
• Track progress automatically when a player breaks blocks, kills entities, shoots projectiles, throws a trident, or takes damage while wearing armor.
• Evolve items through levels, with different progress goals and rewards at each stage.
• Apply vanilla enchantments and custom enchantments registered on the server.
• Run commands as evolution rewards, either as console or as the player, depending on the reward configuration.
• Show progress in the actionbar while the item is being used.
• Show the progress of the evolving item in the player's main hand through a command.
• Open a visual menu with categories, items, progress, levels, percentage, status, and the next reward.
• Use menu icons from common Minecraft materials or custom player heads.
• Reload settings, menu, languages, and evolutions without restarting the server.
• List enchantments recognized by the server and test whether a specific enchantment is recognized.
• Keep the best progress when items are combined through an anvil, smithing table, or grindstone.
• Support Portuguese and English messages through language files.

Commands

Player commands

Command	What it does
/evolutivos menu	Opens the evolving items menu.
/evolutivos progresso	Shows the progress of the evolving item in the main hand.
/evolutivos ajuda	Shows the player command help.

Player aliases: /ppickaxe, /pp, /pevoluir, and /evoluir.

Admin commands

Command	What it does
/evolutivosadmin recarregar	Reloads settings, menu, languages, and evolutions.
/evolutivosadmin encantamentos	Lists enchantments registered on the server.
/evolutivosadmin encantamentos filter	Lists registered enchantments that match the provided filter.
/evolutivosadmin reconhecer enchantment	Tests whether the plugin can recognize an enchantment by the provided name.
/evolutivosadmin ajuda	Shows the admin command help.

Admin aliases: /ppickaxeadmin, /ppadmin, and /evoluiradmin.

Permissions

Permission	Default	Allows
p_pickaxe.use	Everyone	Use the menu and view evolving item progress.
p_pickaxe.admin	Operators	Reload files, list enchantments, and test enchantment recognition.

How evolution works

• The item starts being tracked automatically when used, if that option is enabled.
• Each item has one or more ways to gain progress.
• When progress reaches a stage goal, the plugin applies the reward for that level.
• Each evolution can have multiple rewards in the same stage.
• When the item finishes all stages, it appears as complete in the command and in the menu.
• Progress is individual per item. Two identical items can have different levels and progress.
• The menu can show the next reward, status, current level, maximum level, and completion percentage.

Progress types

Type	How the player progresses	Usually used by
Breaking blocks	Gains progress by breaking blocks outside creative or spectator mode.	Pickaxes, shovels, hoes, and axes.
Killing entities	Gains progress when the item lands the final hit on an entity.	Swords and axes.
Shooting projectiles	Gains progress by shooting a bow or crossbow.	Bows and crossbows.
Throwing tridents	Gains progress by throwing a trident.	Tridents.
Taking damage	Gains progress by taking damage while wearing the armor piece.	Helmets, chestplates, leggings, and boots.

An item can accept more than one progress type. By default, axes evolve both by breaking blocks and by killing entities.

Menu and interface

• Main menu with evolving item categories.
• Category screen with the items from that category.
• Item screen with matching items found in the player's inventory.
• Page navigation, back button, and page information item.
• Configurable title, size, slots, filler item, and navigation items.
• Icons using Minecraft materials or custom heads.
• Display of owned amount, progress, level, percentage, status, and next reward.
• Menu messages and texts configurable by language.

Accepted menu placeholders: item, progress, required, percent, level, max_level, status, next_rewards, and progress_types.

Rewards

• Vanilla Minecraft enchantments.
• Custom enchantments registered on the server.
• Enchantments above the normal limit, if unsafe enchantments are enabled.
• A single command as a reward.
• Multiple commands in the same stage.
• Commands executed by the console or by the player, depending on the reward configuration.
• Friendly reward text for showing the reward in the menu as “Next reward”.

Accepted reward command placeholders: player, player_name, uuid, item, level, max_level, progress, and stage_level.

Available settings

• Active plugin language.
• Message prefix.
• Automatic evolving item initialization when used.
• Enable or disable progress actionbar.
• Actionbar update interval when breaking blocks.
• Allow or block enchantments outside normal limits.
• Debug mode.
• Separate menu configuration.
• Separate language configuration.
• Separate evolution configuration by category and material.

Plugin files

File or folder	Purpose
config.yml	General options, language, prefix, actionbar, unsafe enchantments, and debug.
menu.yml	Menu layout, titles, slots, icons, heads, names, and visual lore.
idiomas	Messages and menu texts in Portuguese and English.
evolucoes	Evolving item definitions by category and material.
plugin.yml	Name, version, commands, aliases, and permissions.

Default evolving items

The analyzed package contains 58 default evolutions.

Pickaxes

Item	Material	Progress	Default goals and rewards
Diamond Pickaxe	DIAMOND_PICKAXE	breaking blocks	400: Efficiency II • 1200: Unbreaking III • 2500: Fortune III
Golden Pickaxe	GOLDEN_PICKAXE	breaking blocks	80: Efficiency II • 240: Unbreaking I • 500: Fortune II
Iron Pickaxe	IRON_PICKAXE	breaking blocks	250: Efficiency I • 700: Unbreaking II • 1500: Fortune II
Netherite Pickaxe	NETHERITE_PICKAXE	breaking blocks	600: Efficiency III • 1800: Unbreaking III • 3500: Fortune III
Stone Pickaxe	STONE_PICKAXE	breaking blocks	150: Efficiency I • 450: Unbreaking I • 900: Efficiency II
Wooden Pickaxe	WOODEN_PICKAXE	breaking blocks	100: Efficiency I • 300: Unbreaking I • 700: Fortune I

Axes

Item	Material	Progress	Default goals and rewards
Diamond Axe	DIAMOND_AXE	breaking blocks, killing entities	350: Efficiency II • 1000: Sharpness IV • 2200: Unbreaking III
Golden Axe	GOLDEN_AXE	breaking blocks, killing entities	70: Efficiency II • 220: Sharpness II • 450: Unbreaking II
Iron Axe	IRON_AXE	breaking blocks, killing entities	220: Efficiency I • 650: Sharpness III • 1300: Unbreaking II
Netherite Axe	NETHERITE_AXE	breaking blocks, killing entities	500: Efficiency III • 1400: Sharpness V • 3000: Unbreaking III
Stone Axe	STONE_AXE	breaking blocks, killing entities	150: Efficiency I • 400: Sharpness II • 850: Unbreaking II
Wooden Axe	WOODEN_AXE	breaking blocks, killing entities	100: Efficiency I • 260: Sharpness I • 600: Unbreaking I

Shovels

Item	Material	Progress	Default goals and rewards
Diamond Shovel	DIAMOND_SHOVEL	breaking blocks	320: Efficiency II • 900: Unbreaking III • 1800: Silk Touch I
Golden Shovel	GOLDEN_SHOVEL	breaking blocks	60: Efficiency II • 180: Unbreaking I • 380: Efficiency III
Iron Shovel	IRON_SHOVEL	breaking blocks	200: Efficiency I • 550: Unbreaking II • 1100: Silk Touch I
Netherite Shovel	NETHERITE_SHOVEL	breaking blocks	450: Efficiency III • 1300: Unbreaking III • 2600: Silk Touch I
Stone Shovel	STONE_SHOVEL	breaking blocks	120: Efficiency I • 340: Unbreaking I • 700: Efficiency II
Wooden Shovel	WOODEN_SHOVEL	breaking blocks	80: Efficiency I • 220: Unbreaking I • 500: Silk Touch I

Hoes

Item	Material	Progress	Default goals and rewards
Diamond Hoe	DIAMOND_HOE	breaking blocks	320: Efficiency II • 900: Unbreaking III • 1800: Fortune III
Golden Hoe	GOLDEN_HOE	breaking blocks	60: Efficiency II • 180: Fortune II • 380: Unbreaking II
Iron Hoe	IRON_HOE	breaking blocks	200: Efficiency I • 550: Unbreaking II • 1100: Fortune II
Netherite Hoe	NETHERITE_HOE	breaking blocks	450: Efficiency III • 1300: Unbreaking III • 2600: Fortune III
Stone Hoe	STONE_HOE	breaking blocks	120: Efficiency I • 340: Fortune I • 700: Efficiency II
Wooden Hoe	WOODEN_HOE	breaking blocks	80: Efficiency I • 220: Fortune I • 500: Unbreaking I

Swords

Item	Material	Progress	Default goals and rewards
Diamond Sword	DIAMOND_SWORD	killing entities	140: Sharpness III • 320: Looting III • 650: Unbreaking III
Golden Sword	GOLDEN_SWORD	killing entities	30: Sharpness II • 90: Looting II • 200: Fire Aspect II
Iron Sword	IRON_SWORD	killing entities	90: Sharpness II • 220: Looting II • 480: Unbreaking II
Netherite Sword	NETHERITE_SWORD	killing entities	180: Sharpness IV • 420: Looting III • 800: Fire Aspect II
Stone Sword	STONE_SWORD	killing entities	60: Sharpness I • 150: Looting I • 320: Fire Aspect I
Wooden Sword	WOODEN_SWORD	killing entities	40: Sharpness I • 100: Looting I • 220: Unbreaking I

Bows

Item	Material	Progress	Default goals and rewards
Bow	BOW	shooting projectiles	80: Power I • 180: Unbreaking II • 320: Punch I • 480: Infinity I

Crossbows

Item	Material	Progress	Default goals and rewards
Crossbow	CROSSBOW	shooting projectiles	80: Quick Charge I • 180: Piercing II • 320: Multishot I • 500: Quick Charge III

Tridents

Item	Material	Progress	Default goals and rewards
Trident	TRIDENT	throwing tridents	50: Impaling II • 140: Loyalty II • 260: Unbreaking III • 420: Channeling I

Helmets

Item	Material	Progress	Default goals and rewards
Chainmail Helmet	CHAINMAIL_HELMET	taking damage	100: Protection I • 240: Respiration I • 420: Aqua Affinity I
Diamond Helmet	DIAMOND_HELMET	taking damage	200: Protection III • 480: Respiration III • 800: Aqua Affinity I
Golden Helmet	GOLDEN_HELMET	taking damage	70: Protection II • 160: Respiration II • 280: Aqua Affinity I
Iron Helmet	IRON_HELMET	taking damage	130: Protection II • 320: Respiration II • 550: Aqua Affinity I
Leather Helmet	LEATHER_HELMET	taking damage	80: Protection I • 180: Respiration I • 300: Aqua Affinity I
Netherite Helmet	NETHERITE_HELMET	taking damage	260: Protection IV • 600: Respiration III • 950: Aqua Affinity I
Turtle Helmet	TURTLE_HELMET	taking damage	180: Protection II • 380: Respiration III • 700: Aqua Affinity I

Chestplates

Item	Material	Progress	Default goals and rewards
Chainmail Chestplate	CHAINMAIL_CHESTPLATE	taking damage	110: Protection I • 260: Unbreaking II • 460: Thorns I
Diamond Chestplate	DIAMOND_CHESTPLATE	taking damage	230: Protection III • 540: Unbreaking III • 920: Thorns III
Golden Chestplate	GOLDEN_CHESTPLATE	taking damage	80: Protection II • 200: Unbreaking II • 340: Thorns I
Iron Chestplate	IRON_CHESTPLATE	taking damage	150: Protection II • 360: Unbreaking II • 620: Thorns II
Leather Chestplate	LEATHER_CHESTPLATE	taking damage	90: Protection I • 200: Unbreaking I • 350: Thorns I
Netherite Chestplate	NETHERITE_CHESTPLATE	taking damage	300: Protection IV • 700: Unbreaking III • 1150: Thorns III

Leggings

Item	Material	Progress	Default goals and rewards
Chainmail Leggings	CHAINMAIL_LEGGINGS	taking damage	110: Protection I • 260: Unbreaking II • 460: Swift Sneak I
Diamond Leggings	DIAMOND_LEGGINGS	taking damage	230: Protection III • 540: Unbreaking III • 920: Swift Sneak III
Golden Leggings	GOLDEN_LEGGINGS	taking damage	80: Protection II • 200: Unbreaking II • 340: Swift Sneak I
Iron Leggings	IRON_LEGGINGS	taking damage	150: Protection II • 360: Unbreaking II • 620: Swift Sneak II
Leather Leggings	LEATHER_LEGGINGS	taking damage	90: Protection I • 200: Unbreaking I • 350: Swift Sneak I
Netherite Leggings	NETHERITE_LEGGINGS	taking damage	300: Protection IV • 700: Unbreaking III • 1150: Swift Sneak III

Boots

Item	Material	Progress	Default goals and rewards
Chainmail Boots	CHAINMAIL_BOOTS	taking damage	100: Protection I • 230: Feather Falling II • 380: Depth Strider I
Diamond Boots	DIAMOND_BOOTS	taking damage	200: Protection III • 480: Feather Falling IV • 800: Depth Strider III
Golden Boots	GOLDEN_BOOTS	taking damage	70: Protection II • 160: Feather Falling III • 280: Depth Strider II
Iron Boots	IRON_BOOTS	taking damage	130: Protection II • 320: Feather Falling III • 550: Depth Strider II
Leather Boots	LEATHER_BOOTS	taking damage	80: Protection I • 180: Feather Falling II • 300: Depth Strider I
Netherite Boots	NETHERITE_BOOTS	taking damage	260: Protection IV • 600: Feather Falling IV • 950: Depth Strider III

Important notes

• The plugin was built for Paper 1.21.3 and Java 21.
• The final JAR identified in the package is P-Pickaxe-1.0.0.jar.
• Progress does not necessarily appear in the item's real name or lore; it is checked through the menu, actionbar, and commands.
• For custom enchantments, the enchantment must be registered on the server to be recognized.
• Players in creative or spectator mode do not generate progress through the monitored actions.
• The listed goals and rewards are the default settings included in the JAR and can be adjusted in the evolution files.