Give every weapon and tool a story — without changing Minecraft balance.

LegacyTools — Minecraft Tool & Weapon Leveling Plugin

LegacyTools is a lightweight, configurable Minecraft tool progression and weapon leveling plugin for PaperMC. It tracks kills, mined blocks, chopped logs, and dug blocks separately for every item, then unlocks cosmetic titles displayed in the item's lore.

A sword can become a Warrior. A pickaxe can become a Deep Delver. A trident can build its own legacy — including kills made while thrown. Progress belongs to the item, not the player.

Built for survival, SMP, RPG, and progression servers, LegacyTools creates collectible equipment without damage bonuses, mining boosts, custom attributes, pay-to-win mechanics, or a database.

Features

• True per-item progression stored on each individual item.
• Cosmetic and balance-safe: no changes to damage, speed, durability, drops, enchantments, or attributes.
• Modern weapon support: swords, maces, spears, and tridents.
• Thrown trident tracking: progress remains on the projectile item and returns through pickup or Loyalty.
• Tool tracking: logs chopped, blocks mined, optional ore-only mining, and shovel-compatible blocks dug.
• Configurable milestones: thresholds, title IDs, text, gradients, actions, units, and tracking rules.
• Clean tooltips: an optional blank line separates titles from item names or enchantments.
• Private unlock feedback: BossBar, action bar above the hotbar, player-only chat, and sound.
• Persistent data: Paper PersistentDataContainer is the source of truth, never visible lore.
• Safe item operations: anvils, grindstones, smithing, and crafting repair preserve the best valid progress.
• Event-driven performance: no repeating inventory scans, SQL, telemetry, or external storage.
• Adventure MiniMessage: modern colors, gradients, and text styling.
• Live reload: update configuration and messages without restarting.

How it works

1. A supported weapon or tool records a valid use.
2. Its hidden counter reaches a configured milestone.
3. The newest unlocked title appears in the item's lore.
4. The owner receives the enabled private notifications.
5. The data travels with that exact item.

Renaming an item does not reset it. Chests, shulkers, hoppers, ender chests, trades, death drops, and server restarts do not detach its legacy.

Supported weapons and tools

Category	Supported items	Default activity
Sword	Wooden, Stone, Iron, Golden, Diamond, Netherite	Monster kills
Mace	Mace	Monster kills
Spear	Wooden, Stone, Copper, Iron, Golden, Diamond, Netherite	Monster kills
Trident	Trident, including thrown kills	Monster kills
Axe	Wooden, Stone, Iron, Golden, Diamond, Netherite	Logs, wood, stems, and hyphae
Pickaxe	Wooden, Stone, Iron, Golden, Diamond, Netherite	All blocks or ores only
Shovel	Wooden, Stone, Iron, Golden, Diamond, Netherite	Shovel-compatible blocks

Player kills, axe mob kills, Creative-mode counting, ore-only mining, and complete categories can be enabled or disabled independently.

Unsupported by design: bows, crossbows, fishing rods, hoes, shears, and flint and steel.

In-game result

A configured milestone produces a compact tooltip block beneath the item's normal name and enchantments:

Warrior
Killed:
100 monsters

Only the latest unlocked milestone is rendered. Real progress remains hidden, keeping the tooltip clean and making every new title feel meaningful.

Installation

Requirements

• PaperMC 26.2
• Java 25
• No required plugin dependencies
• No database

Setup

1. Download LegacyTools-1.0.0.jar from the latest release.
2. Copy it to the server's plugins/ directory.
3. Restart the Paper server.
4. Customize plugins/LegacyTools/config.yml and messages.yml.
5. Run /legacytools reload after changes.

Configuration

The generated configuration is ready to use and fully commented:

lore:
  enabled: true
  disable-italic: true
  blank-line-before: true
  lines:
    - "{title}"
    - "<dark_gray>{action}"
    - "<gray>{milestone} {unit}"

hotbar:
  enabled: true
  duration-ticks: 60

chat:
  enabled: false

titles:
  trident:
    enabled: true
    action: "Killed:"
    track:
      monsters: true
      players: false
    levels:
      100:
        id: tidecaller
        title: "<gray>Tidecaller"
      500:
        id: stormpiercer
        title: "<green>Stormpiercer"
      1000:
        id: sea_legend
        title: "<gradient:#00e5ff:#0066ff>Sea Legend"

Lore placeholders

Placeholder	Meaning
{title}	Formatted unlocked title
{action}	Category action such as Killed: or Mined:
{milestone}	Required count for the title
{unit}	Configured singular or plural unit
{item}	Readable material name
{tool_type}	Category key

Titles and messages support Adventure MiniMessage.

Unlock notifications

Channel	Scope	Default
BossBar	Only the player who unlocked the title	Enabled
Action bar / hotbar	Above that player's inventory hotbar	Enabled
Private chat	Only that player; never a global broadcast	Disabled
Sound	Only that player	Enabled

All notification text is editable in messages.yml.

Commands and permissions

Command	Permission	Description
/legacytools reload	legacytools.reload	Reloads both YAML files and refreshes supported items held by online players

The permission defaults to server operators.

Reliable per-item storage

LegacyTools stores tool_type, current_progress, current_tier, title_id, a schema version, and an internal managed-lore count directly on the item.

The plugin removes and replaces only lore lines it owns. Translations, gradients, anvil names, and edited messages never become progression data.

The strongest valid record is preserved through:

• anvil rename, repair, and combine results;
• grindstone results;
• smithing upgrades;
• crafting repair results.

Creative and Spectator progression is disabled by default to prevent duplicated Creative items from manufacturing progress.

Performance and privacy

LegacyTools runs only for relevant Paper events: entity deaths, block breaks, prepared inventory results, player joins, and configuration reloads.

• No repeating inventory scans
• No SQL or external storage
• No network requests or telemetry
• No unsafe NBT libraries
• Minimal metadata per tracked item

FAQ

Does it make equipment stronger?

No. Progression is entirely cosmetic and never changes gameplay statistics.

Is progress stored per player?

No. It belongs to the exact item and travels to its next owner.

Do anvil names or upgrades erase progress?

No. Supported anvil, grindstone, smithing, and crafting operations retain the best valid record.

Are thrown trident kills counted?

Yes. The trident projectile's own ItemStack is updated, so progress returns with pickup or Loyalty.

Can titles and thresholds be changed?

Yes. Categories, milestones, IDs, text, gradients, lore, tracked actions, notifications, and sounds are configurable.

Does it require PlaceholderAPI, Vault, ProtocolLib, or a database?

No. LegacyTools has no required plugin dependencies.

Build from source

git clone https://github.com/antehor/LegacyTools.git
cd LegacyTools
mvn clean verify

Output: target/LegacyTools-1.0.0.jar

Project links

• Latest release
• Changelog
• Bug report
• Feature request
• Contributing guide
• Security policy

Кратко на русском

LegacyTools — косметический плагин прокачки оружия и инструментов для PaperMC. Каждый меч, молот, копьё, трезубец, топор, кирка или лопата хранит собственный прогресс и получает настраиваемые титулы.

Плагин не меняет характеристики предметов. Прогресс находится внутри самого предмета, переживает рестарты и переносится вместе с ним. BossBar, строка над хотбаром, личный чат и звук настраиваются отдельно.

License

LegacyTools is open-source software released under the MIT License.

---

LegacyTools · Cosmetic item progression for Minecraft Paper servers
Star the repository if LegacyTools improves your server.