TagAPI - Change/color the name over people's heads!

TagAPIis a simple to use resource that your plugin hooks into (Think like Vault or Register) for determining a player's name tag.

Why use TagAPI instead of writing my own code?
More and more plugins are starting to implement name tag coloring to their featureset. This leads to a few problems. Plugin conflict arises when two or more plugins attempt to change the name tag. Depending on implementation this could result in ghost players, or differently colored names at random. Second, most of the implementations I've seen don't take into account a player teleporting, respawning or coming into range properly. TagAPI solves both of these problems by providing a single point of control run through the Bukkit events system, coupled with a fully thorough solution to name tag changing.

How do I implement TagAPI in my plugin?
First of all, you'll want to make sure it's on your build path. You can grab the latest TagAPI here. For determining a player's nametag, you listen to the AsyncPlayerReceiveNameTagEvent.

This event fires whenever one player is about to receive the nametag for another player. The event has two Player objects in it: getPlayer() and getNamedPlayer(). getPlayer is the player who is going to SEE the nametag and getNamedPlayer is the player whose name tag you are adjusting. For instance, in the above picture getPlayer is the person taking the picture and getNamedPlayer might be jamietech or KieraanBreeze.

Then, you can use getTag() to find out the currently set tag with getTag(), which will be the player's name unless another plugin has modified the event first (you can check that with isModified()). You can set the tag with setTag(String). Note that name tags are (thanks to Mojang) limited to 16 chars, and setTag will automatically trim that. setTag will return true if the tag has been set as you sent it and false if it had to be shortened to meet the 16 character limit. Color and formatting codes count as two characters each.

Notice: The AsyncPlayerReceiveNameTagEvent fires on a thread other than the main thread. Many methods in Bukkit cannot be called safely from other threads. If you require a permissions check, pre-cache the lookup for instance.

Here are a few examples of using the event:

Code:java

@EventHandler

publicvoid onNameTag(AsyncPlayerReceiveNameTagEvent event){

if(event.getPlayer().getName().equals("mbaxter")){

event.setTag("Notch");

}

}

In the above example, we check if the player receiving the tag is mbaxter. If so, the nametag he is shown is "Notch". This means that every single player name tag packet mbaxter receives, is Notch. He will be surrounded by Notch. Nobody else will notice anything different.

Code:java

@EventHandler

publicvoid onNameTag(AsyncPlayerReceiveNameTagEvent event){

if(event.getNamedPlayer().getName().equals("TnTBass")){

event.setTag(ChatColor.RED+"TnTBass");

}

}

In this event, we check if the name tag is for TnTBass, and if so make his name RED. In this scenario, every player on the server will see TnTBass as red.

In VanishNoPacket, I check if the player is vanished. If so, I color their name blue so that other admins see their name as blue to know they're invisible to normal players. But how do I accomplish that? I'd have to force the name tag to refresh!

I have additionally provided in TagAPI several static methods that will help you do this.

Static methods for refreshing a player's name tag.
For convenience, there are three methods for refreshing a player's name tag.

TagAPI.refreshPlayer(Player player)
This method will cause the name tag for that player to be refreshed for everyone, which will thus trigger the event to fire for everyone else on the server. (getNamedPlayer would be the Player called in the method, and getPlayer would be all the players seeing him)

TagAPI.refreshPlayer(Player player, Player forWhom)
With this method, you are defining a single player will get the name tag updated for another. This could be useful if you only want to change the tag a single player sees without causing a slight flicker for anyone else. forWhom is the player who will see the potentially new tag. The single event that would fire as a result of this would have getPlayer equal to the forWhom in the above arguments and getNamedPlayer being the player variable in the above arguments.

TagAPI.refreshPlayer(Player player, Set<Player> forWhom)
This method is just calling the above refreshPlayer(player, forWhom) for each of the players defined in the forWhom Set.

What event priority should I listen at?
I would suggest just listening on NORMAL unless you have a particular need to beat out other plugins or a need to let other plugins take over. For instance, if you are passively changing name tags but would happily let another plugin change it, register on LOWEST or LOW. If your plugin is a game mode plugin and you use name tag colors to tell apart teams (and thus can't let other plugins interfere with the color) register on HIGH or HIGHEST, so you get say over them.

Why can't I just include your code in my plugin
Because that'd break the entire purpose of this plugin - eliminating conflicts between plugins. You'd break any plugin using TagAPI while yours is running.

So I have to link people to TagAPI to download that too?
Yes. It's a few extra seconds of effort for the server admin, to save them frustration down the road. If someone complains about the extra download, explain to them that the benefits far outweigh the negative consequences and that it's purely a convenience plugin that will very rarely need to be updated (only when minecraft itself updates).

I want to make TagAPI optional for my plugin
Great! Just make sure that the listener for TagAPI isn't registered if TagAPI isn't on the server, otherwise you'll get errors.

Help! The colors are going in reverse! I said to change my admins to red and now admins see everyone as red!
You've reversed getPlayer and getNamedPlayer

Does the player need any client for this?
I'm guessing not. Thanks, very great and useful plugin! Also can you change the floating nametag of the person, like "exampleplayer" will have the name "Hello"

Does the player need any client for this?
I'm guessing not. Thanks, very great and useful plugin! Also can you change the floating nametag of the person, like "exampleplayer" will have the name "Hello"

Thanks for making this! Made my life a whole lot easier. Just one quick question, what's the best way in your opinion to clear the getNamedPlayer's tag and set it back to the default? Or just in general to clear a player's tag and reset it back to default.

Thanks for making this! Made my life a whole lot easier. Just one quick question, what's the best way in your opinion to clear the getNamedPlayer's tag and set it back to the default? Or just in general to clear a player's tag and reset it back to default.

Click to expand...

Same way you'd change it otherwise. Call a refresh and this time don't change the tag.