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

Discussion in 'Resources' started by mbaxter, Sep 6, 2012.

Thread Status:
Not open for further replies.
  1. Offline

    mbaxter ʇıʞʞnq ɐ sɐɥ ı


    TagAPI is 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:

    1. @EventHandler
    2. public void onNameTag(AsyncPlayerReceiveNameTagEvent event) {
    3. if (event.getPlayer().getName().equals("mbaxter")) {
    4. event.setTag("Notch");
    5. }
    6. }

    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.

    1. @EventHandler
    2. public void onNameTag(AsyncPlayerReceiveNameTagEvent event) {
    3. if (event.getNamedPlayer().getName().equals("TnTBass")) {
    4. event.setTag(ChatColor.RED + "TnTBass");
    5. }
    6. }

    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.

    Common questions

    Where is the javadocs?
    Javadocs are here! Yay!

    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 ;)

    Where do I link my users for TagAPI?
    Send them to the TagAPI BukkitDev page!

    More information
    Some of you like to build with Maven. You can find TagAPI at http://repo.kitteh.org/content/repositories/public/ under groupId org.kitteh and ArtifactId tagapi

    I suggest just building against version 3.0.

    Ask below! :)

    Reserved for future info

    Added some commonly asked questions.

    EDIT by Moderator: merged posts, please use the edit button instead of double posting.
    Last edited by a moderator: May 28, 2016
    AsapRocky, DoggyCode™, _LB and 29 others like this.
  2. Offline


    Cool. Should be part of Bukkit, if it could.
  3. Offline


    This looks very handy. Thanks a ton for releasing it!
  4. Offline


    I'm not sure if it would, but I think that would be great :D
  5. Offline


    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"
  6. Offline

    mbaxter ʇıʞʞnq ɐ sɐɥ ı

    No client needed. The floating nametag is the only thing this is for :p
  7. Do you think it would be possible to expand this to mob disguising because to my knowledge a lot of the same code is used to move and handle to teleporting of the fake entities.
  8. Offline


    Ooh. I may implement this in MCTag
  9. Offline


    So is this a plugin? I can change the floating nametag with this? are there commands? Sorry I'm new-ish

    Read my other comment on TagAPI because you seem to know how

    EDIT by Moderator: merged posts, please use the edit button instead of double posting.
    Last edited by a moderator: May 28, 2016
  10. Offline


    Yes. Yes. No its for devs.
  11. Offline


    So what do I do with it? (thanks for the reply)
  12. Offline


    If you are a dev: use it like vault, but to change color/name tags.
    If you aren't, nothing;p
  13. Offline


    Ok thanks!
    hawkfalcon likes this.
  14. Offline


    I am upset you didn't include me in the logo image :(
    Jugglernaught and hawkfalcon like this.
  15. Offline


    For some reason, the armor of the player disappears if I change their name. It is a Bukkit issue or a Minecraft client issue?
  16. Offline

    mbaxter ʇıʞʞnq ɐ sɐɥ ı

    This was an issue with older releases. Make sure you're on the latest version (1.5)
  17. Offline


    Oh. My bad.

    Just curious, why do people flash for a second when I swap their tags?
  18. Offline

    mbaxter ʇıʞʞnq ɐ sɐɥ ı

    Their entity has to be removed, then readded on the client's side.
  19. Offline


    I will likely be adding this to MCTag
    chasechocolate, iKeirNez and mbaxter like this.
  20. Offline

    Bradley Hilton

    Thanks for making this! Made my life a whole lot easier. :D 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.
  21. Offline

    mbaxter ʇıʞʞnq ɐ sɐɥ ı

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

    Bradley Hilton

    Okay thanks!
  23. Offline


    This would work, right?
    1. public void onNameTag(PlayerReceiveNameTagEvent event) {
    2. Player player = event.getPlayer();
    3. event.setTag(ChatColor.RED + player.getDisplayName());
    4. }
  24. Yeah just remember your @EventHandler and to register the events.
  25. Offline

    mbaxter ʇıʞʞnq ɐ sɐɥ ı

    That means that every player will see everyone else as having their name. Eg. If I join a server, I'll see everyone else as mbaxter in red.
    jjacobson likes this.
  26. Offline


    Oh =/ How do I make it so that it's not my name, but that player's name that I see in red?
  27. Offline


    Will this remove the skins of the players?
    lol768 likes this.
  28. It will change the skin the whatever the nametag is, e.g. if you change your nametag to Notch, you will get Notch's nametag.
  29. Offline


    Would the code be this?
    1. Player player = event.getPlayer();
    2. String name = player.getName();
    3. event.setTag(ChatColor.RED + name);
  30. Offline

    mbaxter ʇıʞʞnq ɐ sɐɥ ı

    You're still getting event.getPlayer() which is the player RECEIVING the information about the nametag. Read the tutorial over again.
Thread Status:
Not open for further replies.

Share This Page