The DisplayTeam api is a packet-level NMS-driven team display controller designed for Minecraft. It integrates seamlessly with UI systems by leveraging Observable state objects to ensure efficient updates across player clients.
Unlike typical Bukkit or API-level teams, DisplayTeam is optimized for direct manipulation via packets, making it extremely responsive and suitable for custom teams, overlays, or nametag modifications in real time. While giving you more free control over who see your teams
Here is an example of using the API with Spigot. You will have to implement a custom Team manager to manage active teams and their references. Beware that you will need to create your own manager and decide how to manage teams I will keep it simple here is simple manager
public class TeamManager {
private final Map<String, SpigotDisplayTeam> teams = new HashMap<>();
private final SpigotViewerGroup group = new SpigotViewerGroup(Collections.newSetFromMap(new WeakHashMap<>()));
private BukkitTask cprTask;
public void initialize(JavaPlugin plugin) {
if (cprTask != null)
return;
cprTask = new BukkitRunnable() {
@Override
public void run() {
heartbeat();
}
}.runTaskTimer(plugin, 0, 1);
}
public void heartbeat() {
for (SpigotDisplayTeam team : teams.values())
team.heartbeat();
}
public void disable() {
if (cprTask != null)
cprTask.cancel();
cprTask = null;
for (SpigotDisplayTeam team : teams.values())
team.delete();
teams.clear();
}
public DisplayTeam<Player> getTeam(Rank rank) {
return teams.computeIfAbsent(formatTeamName(
9999 - rank.getPriority(),
rank.name()
), key -> new SpigotDisplayTeam(key, group));
}
public void addViewer(Player player) {
group.add(player);
}
}
Here is how we create prefixes in tab and above head
public enum Rank {
DEFAULT(0, "§7"),
VIP(10, "§a§lVIP "),
HELPER(100, "§9§lHELPER "),
ADMIN(300, "§4§lADMIN "),
OWNER(500, "§c§lOWNER ");
private final int priority;
private final String prefix;
Rank(int priority, String prefix) {
this.priority = priority;
this.prefix = prefix;
}
public int getPriority() {
return priority;
}
public String getPrefix() {
return prefix;
}
}
// We will want to call that at start
public void createRankTeams() {
TeamManager teamManager = getTeamManager();
for (Rank rank : Rank.values())
teamManager.getTeam(rank)
.setPrefix(Observable.immutable(Component.text(rank.getPrefix())));
}
We also need to add the players as viewers and parts of the team
@EventHandler
public void onJoin(PlayerJoinEvent event) {
Player player = event.getPlayer();
TeamManager manager = getTeamManager();
manager.getTeam(getRank(player))
.addEntity(player.getName());
manager.addViewer(player);
}
Sorting Tab-list
In Minecraft, the tab list(player list) can be sorted using teams, where the team name determines the sort priority.
🔍 How Tab List Sorting Works
Minecraft sorts players in the tab list based on their team name in lexicographical (alphabetical) order. Players on teams with names that come earlier in the alphabet will appear higher in the list.
To control priority using numbers, you can prefix team names with numbers, such as "0001_team", "0002_team", etc. Lower numbers = higher priority in the tab list.
Code snippet
/**
* Formats an int priority into a Minecraft team name like "0001_Team"
* @param priority The integer priority (e.g., 1, 2, 10).
* @param name Optional team suffix or label (e.g., "Admin", "Mod"). Can be null or empty.
* @return A formatted team name string like "0001_Admin".
*/
public static String formatTeamName(int priority, String name) {
String formated = String.format("%04d", priority);
if (name == null || name.isEmpty())
return formated;
return formated + "_" + name;
}
Notes
For LuckPerms we would like to invert the number because their priority go up for example MAX_PRIORITY - priority, where max priority has to be higher than or equal to the highest configured priority in the system