TierTags

Overview

TierTags

Run a tier list server without spreadsheets: testers set a tier in game and it shows everywhere

Your testers run /tier set Notch sword HT2. From that moment Notch has an HT2 tag above their head and in the tab list, sits at the right place in /tierlist sword, shows up in PlaceholderAPI placeholders, and lands in a JSON file your website can read.

Ladders (sword, axe, crystal, UHC, SMP, building, anything) and tiers (LT5 to HT1, or bronze to diamond, or your own) are defined in the config. The plugin does not care what they are called.

Every player's tier in front of their name, coloured per tier.

Latest version

1.2.0

Server

Paper or Purpur, Java 21

BuiltByBit

TierTags on BuiltByBit

Features

Why server owners pick it

• One command updates the tag, the tab list, the tier list and the placeholders
• Any ladders and any tier names, all set in the config
• A JSON export your website can read
• PlaceholderAPI support for scoreboards and other plugins
• SQLite built in, nothing else to install

What makes it different

• One command updates the nametag, the tab list, the tier list, the placeholders and the JSON export together, so nothing drifts out of sync
• Ladders and tier names are free text in the config, not a fixed set
• Testers get their own permission (tiertags.tester) without reload or export rights

Works with

• Paper or Purpur 1.21.11 (or newer 1.21.x), Java 21+
• PlaceholderAPI optional
• Works next to other nametag plugins that use teams only if they leave players in no team; if you already use a tab/nametag plugin, set display.enabled to false and use the placeholders in it instead
• No DRM, no licence key and no licence server; the code is not obfuscated

What you get

• New in v1.3.0: Overall ranking: /tierlist overall ranks everybody by the sum of their tier points across all ladders
• New in v1.3.0: Leaderboard and rank placeholders: top players per ladder and overall, for holograms and scoreboards, answered from memory so they cost nothing
• New in v1.3.0: Tester role: tiertags.tester can set and remove tiers without reload and export rights
• Any number of ladders, any tier names, each tier with a colour and a point value
• Best tier shown above the head and in tab through scoreboard teams; players sort by tier in tab
• Global points: every ladder's tier points summed, for a "best overall" ranking
• /tierlist per ladder, paged, sorted by tier and then name
• Broadcast when somebody is tiered (switchable), and a private message to the player
• PlaceholderAPI: %tiertags_best%, %tiertags_points%, %tiertags_sword%, and _plain versions without colour
• JSON export on a timer (or /tier export) with every player, their best tier, points and per-ladder tiers, ready for a website
• Offline players supported: set a tier for someone who is not online
• SQLite storage in the plugin folder, nothing to install
• MiniMessage everywhere; tag format, prefix and all messages editable

The tab list sorted by tier.

The tier screens

A player's tiers per ladder and their points, with tier lists, set a tier and export.

Testers set a tier in one screen: player, ladder, tier.

• /tier on its own opens a real Minecraft dialog window with your own tiers, your best one and your points
• /tierlist on its own opens the ladder browser: pick a ladder, read the ranked list, page through it with buttons
• Testers get a set screen: type a name, pick the ladder and the tier from drop-downs, then set it, remove it, or look at everything that player holds
• That is three clicks instead of typing /tier set Name sword HT3 with the tier spelled right
• menu: false puts the chat lines back

FAQ

Which servers does it run on?

Paper or Purpur 1.21.11 or a newer 1.21.x, with Java 21.

Do I need other plugins?

No. PlaceholderAPI is supported if you have it, and SQLite is built in.

Is there DRM or a licence key?

No. There is nothing to activate and no licence server to reach, and the code is not obfuscated.

How long does setup take?

Drop the jar into /plugins and restart. The setup guide above has 4 short steps.

Can I try it before I buy?

Yes. This page has a test server with the plugin installed.

Where do I get help?

In the active support Discord, in the discussion tab on this page, or in the documentation.

Can testers set tiers without admin rights?

Yes. Give them tiertags.tester: they can set and remove tiers, nothing else.

Updates

Released on September 15, 2026 and updated 4 times since. The latest version is v1.3.0 (October 16, 2026). Every update is free, new Minecraft versions included.

Also by Frostyh

• KitLayouts: kits players arrange themselves
• ArenaBots: PvP training bots that fight back
• Nameplates: stacked custom nametags
• Complete Collection: all my published plugins in one purchase, 40% off

If this plugin helps your server, a short review on this page would mean a lot. Thank you!

Installation

Requirements

Server software

Paper, or a Paper fork such as Purpur. Spigot and CraftBukkit are not supported: the plugin uses Paper-only APIs.

Minecraft version

plugin.yml api-version 1.21; built against Paper API 1.21.11

