Feature guide: Tablist name formatting

Content

• About
• Configuration
  • Introduction
  • Groups and users
  • Per-world / per-server
  • Priority system
  • Placeholder support
  • Additional settings
• Tips & Tricks
• API

About

This feature allows you to configure player name formats in the tablist.

Settings of this feature can be configured in config.yml under tablist-name-formatting section.

Configuration

Introduction

The display name is split into 3 parts for convenience:
tabprefix - first part of the text, this is where prefix is usually configured
customtabname - second part of the text, it will be used as player name. If customtabname is not defined at all (not just setting empty value!), player's original name will be used instead
tabsuffix - last part of the text, this is where suffix is usually configured

These values are then merged together and displayed in the tablist.

Groups and users

Properties can be applied in 2 ways: groups and users. Users can be defined by both username and their UUID. Values applied to users take priority over groups.
groups.yml

admin:
  tabprefix: "&4&lAdmin &r"

This can also be achieved with commands, in this case /tab group admin tabprefix "&4&lAdmin &r".

users.yml

_NEZNAMY_:
  tabprefix: "&6&lTAB &r"

# An alternate way using UUID
237d8b55-3f97-4749-aa60-e9fe97b45062:
  tabprefix: "&6&lTAB &r"

This can also be achieved with commands, in this case /tab player _NEZNAMY_ tabprefix "&6&lTAB &r" or /tab playeruuid _NEZNAMY_ tabprefix "&6&lTAB &r".

Properties can also be set as "default" for everyone who does not have them defined. For that purpose, a group keyword _DEFAULT_ was made.
groups.yml

admin:
  tabprefix: "&4&lAdmin &r"
_DEFAULT_:
  tabprefix: "&7" # This will be displayed on everyone except admin

Per-world / per-server

Values can also be applied per-world (and per-server on bungeecord), where they can be defined per group/user. These values take priority over global settings. Example:
groups.yml

per-world:
  world1:
    _DEFAULT_:
      tabprefix: "&a" # Everyone in world "world1" will have this prefix
per-server:
  server1:
    _DEFAULT_:
      tabprefix: "&a" # Everyone in server "server1" will have this prefix

For multiple worlds/servers to share the same settings, separate them with ;.
For worlds/servers starting with a specified text, use * after shared part. For ending with a shared part, use * at the beginning.
Example:

per-world:
  world1;world2:
    _DEFAULT_:
      tabsuffix: "Shared tabsuffix in worlds world1 and world2"
  lobby-*:
    _DEFAULT_:
      tabsuffix: "Suffix in all worlds starting with lobby-"

Priority system

Full list of priorities looks like this:

1. value set using the API
2. per-world / per-server applied to username
3. value applied to username
4. per-world / per-server applied to uuid
5. value applied to uuid
6. per-world / per-server applied to player's group
7. per-world / per-server applied to group _DEFAULT_
8. value applied to player's group
9. value applied to group _DEFAULT_

This list is browsed through until the first match is found. If no match is found, empty value is used (except customtabname, which defaults to player's name).

Values are taken independently from each other. This means you can set per-world tabprefix, but only keep one global tabsuffix for example.

You can see source of a value displayed on player by using /tab debug <player> and checking "source" part of the value you are looking for.

Placeholder support

All values fully support TAB's internal placeholders and PlaceholderAPI placeholders including relational placeholders. Amount of placeholders is not limited and they can be used in combination with static text as well.

Additional settings

Option name	Default value	Description
enabled	true	Enables / Disables the feature
anti-override	true	When enabled, prevents other plugins from overriding TAB. This results in slightly higher CPU usage, but will make sure the function works as expected. Unlike with teams, attempts to override TAB are not logged into anti-override.log file. This is due to high amount of false positives from TAB's own features, as well as bungeecord server switch, higher CPU usage and more. Whether you need this or not depends on how properly your plugins are configured. Some of them attempt to format tablist even if you'd not expect it from such plugin. Keep this enabled to stay safe.
disable-condition	%world%=disabledworld	A condition that must be met for disabling the feature for players. Set to empty for not disabling the feature ever.

Tips & Tricks

If you want TAB to only take prefixes/suffixes from permission plugin, delete all groups from groups.yml and only keep this:

_DEFAULT_:
  tabprefix: "%luckperms-prefix%"
  tabsuffix: "%luckperms-suffix%"

API

To get started with the API, see Developer API page.

To access this feature, you'll need to obtain TabListFormatManager instance. Get it using TabAPI.getInstance().getTabListFormatManager(). If this feature is disabled, the method will return null.

To set the values for the respective formatting, use the following:

• TabListFormatManager#setPrefix(TabPlayer, String)
• TabListFormatManager#setName(TabPlayer, String)
• TabListFormatManager#setSuffix(TabPlayer, String) To reset the values, set them to null.

To get custom values previously set using the API (they will return null if no custom value is set):

• TabListFormatManager#getCustomPrefix(TabPlayer)
• TabListFormatManager#getCustomName(TabPlayer)
• TabListFormatManager#getCustomSuffix(TabPlayer)

To get original value set by the plugin based on configuration:

• TabListFormatManager#getOriginalPrefix(TabPlayer)
• TabListFormatManager#getOriginalName(TabPlayer)
• TabListFormatManager#getOriginalSuffix(TabPlayer)

Note: These values are only temporary, meaning they won't get saved anywhere and will get reset on player quit or plugin reload. If you wish to save these values into file, use commands.