Tab Lists

Waarschuwing

These docs were written for SpongeAPI 7 and are likely out of date. If you feel like you can help update them, please submit a PR!

Tab lists are used in Minecraft to display the list of players currently on a server. SpongeAPI allows for manipulation of the tab list on a per-player basis.

To get a player’s TabList, you simply need to call the Player#getTabList() method:

import org.spongepowered.api.entity.living.player.Player;
import org.spongepowered.api.entity.living.player.tab.TabList;

TabList tablist = player.getTabList();

Now that we have obtained the TabList, we can modify several components of it. For example, to set the header or the footer of the TabList, we simply need to call their appropriate methods:

import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;

tablist.setHeader(Component.text("The tab list header", NamedTextColor.GOLD));
tablist.setFooter(Component.text("The tab list footer", NamedTextColor.RED));

We can call the TabList#setHeaderAndFooter(Component, Component) method if we want to alter both of them at once:

tablist.setHeaderAndFooter(Component.text("header"), Component.text("footer"));

Notitie

If you are wanting to alter the tab list header and footer, it is recommended to use the setHeaderAndFooter() method over individually calling the TabList#setHeader(Component) and TabList#setFooter(Component) methods, as it only sends one packet instead of two separate packets for the header and the footer.

Tab List Entries

Now that we have set the header and footer of the TabList, we can also add our own entries to the list. An example of this is shown below:

import org.spongepowered.api.entity.living.player.gamemode.GameModes;
import org.spongepowered.api.entity.living.player.tab.TabListEntry;
import org.spongepowered.api.profile.GameProfile;

TabListEntry entry = TabListEntry.builder()
    .list(tablist)
    .gameMode(GameModes.SURVIVAL)
    .profile(gameProfile)
    .build();
tablist.addEntry(entry);

Now let’s break this down. We set the list associated with the TabListEntry to our specified TabList using the TabListEntry.Builder#list(TabList) method. We then set the game mode of our entry to GameModes#SURVIVAL. The game mode of our entry is used to determine various things. On the client, it is used to determine if a player is in creative or perhaps a spectator. If the game mode is spectator, then their name will also appear gray and italicized. We then need to specify the GameProfile that the entry is associated with. The GameProfile may be constructed using the GameProfile#of() method, or it can be obtained from a real profile, such as a player. For more information, see the Game Profile Manager article. To apply the entry to the tab list, we simply need to call the TabList#addEntry(TabListEntry) method.

We can flesh out our basic example by specifying things such as the display name or latency of the entry:

TabListEntry entry = TabListEntry.builder()
    .list(tablist)
    .displayName(Component.text("Spongie"))
    .latency(0)
    .profile(gameProfile)
    .build();
tablist.addEntry(entry);

Here, we set the display name that our entry will appear under to Spongie using the TabListEntry.Builder#displayName(Component) method. We then set the latency for our TabListEntry to five bars. See the TabListEntry#setLatency(int) method for more information on how to specify other types of bars for our entry.

Modifying Current Entries

Using the TabList, we can obtain entries currently on the TabList for our own modification. To obtain a specific entry, use the TabList#getEntry(UUID) method. This method will return Optional.empty() if the specified UUID cannot be found. An example is shown below:

import java.util.Optional;

Optional<TabListEntry> optional = tablist.getEntry(uuid);
if (optional.isPresent()) {
    TabListEntry entry = optional.get();
}

With this, we can use the methods on TabListEntry to modify the game mode, latency, and the display name of the entry:

entry.setDisplayName(Component.text("Pretender Spongie"));
entry.setLatency(1000);
entry.setGameMode(GameModes.SPECTATOR);

As an alternative to getting entries, we can also remove a specified entry. We must simply call the TabList#removeEntry(UUID) method, specifying the UUID of the entry that we wish to remove. As with getEntry(UUID), this will return Optional.empty() if the specified UUID cannot be found.

If we don’t have a specific entry to modify, then we can iterate through all TabListEntrys in a TabList. We just need to call the TabList#getEntries() method to obtain a Collection<TabListEntry> that we may iterate through.