API interface for interacting with EssentialsC's nickname system. Nicknames are
stored in SQLite and cached in memory on player join. All database operations
return CompletableFuture — do not block the main thread waiting on
them. Cache reads (getCachedNickname) are synchronous.
Retrieve an instance via EssentialsCAPI.getNickApi().
NickApi nick = APIProvider.getAPI().getNickApi();
nick.getNickname(player.getUniqueId()).thenAccept(opt -> {
String display = opt.orElse(player.getName());
player.sendMessage("Your name: " + display);
});
Method Summary
| CompletableFuture<Optional<String>> | getNickname(UUID uuid) Returns the stored nickname for the given player, checking cache then database. |
| String | getCachedNickname(UUID uuid) Returns the cached nickname synchronously, or null if not cached. |
| CompletableFuture<Optional<UUID>> | getUUIDByNickname(String nickname) Looks up the UUID of the player who owns the given nickname. |
| CompletableFuture<Boolean> | isNicknameTaken(String nickname, UUID excludeUuid) Returns whether the given nickname is already in use by another player. |
| CompletableFuture<Boolean> | setNickname(UUID uuid, String nickname) Sets or overwrites the nickname for the given player. |
| CompletableFuture<Boolean> | removeNickname(UUID uuid) Removes the nickname for the given player from the database and cache. |
| void | applyNickname(Player player) Applies the stored nickname as the player's display name and updates the tab list. |
| void | clearNickname(Player player) Resets the player's display name to their real username and clears the cache entry. |
Returns the stored nickname for the given player, if one exists. Checks the in-memory cache first; falls back to the database if not cached. The optional is empty if the player has no nickname set.
Do not block the main thread waiting on this future.
Parameters:| uuid | the UUID of the player; must not be null |
| CompletableFuture<Optional<String>> | an Optional containing the raw MiniMessage nickname string, or Optional.empty() if none |
Returns the cached nickname for the given player synchronously, or null if the player is not in the cache. Does not hit the database. Safe to call on the main thread.
| uuid | the UUID of the player; must not be null |
| String | the raw MiniMessage nickname string, or null if not cached |
Looks up the UUID of the player who owns the given nickname. Matching is case-insensitive. The optional is empty if no player has that nickname set.
Do not block the main thread waiting on this future.
Parameters:| nickname | the nickname to search for; must not be null |
| CompletableFuture<Optional<UUID>> | an Optional containing the owner's UUID, or Optional.empty() if not found |
Returns whether the given nickname is already in use by another player. The excludeUuid parameter allows you to exclude the player currently holding the nickname — useful when updating a player's own nickname.
Do not block the main thread waiting on this future.
Parameters:| nickname | the nickname to check; must not be null |
| excludeUuid | the UUID of the player to exclude from the check; must not be null |
| CompletableFuture<Boolean> | true if another player already has this nickname |
Sets or overwrites the nickname for the given player. The nickname string may contain MiniMessage formatting. The value is written to the database and the cache is updated immediately. This method does not apply the nickname visually — call applyNickname(Player) afterwards if the player is online.
Do not block the main thread waiting on this future.
Parameters:| uuid | the UUID of the player; must not be null |
| nickname | the nickname to set (may contain MiniMessage tags); must not be null |
| CompletableFuture<Boolean> | true on success |
Removes the nickname for the given player from the database and cache. The future resolves false if the player had no nickname set. This method does not reset the player's display name — call clearNickname(Player) afterwards if the player is online.
Do not block the main thread waiting on this future.
Parameters:| uuid | the UUID of the player; must not be null |
| CompletableFuture<Boolean> | true if a nickname was found and removed, false if the player had none |
Applies the player's stored nickname as their Adventure display name and updates the tab list. Fetches the nickname from cache or database asynchronously, then applies it on the main thread. Has no effect if the nick system is disabled in config or if the player has no nickname. Safe to call from any thread.
Parameters:| player | the online player to apply the nickname to; must not be null |
Resets the player's display name to their real username and clears their nickname from the cache. Also triggers a tab list update. Does not remove the nickname from the database — use removeNickname(UUID) for permanent removal. Must be called on the main thread.
| player | the online player whose nickname to clear; must not be null |