Java

21 or newer

Required plugins

none

Optional plugins

PlaceholderAPI

Libraries

org.xerial:sqlite-jdbc:3.53.2.1, downloaded by the server at startup (plugin.yml libraries)

Steps

1. Download TierTags.jar from BuiltByBit. There is no licence key to enter.
2. Stop the server and put the jar into the plugins folder.
3. Start the server. The plugin creates plugins/TierTags/config.yml with the defaults shown under Configuration.
4. Edit config.yml to suit your server.
5. Apply the changes with /tier reload (Reload the config), or restart the server.

Setup guide

1. Drop TierTags.jar into /plugins and restart.
2. Edit the ladders and tiers to match your server, /tier reload.
3. Give your testers tiertags.admin (or a LuckPerms group with it).
4. Testers run /tier set <player> <ladder> <tier>. Tags and lists update instantly.

Duel / PvP servers: one ladder per kit. Your tiers show in tab during matches, and %tiertags_best% goes into your scoreboard.

FFA / KitPvP: a single "ffa" ladder is enough, or split by kit. The tag above the head tells everybody who to watch out for.

SMP: ladders do not have to be PvP: "building", "redstone", "farming", "pvp". Testers become your judges and the tier becomes a status people play for.

Websites: point export.file at your web root (for example /var/www/site/tiers.json) and read it with a few lines of JavaScript. The file holds every player with uuid, name, best tier, points and all ladders.

Commands

From plugin.yml. "Not set" in the permission column means plugin.yml attaches no permission to the command itself; the nodes the plugin checks are listed under Permissions.

Subcommands in detail

/tier                                  Your own tiers and points.
/tier <player>                         Somebody else's tiers.
/tier set <player> <ladder> <tier>     (admin) Give a tier on a ladder.
/tier remove <player> <ladder>         (admin) Take a tier away.
/tier ladders                          List the ladders.
/tier export                           (admin) Write the JSON file now.
/tier reload                           (admin) Reload the config.
/tierlist <ladder> [page]              The ranked list for one ladder.
/tierlist overall [page]          Everybody ranked by total tier points.

Permissions

From plugin.yml.

Viewing and /tierlist need no permission.

Placeholders

Registered with PlaceholderAPI under the identifier tiertags (TierPlaceholders.java). PlaceholderAPI must be installed for these to work.

<ladder> is a ladder key from ladders: in config.yml. The default ladders are sword, axe, mace, crystal, uhc, pot, smp, so for example %tiertags_sword%.

When a player holds no tier, the placeholder shows the text of messages.none in config.yml (default: "<muted>none</muted>").

Configuration reference

The default files as they ship in the jar, with their comments. The plugin writes them to plugins/TierTags/ on first start.

config.yml

Top-level keys:

# TierTags - tier lists for any server.
#
# Testers set a tier per player per ladder (/tier set <player> <ladder> <tier>). The best tier a
# player holds shows above their head and in the tab list, every ladder has a ranked /tierlist,
# PlaceholderAPI can put tiers anywhere, and a JSON file is written for a website.

# Bare /tier and bare /tierlist open the screens instead of printing lines in chat.
menu: true

# Ladders: key -> label shown to players. Any names you like: kits, game modes, skills.
ladders:
  sword: "Sword"
  axe: "Axe"
  mace: "Mace"
  crystal: "Crystal"
  uhc: "UHC"
  pot: "Pot"
  smp: "SMP"

# Tiers, lowest to highest. points feed "best tier" and the global score; colours are MiniMessage.
tiers:
  LT5: { color: "<gray>", points: 1 }
  HT5: { color: "<gray>", points: 2 }
  LT4: { color: "<green>", points: 3 }
  HT4: { color: "<green>", points: 4 }
  LT3: { color: "<aqua>", points: 6 }
  HT3: { color: "<aqua>", points: 8 }
  LT2: { color: "<light_purple>", points: 12 }
  HT2: { color: "<light_purple>", points: 16 }
  LT1: { color: "<gold>", points: 24 }
  HT1: { color: "<gold>", points: 32 }

display:
  # Tag above the head and in tab, as a team prefix. {tier} is the coloured best tier.
  enabled: true
  format: "<dark_gray>[</dark_gray>{tier}<dark_gray>]</dark_gray> "
  # Also colour the name itself like the tier (only works for named colours like <aqua>).
  color-name: false

announce:
  # Tell the whole server when a tier is set.
  enabled: true

list:
  per-page: 10

export:
  enabled: true
  every-minutes: 5
  # Relative to plugins/TierTags/, or an absolute path such as /var/www/site/tiers.json
  file: "tiers.json"

