Cocoa Beans 0.0.54-beta0 Help

👥 DisplayTeam

Introduction

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

Showcase

team-tab-priority.png

Sorting Tab-list

image.png

Ability to set viewers

tab-animation.gif

Animation support using Observable

Usage

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

Last modified: 07 July 2025