UpdateDisplayNames

Overview

UpdateDisplayNames is a Paper plugin which automatically updates the display name and tablist name of the players to a specified format.

Features

• Supports LuckPerms, Vault and PlaceholderAPI
• Supports both MiniMessage and legacy color codes in placeholders
• Has an API which allows to exclude specific players from the display name updates

How to install

To install this plugin, download the plugin for the correct minecraft version from the releases page and put it into your plugins directory.

Commands

Configuration

Config file

To change the prefixes or other values, you can do this in the plugins/UpdateDisplayName/config.yml:

# UPDATE DISPLAY NAME CONFIGURATION FILE

# ----- GENERAL SECTION -----

# The interval in seconds the names are updated (default: 60).
# Set to < 0 to disable auto-update.
# When disabled, the name of a player will only updated on join.
update_interval: 30

# ----- DISPLAYNAME SECTION -----

displayname:
  # Enables updating the display name.
  # The display name of a player is shown everywhere except the tablist.
  enable: true
  # Here you can set the display name format.
  # The format of this field is explained in the "Name format configuration".
  format: '<luckperms:prefix><player><luckperms:suffix>'
  
# ----- TABLIST SECTION -----

tablist:
  name:
    # Enables updating the tablist name.
    # The tablist name is the name shown in the tablist.
    # It is different from the player's display name, which is shown everywhere else.
    enable: true
    # Here you can set the tablist name format.
    # The format of this field is explained in the "Name format configuration".
    format: '<luckperms:prefix><player><luckperms:suffix>'
  sort:
    # Enables tablist sorting using the tablist sort permission.
    enable: true
    # The highest tablist sorting level.
    # Levels higher than this will be ignored.
    max_level: 9

Since the config file is auto-generated on first start, the order of the config values might be a bit different (but the values are the same).

The auto-generated config (the config you will see after you have installed the plugin) does not have quotes on strings. It is recommended to use quotes ("" or '') for longer string values like displayname.format and tablist.name.format.

WARNING: When you already have a config from version 1.0, you need to update your configuration. The tablist section has been changed, and the plugin assumes the default values for unset config options.

Name format configuration

This section explains, how the format options can be configured.

Please note that this format DOES NOT support legacy color codes. You have to use MiniMessage. But don't worry, it's easy:

• &0 = <black>, &1 = <dark_blue>, &2 = <dark_green>, etc...
• &l = <bold>, &m = <strikethrough>, &n = <underline>, &r = <reset>, etc...

More information: MiniMessage Documentation
Placeholders support both MiniMessage and legacy color codes.

Available placeholders:

• LuckPerms: <luckperms:prefix> <luckperms:suffix> <luckperms:group>
• Vault: <vault:prefix> <vault:suffix> <vault:group>
• PlaceholderAPI: <papi:PLACEHOLDER>

Using the API

Import

Using gradle:

repositories {
    maven("https://maven.chaossquad.net/releases")
}

dependencies {
    compileOnly("net.jandie1505:UpdateDisplayName:1.0-RELEASE")
}

Using maven:

<repository>
  <id>ChaosSquad-Repository-releases</id>
  <name>ChaosSquad Repository</name>
  <url>https://maven.chaossquad.net/releases</url>
</repository>

<dependency>
  <groupId>net.jandie1505</groupId>
  <artifactId>UpdateDisplayName</artifactId>
  <version>1.0-RELEASE</version>
  <scope>provided</scope>
</dependency>

Usage

public class ApiExampleClass {

    /**
     * General features.
     */
    public void ApiExample() {
        UDNApi api = UpdateDisplayName.getApi();

        Player player = Bukkit.getPlayer("playername");

        boolean updatesEnabled = api.isUpdatesEnabled(); // Get plugin functionality status
        api.setUpdatesEnabled(false); // Disable plugin functionality

        api.updatePlayers(); // Update display names of all players
        api.updatePlayer(player); // Update display name of the specified player

        Set<UUID> excludedPlayers = api.getExcludedPlayers(); // Get excluded players
        boolean excluded = api.isPlayerExcluded(player); // Check if a player is excluded

        DataStorage config = api.getPluginConfig(); // Get plugin config

        // Get config values
        boolean enableDisplaynameUpdate = config.optBoolean(UpdateDisplayname.CONFIG_ENABLE_DISPLAYNAME, false);
        String displayNameFormat = config.optString(UpdateDisplayName.CONFIG_FORMAT_DISPLAYNAME, null);
        boolean enableTablistName = config.optString(UpdateDisplayName.CONFIG_ENABLE_TABLIST_NAME, false);
        String tablistFormat = config.optString(UpdateDisplayName.CONFIG_TABLIST_FORMAT, null);
        int updateInterval = config.optInt(UpdateDisplayName.CONFIG_UPDATE_INTERVAL, 60);

        // Set config values
        config.set(UpdateDisplayName.CONFIG_ENABLE_DISPLAYNAME, true);
        config.set(UpdateDisplayName.CONFIG_FORMAT_DISPLAYNAME, "<luckperms:prefix><player><luckperms:suffix>");
        config.set(UpdateDisplayName.CONFIG_ENABLE_TABLIST_NAME, true);
        config.set(UpdateDisplayName.CONFIG_TABLIST_FORMAT, "<luckperms:prefix><player><luckperms:suffix>");
        config.set(UpdateDisplayName.CONFIG_UPDATE_INTERVAL, 60);
    }

    /**
     * Event for updated display name.
     */
    @EventHandler
    public void onDisplayNameUpdated(DisplayNameUpdatedEvent event) {

        if (event.getPlayer().getName().equals("forbiddenName")) {
            event.setCancelled(true);
            return;
        }

        if (event.getUpdatedDisplayName() == null) {
            Bukkit.broadcast(Component.text("Display name of " + event.getPlayer().getName() + " has been reset"));
            return;
        }

        Bukkit.broadcast(Component.empty()
            .append(Component.text("Updated display name of player " + event.getPlayer().getName() + ": "))
            .append(event.getUpdatedDisplayName())
        );

    }

    /**
     * Event for updated tablist name.
     */
    @EventHandler
    public void onDisplayNameUpdated(TablistNameUpdatedEvent event) {

        if (event.getPlayer().getName().equals("PleaseDontGiveMeATablistName")) {
            event.setCancelled(true);
            return;
        }

        if (event.getUpdatedTablistName() == null) {
            Bukkit.broadcast(Component.text("Tablist name of " + event.getPlayer().getName() + " has been reset"));
            return;
        }

        Bukkit.broadcast(Component.empty()
            .append(Component.text("Updated tablist name of player " + event.getPlayer().getName() + ": "))
            .append(event.getUpdatedTablistName())
        );

    }
}

JavaDocs

Click here to get to the JavaDocs.