Tools

A tool is the heart of the plugin. Each tool earns currency from its own action, then spends it in the tool's menu.

Supported tools

Each tool's material, currency name, earn rates, enchants, and effects live in its own file under tools/. The pickaxe.yml file has the full schema documentation, and the other files point back to it.

How earning works

Every tool has an earn-from list. The list maps an action to a currency amount. You stay in full control of the economy.

• A pickaxe can pay one amount for stone and a bigger amount for diamond ore.
• A sword pays per mob type.
• A fishing rod pays per caught item.
• Anything not on the list pays nothing.

If CustomFishing is installed, the fishing rod hooks its events automatically, so currency, quests, and the FISH_CAUGHT stat all still advance for vanilla catches and CustomFishing's own custom fish. Each catch counts exactly once, whether or not CustomFishing's trigger-fish-event option is on. Telekinesis, auto-sell, and the item-drop-boost effect work on any catch that CustomFishing drops in the water; loot it puts straight into the inventory still counts but those three effects cannot act on it.

A custom fish can have its own earn rate. Add a quoted plugin id as the key: "customfishing:golden_cod": 20, "itemsadder:mypack:golden_cod": 20, or "oraxen:golden_cod": 20. A custom catch checks its plugin ids first and falls back to its material, so a cod-based custom fish with no line of its own pays the COD rate. Quests can tell vanilla and custom fish apart too, see Quests.

What the lore can show

The lore can list more than the balance. Each part below is turned on or off with a display.lore-show-... option in config.yml.

• The tool's enchant levels.
• The live bonus of upgradable effects, shown as a percentage. For example, a currency multiplier at +25%.
• The settings, with each on/off toggle as a green check or red cross, plus the active mining radius.
• The tool's lifetime statistics: blocks mined, mobs killed, damage dealt, and fish caught. Each item keeps its own counters, and only counters above zero are listed, so a sword never shows a blocks row.

Choosing which statistics a tool tracks

Each tool file has a statistics block that decides which of the four lifetime counters it tracks. This is what keeps a sword from ever counting blocks mined, or a pickaxe from counting mobs killed.

statistics:
  enabled: true
  counters:
    - MOBS_KILLED
    - DAMAGE_DEALT
  blocks:
    mode: none
    list: []

Upgrading a tool

While holding a tool, sneak and right-click to open the menu. From there a player can:

• Buy Enchantments with the tool's balance.
• Unlock and upgrade Effects like autosmelt or radius mining.
• Toggle effects and pick a mining radius under Settings.
• Track the Quests for that tool.
• Open the server Leaderboards.

See Menus for a tour of each page.

Customizing enchants

You decide which enchants a tool offers. Open the tool file, find the enchants block, and add an entry. Each entry needs a max-level and a cost-curve (one price per level, so the list length matches max-level).

enchants:
  EFFICIENCY:
    max-level: 10
    cost-curve: [500, 1000, 2000, 4000, 8000, 16000, 32000, 64000, 128000, 256000]
  UNBREAKING:
    max-level: 3
    cost-curve: [5000, 15000, 50000]

A new entry shows up in the enchant menu and the tool lore on the next /et reload.

The enchants list and the currency earn-from list are yours to edit. The plugin keeps them exactly as you write them across reloads and updates, so entries you add are never wiped. Buying is always done in the enchant menu; the lore only displays the levels you own.

The multi-tool

The multi-tool is one tool that does the job of several. It changes shape to match the work:

• Break dirt and it becomes a shovel.
• Chop a log with that shovel and it becomes an axe.
• Mine stone and it becomes a pickaxe.
• Kill a mob and it becomes a sword.

Only the item's shape, its fixed enchants, and its durability change. The balance, upgrades, settings, and quest progress all stay put, because it is always the same tool. Give one with:

/et give <player> default_multi_tool

Setting up the shapes

Shapes live in the multi-tool block of tools/multi_tool.yml. Each shape says what item it turns into, what blocks it handles, and what enchants it always carries.

multi-tool:
  enabled: true
  morph-on: start
  unbreakable: true
  durability: -1
  default-form: pickaxe
  forms:
    axe:
      material: NETHERITE_AXE
      enchants:
        EFFICIENCY: 5
      matches:
        - "*_LOG"
        - "*_PLANKS"
    sword:
      material: NETHERITE_SWORD
      on-kill: true
      enchants:
        SHARPNESS: 5
      matches:
        - "COBWEB"

Fixed tools

A fixed tool is a finished item. It has no menu, no balance, no upgrades, and no quests. Everything it owns is written in its file. Use one as a reward, a kit item, or a crate prize.

Set it in any tool file:

fixed: true
unbreakable: false
durability: 1561
lore:
  - ""
  - "<muted>Changes shape to fit the job.</muted>"

A ready-made one ships as tools/fixed_multi_tool.yml: a fixed multi-tool that still changes shape and carries a set list of enchants per shape.

/et give <player> fixed_multi_tool

Custom items from ItemsAdder or Oraxen

A tool can wear a custom item's texture instead of its plain material. Two keys, in any tool file:

custom-item-provider: "itemsadder"
custom-item-id: "mypack:ruby_pickaxe"

Use oraxen with the plain item id for Oraxen. Only the look is taken, so the tool keeps its own name, lore, balance, and progress: you can restyle a tool without touching anyone's upgrades.

A different skin per shape

The same two keys work inside a multi-tool shape, so the pickaxe shape, the shovel shape and the axe shape can each carry their own texture. Write them under the shape, in the forms list:

multi-tool:
  default-form: pickaxe
  forms:
    axe:
      material: NETHERITE_AXE
      custom-item-provider: "itemsadder"
      custom-item-id: "mypack:ruby_axe"
      matches:
        - "*_LOG"
    shovel:
      material: NETHERITE_SHOVEL
      custom-item-provider: "itemsadder"
      custom-item-id: "mypack:ruby_shovel"
      matches:
        - "DIRT"
    pickaxe:
      material: NETHERITE_PICKAXE
      custom-item-provider: "itemsadder"
      custom-item-id: "mypack:ruby_pickaxe"
      matches:
        - "*"

The tool now wears the ruby pickaxe on stone, the ruby shovel on dirt, and the ruby axe on logs, while staying one tool with one balance and one set of upgrades.

A shape that names no skin wears the tool's own look instead, so a skinned shape never leaves its texture behind on the next one. On a plain resource pack, use custom-model-data on the shape instead of the two ItemsAdder keys: -1 keeps the tool's own model data, 0 gives that shape none.

Custom images inside your text

An ItemsAdder font image or an Oraxen glyph can be shown anywhere the plugin writes text: a tool name, a lore line, a menu, a message. Write the image name between two colons, exactly as it is named in your pack:

lore:
  - "<gray>Shift + :right_click: to open the menu"

The picture replaces the placeholder in game. A name neither plugin knows is left as you typed it, so nothing breaks if the pack changes.

Turn it off in config.yml if you use : characters in your text and want them left alone:

display:
  font-images: false

Keeping tools out of vanilla stations

By default a tool cannot be put into an anvil, an enchanting table, a grindstone, a smithing table, or a crafting grid. Without that, a player could stack vanilla enchants on top of the ones they bought, or grind the tool down. Dropping a tool also takes two presses, so a mistimed key does not throw a maxed tool on the floor.

All of it is switchable under protection in config.yml. See Configuration.

Progress is saved on the item

A tool's currency, enchants, effects, settings, and quest progress all live on the item. The tool keeps everything through death, dropping, trading, and server restarts.