LuckTAB

Tab list, name tags, sidebar and chat format, all driven by the LuckPerms group a player is in. One config.yml decides what a rank looks like, and the plugin applies that prefix everywhere at once: above the head, in the tab list, in front of the chat message and in the sidebar.

Colors can be legacy codes, hex, or animated gradients that move on their own. Header, footer and sidebar can differ per world and per permission, players can switch their sidebar off, and lines that have nothing to say disappear on their own. Bedrock players joining through Geyser get a sidebar that stays calm instead of flickering. Icons like :star: work in prefixes and lines, also straight from your resource pack.

Full documentation is in the wiki.

Requirements

• Paper or Spigot on Minecraft 1.21+
• Java 21
• LuckPerms (required)
• PlaceholderAPI (optional)
• ProtocolLib (optional, only for the static info rows in the tab list)
• EssentialsX, CMI or Purpur (optional, for the AFK tag)
• Geyser or Floodgate (optional, for Bedrock players)

On Paper the sidebar renders through components, so hex and gradients work in every line. On Spigot the sidebar falls back to legacy colors; everything else is the same.

Bedrock and Geyser

Bedrock players are recognized through the Floodgate or Geyser API, nothing has to be set up. Geyser rebuilds the whole Bedrock sidebar on every change it receives and starts throttling above 20 scoreboard packets per second, so LuckTAB only sends what actually changed, and Bedrock players get their own, slower update rate:

bedrock:
  enabled: true
  update-interval: 20
  animations: false
  fake-entries: false

With animations: false gradients and %anim_...% stay on their first frame for them. Bedrock cannot show a tab list header and footer, so those are not sent at all. A sidebar or header/footer design with platform: bedrock is only used for Bedrock players, which leaves room for shorter lines on the narrower Bedrock sidebar.

Icons

Write :name: in any LuckTAB line or in a LuckPerms prefix or suffix and it turns into a symbol. %lucktab_icon_name% does the same inside LuckTAB lines. Names without an icon stay as they are.

icons:
  star: "&e★"
  crown: "&6♛"
  # rank_owner: "\uE001"   # a resource pack glyph

With icons-auto LuckTAB also reads the glyphs of your resource pack on its own. The picture name is the icon name, so rank_owner.png becomes :rank_owner:. It uses the pack from server.properties, or the pack you set (URL, zip or folder). Only pictures with exactly one character count. Icons from your own icons section win over the pack.

With ItemsAdder installed its font images work as :name:, with Nexo or Oraxen their glyph ids.

Commands

Command	Description	Permission
/lucktab reload	Reload config.yml and rebuild every display	lucktab.reload
/lucktab toggle, /sidebar, /sb	Show or hide your own sidebar, remembered across rejoins	lucktab.toggle
/lucktab setprefix <group> <prefix>	Change a rank prefix in game and reload	lucktab.edit
/lucktab setsuffix <group> <suffix>	Change a rank suffix in game and reload	lucktab.edit
/lucktab benchmark	What the updates cost, in microseconds per section	lucktab.benchmark
/lucktab migrate to-luckperms	Write the configured prefixes into LuckPerms groups	lucktab.migrate
/lucktab migrate from-luckperms	Read the prefixes of all LuckPerms groups back into the config	lucktab.migrate

All permissions default to op, except lucktab.toggle, which everyone has.

setprefix and setsuffix save config.yml through Bukkit, which drops the comments in it. The alias of the toggle command is configurable and is registered at startup, so changing it needs a restart rather than a reload.

Configuration

When a new version adds options, they are written into your existing config.yml on the next start, with their comments. Your values stay as they are, and the previous file is kept as config.yml.bak.

Ranks are one line each, in the order they should appear in the tab list. Top is highest:

prefixes:
  - "owner;<gradient:#FF0000:#FF7700>[Owner] </gradient>;;&#FF7700"
  - "admin;&#FF5555[Admin] &7;;&#FF5555"
  - "vip;&6[VIP] &7;;&6"
  - "default;&7[Player] &7;;&7"

The format is luckperms_group;prefix;suffix;namecolor. A player who is in none of the listed groups gets the last entry.

prefix-source decides where prefixes come from. With lucktab they are read from the config above, with luckperms the prefix and suffix come from the group meta in LuckPerms and only the sort order and name color stay with the config. The two migrate commands move the data between both sides, so switching does not mean typing everything again.

header-footer and scoreboard each hold a designs section. A section named after a world is used in that world, everything else falls back to default. A design can also pick itself by permission, which is what a staff board next to a player board needs, or by platform: bedrock / platform: java:

scoreboard:
  designs:
    staff:
      permission: lucktab.staff
      priority: 10
      title: "&c&lStaff"
      lines:
        - "&7TPS: &f%server_tps_1%"

Lines whose placeholders all come back empty, 0 or null are dropped instead of leaving a gap, so &7Clan: &f%clan_name% is simply not there for a player without a clan. Empty spacer lines always stay.

animations holds named frame lists, and %anim_<name>% prints the current frame anywhere a placeholder is allowed. A header and footer design can carry frames instead of one fixed block and rotate through them.

Colors

Syntax	Example
Legacy	&a, &l, &r
Hex	&#FF5555
Gradient	<gradient:#FF0000:#FF7700>text</gradient>

Gradients animate: the color wave shifts a little every two ticks, so a prefix slowly cycles through its range.

Placeholders

Placeholder	Meaning
%player%	Player name
%world%	Current world
%server_online%	Online player count
%server_max_players%	Slot count
%player_ping%	Ping as a plain number
%lucktab_ping_colored%	Ping, green/yellow/red by the thresholds in ping-colors
%lucktab_rank% / %lucktab_prefix%	The rank prefix
%lucktab_suffix%	The rank suffix
%lucktab_color%	The name color of the rank
%lucktab_rank_display%	Prefix, color, group name and suffix in one
%lucktab_ping_icon%	Ping symbol from the ping-icons section
%lucktab_icon_<name>%	Icon from the icons section or the resource pack, only inside LuckTAB lines and prefixes (:name: works too)
%lucktab_tps%	Server TPS with one decimal (Paper, - on Spigot)
%lucktab_tps_colored%	TPS, green from 19, yellow from 15, red below
%lucktab_mspt%	Average milliseconds per tick (Paper)
%lucktab_afk%	The AFK tag, empty while the player is active
%lucktab_badges%	Badges for every group the player is in
%lucktab_platform%	Bedrock for Geyser/Floodgate players, otherwise Java
%anim_<name>%	Current frame of an animation
%chatPrefix% / %chatSuffix% / %chatBadges% / %playerName% / %message%	Chat format only

With PlaceholderAPI installed, its placeholders work in every LuckTAB text as well. LuckTAB registers its own expansion in return, so other plugins can read %lucktab_prefix%, %lucktab_rank_display%, %lucktab_badges% and the rest; append _plain for a version without colors. That is also how DiscordSRV picks up the ranks for its chat bridge: put the placeholder into the DiscordSRV message format.

Building

mvn clean package

The finished jar lands in target/LuckTAB-<version>.jar. bStats is shaded and relocated into de.empireblocks.luckTAB.metrics; paper-api, the LuckPerms API and PlaceholderAPI are provided and stay out of the jar.

License

GNU General Public License v3.0. See LICENSE.