# ------------------------------------------------------------------------------------------------
# THEME
# ------------------------------------------------------------------------------------------------
# Every message below is written against these names, not against hex codes: <accent>Open</accent>
# rather than <#48adf0>Open</#48adf0>. Change a colour here and it changes on every screen at
# once. Ordinary MiniMessage still works, so <gradient:#a:#b> and <#ff0000> are fine anywhere.
theme:
  accent: "#48adf0"     # your colour: headings and anything the player is meant to click
  accent2: "#9ad2f7"    # a lighter accent, for a second level of emphasis
  title: "#f4f7ff"      # screen titles
  text: "#c2ccdd"       # ordinary prose
  muted: "#6b7a94"      # hints, separators, anything the eye should skip
  value: "#ffffff"      # the numbers and names the player opened the screen to read
  good: "#57e08a"
  warn: "#ffc857"
  bad: "#ff6b6b"
  small-caps: false     # ᴇхᴀᴍᴘʟᴇ - a garnish; whole menus in it read badly
  # Real Minecraft item pictures beside the buttons and in the chest screens. Drawn from the
  # client's own textures, so there is nothing to install and no resource pack: it needs a
  # 1.21.9 or newer client, and older ones simply see the buttons as words.
  item-icons: true

messages:
  prefix: "<accent2><bold>Tiers</bold></accent2> <muted>»</muted> "
  none: "<muted>none</muted>"
  help: "<text>/tier [player] · /tier set <player> <ladder> <tier> · /tier remove <player> <ladder> · /tierlist <ladder|overall> [page] · /tier ladders</text>"
  no-permission: "<bad>You cannot do that.</bad>"
  usage-set: "<text>/tier set <player> <ladder> <tier></text>"
  usage-remove: "<text>/tier remove <player> <ladder></text>"
  unknown-ladder: "<bad>Ladders: </bad><value>{list}</value>"
  unknown-tier: "<bad>Tiers: </bad><value>{list}</value>"
  unknown-player: "<bad>Unknown player: </bad><value>{name}</value>"
  set: "<value>{player}</value><text> is now </text>{tier}<text> on </text><value>{ladder}</value><text>.</text>"
  you-were-tiered: "<text>You are now </text>{tier}<text> on </text><value>{ladder}</value><text>.</text>"
  announce: "<value>{player}</value><text> was tiered </text>{tier}<text> on </text><value>{ladder}</value><text>.</text>"
  removed: "<text>Removed </text><value>{player}</value><text>'s tier on </text><value>{ladder}</value><text>.</text>"
  nothing-to-remove: "<text>{player} had no tier on {ladder}.</text>"
  view-header: "<value>{player}</value><text>: best </text>{best}<text>, </text><value>{points}</value><text> points</text>"
  view-row: "<text> - </text><value>{ladder}</value><text>: </text>{tier}"
  list-header: "<value>{ladder}</value><text> tier list, page {page}/{pages} ({count} players)</text>"
  list-row: "<muted>#{place}</muted> <value>{player}</value> {tier}"
  list-empty: "<text>Nobody is tiered here yet.</text>"
  # /tierlist overall: everybody ranked by the sum of their tier points across every ladder.
  list-overall-header: "<value>Overall</value><text> ranking, page {page}/{pages} ({count} players)</text>"
  list-overall-row: "<muted>#{place}</muted> <value>{player}</value> <text>{points} points, best</text> {best}"
  # Placeholders: an empty leaderboard slot (%tiertags_top_..%) and a player with no place (%tiertags_rank..%).
  placeholder-empty: "-"
  placeholder-unranked: "-"
  ladders: "<text>Ladders: </text><value>{list}</value>"
  reloaded: "<value>Config reloaded.</value>"
  exported: "<value>Written to </value><text>{file}</text>"

  # The tier screens. Every line here is a screen title, a button label or a tooltip.
  menu-title: "<value>Tiers</value>"
  menu-close: "<white><icon:close></white><text>Close</text>"
  menu-back: "<white><icon:back></white><text>Back</text>"
  menu-back-tip: "<text>Back to the screen before.</text>"
  menu-home-me: "<value>{player}</value><text>: best </text>{best}<text>, {points} points</text>"
  menu-home-untiered: "<text>You hold no tier yet. Ask a tester for a test.</text>"
  menu-ladders: "<white><icon:tier></white><accent2>Tier lists</accent2>"
  menu-ladders-tip: "<text>The ranked list of every ladder.</text>"
  menu-ladders-title: "<value>Tier lists</value>"
  menu-ladders-intro: "<text>Pick a ladder to see who is on top.</text>"
  menu-ladder: "<white><icon:tier></white><value>{ladder}</value> <muted>({count})</muted>"
  menu-ladder-tip: "<text>The ranked list for {ladder}.</text>"
  menu-list-title: "<value>{ladder}</value>"
  # The button under the ladders that opens the overall ranking.
  menu-overall: "<white><icon:top></white><accent2>Overall</accent2> <muted>({count})</muted>"
  menu-overall-tip: "<text>Everybody across every ladder, by tier points.</text>"
  menu-overall-title: "<value>Overall ranking</value>"
  menu-prev: "<white><icon:back></white><text>« Page back</text>"
  menu-prev-tip: "<text>The page before.</text>"
  menu-next: "<white><icon:next></white><text>Page on »</text>"
  menu-next-tip: "<text>The next page.</text>"
  menu-set: "<white><icon:nick></white><accent2>Set a tier</accent2>"
  menu-set-tip: "<text>Testers only: give or take a tier.</text>"
  menu-set-title: "<value>Set a tier</value>"
  menu-set-intro: "<text>Type the name, pick the ladder and the tier, then set it.</text>"
  menu-set-nothing: "<text>There are no ladders or no tiers in config.yml yet.</text>"
  menu-field-player: "<text>Player</text>"
  menu-field-ladder: "<text>Ladder</text>"
  menu-field-tier: "<text>Tier</text>"
  menu-set-apply: "<white><icon:yes></white><good>Set this tier</good>"
  menu-set-apply-tip: "<text>Give the player the tier above.</text>"
  menu-set-remove: "<white><icon:delete></white><bad>Remove from this ladder</bad>"
  menu-set-remove-tip: "<text>Take away whatever they hold on that ladder.</text>"
  menu-set-view: "<white><icon:yes></white><value>Show their tiers</value>"
  menu-set-view-tip: "<text>Every ladder for the player above.</text>"
  menu-view-title: "<value>{player}</value>"
  menu-export: "<white><icon:save></white><text>Export now</text>"
  menu-export-tip: "<text>Write the JSON file for the website.</text>"
  menu-reload: "<white><icon:reload></white><text>Reload config</text>"
  menu-reload-tip: "<text>Read config.yml again.</text>"

