TablistManagerAPI

TablistManagerAPI is a API for displaying content on tablists for SpigotMC servers. Depends on ProtocolLib.

Features of the plugin

Fill the tablist to a custom size (with empty slots aka fake players)
Per world tablist (Only players within the World can see each others)
Multiversion since is built on top ProtocolLib
Header and footer manipulation (per-world)

Features of the API

All of the plugin but programmatically

Developing a plugin using the API

You can use the tablistmanager-api package by itself (suitable for customization), or use the tablistmanager-plugin.

Installing using Maven

The API and the Plugin are published to GitHub Packages. In order to access the packages you should follow this steps:

First, you should create a personal access token
Then, authenticate with that token on your settings.xml, as described here

<servers>
  <server>
    <id>github</id>
    <username>YOUR_GH_USERNAME</username>
    <password>YOUR_TOKEN</password>
  </server>
</servers>

Add the repository (to your settings.xml profile or to your project pom.xml)

<repository>
  <id>github</id>
  <url>https://maven.pkg.github.com/ErnestoRB/TablistManagerAPI/</url>
</repository>

Finally, add the dependency you need to your project POM (API or Plugin).

<dependencies>
   ...
   <dependency>
      <groupId>com.ernestorb.tablistmanager</groupId>
      <artifactId>tablistmanager-api</artifactId>
      <version>1.1.0</version>
   </dependency>
   ...
</dependencies>

<dependencies>
   ...
   <dependency>
      <groupId>com.ernestorb.tablistmanager</groupId>
      <artifactId>tablistmanager-plugin</artifactId>
      <version>1.1.0</version>
   </dependency>
   ...
</dependencies>

Developing using the API

Declare the tablistmanager-api dependency to your plugin POM
Create an instance of TablistManager. There must be just one instance of this class, having more can lead to issues.

  TablistManager manager = new TablistManager(this);

As the API depends on ProtocolLib, you need to make sure it gets loaded before. Add the following to your plugin.yml

loadbefore: [ ProtocolLib ]
depend: [ ProtocolLib ]

Developing using the plugin

Download the latest plugin available. (Releases tab)

Install the plugin downloaded before in you server plugin's folder.
Declare the tablistmanager-plugin dependency to your plugin POM.
In your plugin.yml add the following lines

loadbefore: [ TablistManager ]
depend: [ TablistManager ]

Get the attached TablistManager instance of the TablistManagerPlugin.

Plugin pl = this.getServer().getPluginManager().getPlugin("TablistManager");
if(pl != null && pl instanceof  TablistManagerPlugin) {
    this.manager = ((TablistManagerPlugin)pl).getManager();
} else {
    this.getLogger().severe("Plugin cannot be loaded due lack of TablistManager plugin");
    this.getPluginLoader().disablePlugin(this);
    return;
}

Code examples

Displaying header and footer

Get the TablistHandler attached to TablistManager (see api usage or the plugin usage, define a template and send it to the player you want.

public class HelloTablist extends TablistTemplate {

    private HelloTablist() {
        super((tablistTemplate, player) -> {
            // define new custom placeholder
            tablistTemplate.setHeader(tablistTemplate.getHeader().replaceAll("%new_placeholder%", player.getGameMode().toString()));
        });
        this.setHeader("&aHello!\n&eThis API is great %player_name%\nThis is my %new_placeholder% (gamemode)");
        this.setFooter("&cYou are on %player_world%"); // built in player placeholders
    }

    public static HelloTablist getInstance() {
        return new HelloTablist();
    }
}

This is how would look using the plugin.

Plugin pl = this.getServer().getPluginManager().getPlugin("TablistManager");
if(pl != null && pl instanceof  TablistManagerPlugin) {
    this.manager = ((TablistManagerPlugin)pl).getManager();
    TablistHandler handler = this.manager.getTablistHandler();
    Player p = ...;
    handler.setPlayerTablist(player, HelloTablist.getInstance());
} else {
    this.getLogger().severe("Plugin cannot be loaded due lack of TablistManager plugin");
    this.getPluginLoader().disablePlugin(this);
    return;
}

Adding slots (or "fake players")

If you want to display slots to a tablist, use the FakePlayers class.

If you want a "empty" slot

Use FakePlayer#randomFakePlayer() to create an instance of a FakePlayer
Add fake player to player's tablist with FakePlayer#getTablistAddPacket().sendPacketOnce(Player)
And to remove it use FakePlayer#getTablistRemovePacket().sendPacketOnce(Player)

If you want a slot with custom display name

Use FakePlayer(name, displayname) to create an instance of a FakePlayer
Add fake player to player's tablist with FakePlayer#getTablistAddPacket().sendPacketOnce(Player)
And to remove it use FakePlayer#getTablistRemovePacket().sendPacketOnce(Player)