LuckTAB

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.