# One thank-you line with the BuiltByBit review link: once in the console after install and once
# in chat for the first operator who joins. It never repeats and sends nothing anywhere. false turns it off.
review-reminder: true

Config guide

The annotated summary from the store page. Where it and the default file above differ, the file is what the plugin ships.

ladders:                     key: label. Add or rename freely.
  sword: "Sword"
  axe: "Axe"
  smp: "SMP"

tiers:                       lowest to highest. Points drive "best tier" and global points.
  LT5: { color: "<gray>", points: 1 }
  HT3: { color: "<aqua>", points: 8 }
  HT1: { color: "<gold>", points: 32 }

display:
  enabled: true
  format: "<dark_gray>[</dark_gray>{tier}<dark_gray>]</dark_gray> "   the tag in tab and above the head
  color-name: false          also colour the name like the tier

announce:
  enabled: true              broadcast when a tier is set

list:
  per-page: 10

export:
  enabled: true
  every-minutes: 5
  file: "tiers.json"         relative to plugins/TierTags, or an absolute path into your web root

FAQ

Which servers and versions does it run on?

It needs Paper or a Paper fork such as Purpur, because it uses Paper-only APIs (the dialog API for its menus, Adventure text components). Spigot and CraftBukkit are not supported. plugin.yml declares api-version 1.21, the jar is built against Paper API 1.21.11, and it needs Java 21 or newer.

Does it need other plugins?

No other plugin is required (plugin.yml has no hard dependencies). Optional: PlaceholderAPI (plugin.yml softdepend), used when present. The server downloads org.xerial:sqlite-jdbc:3.53.2.1 at startup, so it needs internet access on first start.

How do I apply config changes?

Edit plugins/TierTags/config.yml and run /tier reload (reload the config). A restart works too.

Does it run on Folia, or for Bedrock players?

Not tested on Folia, and plugin.yml does not declare folia-supported. Bedrock players (through Geyser) have not been tested either.

What licence do I get?

The licence terms are the BuiltByBit EULA shown on the listing. There is no licence key to enter, and the plugin never contacts a licence server.

Links

• BuiltByBit: TierTags
• Support Discord: discord.gg/KG4ubAZEuw
• All plugins on BuiltByBit: the collection
• More plugins: all plugins
• Custom work: commissions

Support

Questions, bugs or ideas: the active support Discord or the discussion tab on this page. When something breaks, include your server version and the error from the console.

Full setup guide, commands, permissions and config reference: documentation.