TagAPI icon

TagAPI -----

An open source API that allows developers to easily add extra lines above an entity.



TagAPI

I have frequently come across the question from developers on both the Spigot forums and Discord servers that asks how to create customizable text under a players name. A system that provides unlockable "titles" under a players name has been a staple in a server for over two years that I have developed for, and I wished to share the method which I use to create them.
There have been a couple of methods I had seen to accomplish this:​
  1. Using a scoreboard.
  2. Teleporting invisible entities above an entity.
  3. Mounting invisible entities to an entity.
All of these work, but each have their own pros and cons. Scoreboards are easy, but always have a number to the left of them and limit you to one line. You also have to worry about the players scoreboard changing. Teleporting may have the issue of the tag trailing behind them. Mounting limits the entities ability to have any other entity mounted to it.

This resource only uses the mounting technique.

Examples

[​IMG]
[​IMG]
[​IMG]

Client Side Only

This API does not create any actual entities to work. The entirety of it uses packets to trick the client into thinking an entity exists. What are the benefits, though? Well, there are quite a few.

First off, no mess. The last thing a server owner would like is for a plugin to incorrectly shutdown, and now there are random floating tags around the world where entities once were. With the entirety of this system using packets and only existing on the clients end, you will not have to worry about this ever!

Second, and my personal favorite, is per-player customization. You can have the lines of the tags appear different to each individual player, or even hide specific lines from individual players.

How to Install On a Server

There are two ways you can use this resource. This resource can either be downloaded from the SpigotMC plugin page as an individual plugin to be dropped into the servers plugins directory, or you can directly integrate it into your code using maven shade or github download.
Code (Text):
<dependency>
    <groupId>com.lkeehl</groupId>
    <artifactId>tagapi</artifactId>
    <version>1.2.3</version>
</dependency>
If you are directly integrating this API into your own code, then the methods to enable and disable it are simple:
Code (Java):
// In your plugins onEnable, include a line such as
TagAPI. onEnable ( this ) ;
// and on disable
TagAPI. onDisable ( ) ;
Creating Tags

Tags can be created by using the Builder or Tag.create(entity) method like so:
Code (Java):
TagBuilder builder = TagBuilder. create (entity ) ; // Create a new TagBuilder
builder. withLine (pl -> "First Line" ). withLine (pl -> "Second Line" ) ; // Add a first and second line
builder. withLine (pl -> "Third Line", pl -> false ) ; // Add another line, because why not?
builder. build ( ) ; // Build will return a Tag instance, which you can use with methods later in this page

// or

Tag tag = Tag. create (entity ) ; // Create a new Tag
tag. addTagLine ( 10 ). setText (pl -> "First Line" ) ;
tag. addTagLine ( 9 ). setText (pl -> "Second Line" ) ;
tag. addTagLine ( 8 ). setText (pl -> "Third Line" ). setKeepSpaceWhenNull (pl -> false ) ;
For each TagLine, you are able to customize two settings: What the line should return and whether the line should be visible if the line is null. In the TagBuilder, the line text is the first argument in the withLine method whereas the keepSpaceWhenNull setting an optional second argument.
In the second example, the addTagLine method returns a TagLine object, which you can directly call .setGameName and .setKeepSpaceWhenNull to alter the aforementioned settings.

Using the traditional Tag.create method, you can see that the addTagLine method accepts an integer. This is the priority towards the top. The TagBuilder does not have this, as the order of the lines will be the order you add them to the builder.

Getting, Updating, and Removing Tags

From here, everything can be controlled through the Tag or TagAPI class like so:
Code (Java):
Tag tag = Tag. create (entity ) ; // Create a tag for the entity
tag. giveTag ( ) ; // Give the entity the tag.

tag = TagAPI. getTag (entity ) ; // Grab the tag of an entity. Entity must have been given the tag using above method.
tag. updateTag ( ) ; // Update the tag incase lines should change for viewers
tag. removeTag ( ) ; // Remove the tag from the entity. This tag can still be given back to the entity later.
The above example shows creating a new tag for an entity, spawning the tag in, grabbing an entities tag, updating the tag, as well as removing one. The same can be accomplished through the TagAPI class.

Code (Java):
TagAPI. giveTag (entity, tagConstructor ) ; // Create and give tag to entity. tagConstructor is a Function that receives an entity and returns a tag.
TagAPI. updateTag (entity ) ; // Update the entities tag
TagAPI. removeTag (entity ) ; // Remove a tag from an entity
Setting Default Tags

I lastly wanted to share that it is possible to set default tags for entity types using the method in the following example:
Code (Java):
TagAPI. setDefaultTag (EntityType. PIG, target ->
    TagBuilder. create (target ). withLine (pl -> target. getName ( ) ). withLine (pl -> ChatColor. YELLOW + "Hello " + pl. getName ( ) + "!" ). build ( )
) ;
All viewed entities will be checked only once if they should have a tag. This means that you can easily remove a tag from an entity, and it will not respawn itself.

Dependencies

TagAPI requires ProtocolLib to run, and will only run in version 1.17.1 or higher as of the current release.

I make no guarantees that this will properly work with all plugins. I intend to have the resource account for hitboxes when adding lines to entities, but it does not as of this release. The resource will not show an entity-name line by default. If you want to show an entities name, add it as a TagLine.
Resource Information
Author:
----------
Total Downloads: 2,012
First Release: Nov 5, 2021
Last Update: Jul 8, 2022
Category: ---------------
All-Time Rating:
3 ratings
Find more info at github.com...
Version -----
Released: --------------------
Downloads: ------
Version Rating:
----------------------
-- ratings