Developer API
On this page5 sections
Other plugins can hide nametags, play reactions, read the applied template, pick badges, draw badges in their own messages and add new text effects. The API is small on purpose: designs live in the YAML files, so server owners keep control of them.
Setup
The API is inside the plugin jar (package me.vicentity.nametags.api); it is not published to a
Maven repository. Put the jar in your project and compile against it without shading it:
// build.gradle.kts
dependencies {
compileOnly(files("libs/AdvancedNametags-1.0.0.jar"))
}# plugin.yml (or paper-plugin.yml)
softdepend: [AdvancedNametags] # or depend, if your plugin cannot work without itGet the API once AdvancedNametags is enabled (it is registered in Bukkit's services manager):
import me.vicentity.nametags.api.AdvancedNametagsApi;
if (Bukkit.getPluginManager().isPluginEnabled("AdvancedNametags")) {
AdvancedNametagsApi api = AdvancedNametagsApi.get(); // throws IllegalStateException if it is not enabled
}All methods are thread-safe: call them from any thread, including Folia region threads and async tasks.
Methods
| Method | Does |
|---|---|
void refresh(Player) | Re-evaluates the player's template and placeholders on the next update (e.g. after your plugin changed a value a placeholder reads). |
void setHidden(Player, boolean) | Hides the nametag (or shows it again). Not saved: it resets when the player rejoins or the server restarts. Independent from /nametag set <player> hidden. |
boolean isHidden(Player) | true if hidden by the API, by an admin, or if the player has no nametag. |
Optional<String> template(Player) | Id of the template applied now; empty if the player is offline. |
Optional<List<String>> lines(Player) | Plain text (no colours, no images) of each line shown now. |
boolean react(Player, String) | Plays a reaction now: pop, fade, bounce, shake, jump, spin, a reaction from animations.yml, optionally with a duration ("bounce:ticks=20"). Returns false if the player has no nametag; throws IllegalArgumentException for an unknown reaction. |
Optional<String> badge(Player) | Id of the badge <badge> shows for the player. |
CompletableFuture<Boolean> setBadge(Player, String) | Saves which badge the player shows, as if they picked it: a badge id, "auto" (the first they own) or "none". Completes with false if no badge has that id. A badge they do not own is not shown. |
Optional<Component> badgeComponent(String) | The badge as an Adventure component for your chat, menus or scoreboards (1.21.9+ clients); its fallback text while its textures are not generated; empty for an unknown id. |
void registerAnimation(String, AnimationFactory) | Adds a text effect usable as <name> and <anim:name> in every line. Replaces a type with the same name. |
AdvancedNametagsApi api = AdvancedNametagsApi.get();
api.setHidden(player, true); // hide while in a hide-and-seek arena
api.react(player, "celebrate"); // the player scored, won, opened a crate
api.template(player).ifPresent(id -> getLogger().info(player.getName() + " uses " + id));
api.setBadge(player, "vip").thenAccept(ok -> { if (!ok) getLogger().warning("no badge 'vip'"); });
api.badgeComponent("mvp").ifPresent(badge -> player.sendMessage(badge.append(Component.text(" Welcome!"))));Event
me.vicentity.nametags.api.NametagTemplateChangeEvent (a PlayerEvent) fires when the template
applied to a player changes, including the first time after joining (previousTemplate() is then
null). It runs on the player's owner thread: the main thread on Paper, the player's region thread
on Folia. It cannot be cancelled.
@EventHandler
public void onTemplate(NametagTemplateChangeEvent event) {
if ("vip".equals(event.template()) && event.previousTemplate() != null) {
event.getPlayer().sendMessage(Component.text("Your VIP nametag is active!"));
}
}Custom text effects
A text effect is a function that returns the colour of each character for each tick. It runs on
network threads for every viewer, so it must be stateless: derive anything random from seed,
index and tick, never from a shared Random.
import me.vicentity.nametags.animation.Animation;
// <blink>text</blink>, or <blink:color=#ff0000:speed=2>
api.registerAnimation("blink", params -> {
int color = params.getColor("color", 0xFFFFFF);
double speed = params.getDouble("speed", 1);
return (index, length, tick, seed) -> ((long) (tick * speed) / 10) % 2 == 0 ? color : Animation.HIDDEN;
});
// <typewriter>: reveals the text letter by letter, then starts again
api.registerAnimation("typewriter", params -> (index, length, tick, seed) ->
index < (tick / 2) % (length + 10) ? 0xFFFFFF : Animation.HIDDEN);| Part | |
|---|---|
Animation.glyph(index, length, tick, seed) | Returns RGB in the low 24 bits. Add Animation.OBFUSCATED to scramble the character or return Animation.HIDDEN to hide it. index is the character within the tag, length the number of characters, tick the clock (20 per second), seed stable per line. |
AnimationParams | The tag's options: getString, getDouble, getBoolean, getColor, getColors(key, default), has. Keys ignore case and _/-; bare colours in a tag arrive as colors. |
AnimationException | Throw it from the factory for a missing or bad option; the message is shown to the admin (console, /nametag reload). |
Names are a-z, 0-9, _ and -. If the name is a standard MiniMessage tag (rainbow, gold...)
only <anim:name> works. Server owners can also make presets of your type in animations.yml
(type: blink). Register it in onEnable: lines refresh to pick it up.
What is not in the API
Templates, lines and styles are not set through the API. When you need it, run the admin commands, which also save the change:
Bukkit.dispatchCommand(Bukkit.getConsoleSender(), "nametag set " + player.getName() + " template event-winner");
Bukkit.dispatchCommand(Bukkit.getConsoleSender(), "nametag unset " + player.getName() + " template");Commands that change a player's design need the server thread on Paper (on Folia, the global region). For read-only data in another plugin's text, the placeholders are often simpler than the API.