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.

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.

Commands

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

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

Placeholders

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.