Skip to content

Souls And Trackers

neoramm edited this page Nov 5, 2026 · 1 revision

Souls and Trackers

Trackers are special items that make an item count things: players killed, mobs killed, blocks broken, fish caught, or souls. The count shows at the end of the item tooltip, like Mob kills: 120.

Souls are a count that enchantments can also spend: an enchantment can need souls to activate and use some up every time.

Trackers

items:
  stattrak:
    kind: tracker
    stat: player-kills
    applies-to: ["#minecraft:swords", "#minecraft:axes", "minecraft:bow"]
    item:
      material: NAME_TAG
      name: "<red>StatTrak"

The player drags the tracker onto the item. From then on the item counts:

stat Counts
player-kills Players killed while holding the item.
mob-kills Mobs and animals killed while holding the item.
blocks Blocks broken with the item.
fish Fish caught with the rod.
souls Souls earned from kills (see below).

An item can have several trackers, one of each stat. The kills count when the item is in the main hand at the moment of the kill, also with bows and tridents.

The tooltip lines are in the display section of items.yml. %amount% is the count. Delete a line to hide it.

display:
  trackers:
    player-kills: "<red>Player kills: <white>%amount%"
    mob-kills: "<red>Mob kills: <white>%amount%"
    blocks: "<yellow>Blocks broken: <white>%amount%"
    fish: "<aqua>Fish caught: <white>%amount%"
    souls: "<dark_aqua>Souls: <white>%amount%"

Souls

An item collects souls once it has a soul tracker (stat: souls). Each kill made with it adds souls:

souls:
  per-player-kill: 1
  per-mob-kill: 0

Soul gems move souls around:

items:
  soul-gem:
    kind: soul-gem
    value: 10
    item:
      material: EMERALD
      name: "<dark_aqua>Soul Gem <gray>(%value% souls)"

Dragging a gem onto an item with a soul tracker adds its value in souls. Players can also turn souls of the held item back into a gem:

Command What it does
/metaenchants souls Shows the souls of the held item.
/metaenchants souls withdraw <amount> Takes that many souls off the held item and gives a soul gem with them. Uses the first soul-gem of items.yml.
/metaenchants souls set <amount> Administrators only: sets the souls of the held item. It also gives it a soul tracker if it had none.

The permission of the first two is metaenchants.command.souls (everyone by default).

Enchantments that use souls

Enchantments have a condition and two actions for souls. They work with the item that carries the enchantment, so they can be used in the triggers of enchantments (not of sets).

Element What it does Example
souls condition Checks the souls of the item. False if the item has no soul tracker. souls: ">= 5"
remove-souls action Takes souls off the item. remove-souls: 5
add-souls action Adds souls to the item. add-souls: 1

This enchantment hits harder, but each hit costs five souls:

name: "Soul Strike"
rarity: epic
max-level: 3
supported-items: ["#minecraft:swords"]
slots: [mainhand]
triggers:
  strike:
    on: attack
    if:
      - souls: ">= 5"
    do:
      - remove-souls: 5
      - set-damage: "{damage} * (1 + {level} * 0.15)"

The amounts can be calculations, like remove-souls: "{level} * 2".

Messages

Message When Replaced words
souls-none souls without an item with a soul tracker in the hand.
souls-show The souls of the held item. %amount%
souls-no-gem souls withdraw when items.yml has no soul gem.
souls-missing souls withdraw asks for more souls than the item has. %amount% (what it has)
souls-withdrawn Souls became a gem. %amount%

From AdvancedEnchantments

The migration converts souls too: ADD_SOULS and REMOVE_SOULS become add-souls and remove-souls, %souls on item% becomes the souls condition, and souls: 5 in a level becomes a souls: ">= 5" condition plus remove-souls: 5.

Clone this wiki locally