TAB order and small icons
Sorting the TAB list by rank
Staff on top, then paid ranks, then everyone else, A-Z inside each rank. One section of
config.yml decides it:
tablist-sort:
by: weight # weight | groups | profile | off
groups: [owner, admin, mod, helper, builder, vip, default]
by: |
What decides the place | Needs |
|---|---|---|
weight |
The player's heaviest LuckPerms group, inherited groups included. Higher weight goes higher: owner at 300 sits above vip at 10. |
LuckPerms with setweight on the groups |
groups |
The list under groups:. The first group in the list the player is in decides; a player in none of them goes last. |
LuckPerms, or any permissions plugin behind Vault |
profile |
Each profile's weight: (lower goes higher). This was the only order before 1.3.0, and a config without tablist-sort keeps it. |
nothing |
off |
HudForge writes no order: the list stays alphabetical. | nothing |
Players who share a place are listed A-Z, ignoring capitals.
Which one to pick
-
One server, one set of ranks:
weight. Give each group a weight once (/lp group admin setweight 200) and the order follows from it. -
A network whose game modes share one LuckPerms database, with ranks per mode (a
box_vipand asurvival_dragonthat can both belong to the same player, given globally):groups, and on each server list only the ranks of that mode. Withweight, a Survival rank would also place the player on Box.
# Box server
tablist-sort:
by: groups
groups: [owner, admin, mod, builder, creator, box_immortal, box_elite, box_mvp, box_pro, box_vip, default]
The order is applied right away on join, world change and /hud reload, and checked again every
nametag-refresh-ticks (2 seconds by default), so a rank bought while online moves the player up
within two seconds.
How it works, and what else can break it
The game sorts the TAB by scoreboard team name. HudForge puts each player in a team whose name
starts with a three-digit key (000 = top), written into every online player's scoreboard. Two
consequences:
-
Another plugin that also puts players in teams (another TAB plugin, a nametag plugin, some minigames) fights over the same thing. Run one of them.
-
A plugin that moves players to its own scoreboard takes the whole HUD away: sidebar, TAB order and name tags. HudForge 1.3.1 and later say so once in the log ("Another plugin moved ... to its own scoreboard"). BetterTeams does it with
useTeams: true: set it tofalseand run/teama reload. Its team tag above the head goes away; the teams themselves keep working. -
Spectators always go to the bottom: the game does that before looking at teams.
Small icons: <sprite_or> and <head_or>
1.21.9 added two text objects the game draws inline: any sprite of its atlases
(<sprite:items:item/diamond>) and a player's face (<head:Notch>). No resource pack needed.
Clients older than 1.21.9 cannot draw them. On a server that lets older versions in with ViaVersion, ViaBackwards and ViaRewind, the icon reaches them as an empty text: no garbage, but a gap in the line. We checked what arrives with bots on 1.21.11, 1.21.4, 1.20.4 and 1.8.9:
| Client | <sprite:items:item/diamond> |
<sprite_or:items:item/diamond:''> |
|---|---|---|
| 1.21.9 and later | the diamond | the diamond |
| 1.21.4, 1.20.4 | nothing ("SPRITE END") |
`` |
| 1.8.9 | nothing | `` |
So write the _or form, with the text older clients should see last:
lines:
- "<sprite_or:items:item/diamond:'<aqua>◆'> <white>Gems: %gems%"
- "<head_or:%hud_player%:'☺'> <white>%hud_player%"
nametag:
prefix: "<sprite_or:items:item/emerald:'*'>%hud_prefix%"
- The atlas can be left out:
<sprite_or:item/diamond:''>uses the item and block atlas. -
The text may carry colours and spaces when it is in single quotes; without quotes it ends at the next
:or>. -
The choice is made per viewer in the sidebar, the TAB header and footer, the boss bars, the action bar and the nametag prefix and suffix: a 1.8 player looking at a 1.21.11 player's nametag gets the text, the 1.21.11 player next to them the icon.
-
tablist.nameis the exception: the game sends one list name to everyone, so there it is decided by the listed player's own client. Keep icons out oftablist.nameon a mixed-version server, or put them innametag.prefix, which also shows in the TAB. -
Server side, icons are only sent from Paper 1.21.9 or newer. On older servers and on Spigot every viewer gets the text.
To show something else entirely to old clients, gate on the client's protocol, which
%hud_protocol% gives through ViaVersion (773 = 1.21.9, 393 = 1.13, 47 = 1.8):
- text: "<white>Your stats, now with icons"
when: "%hud_protocol%>=773"