Skip to content

Placeholders

Jump to bottom
NEZNAMY edited this page Jan 15, 2023 · 95 revisions

Content

About

TAB offers various placeholders to display the most common information. It also supports PlaceholderAPI placeholders.

Internal placeholders

Basic placeholders provided by the plugin. Most of these placeholders were added because they were requested by people who don't want to install another plugin just to show username. Some of them have configurable output in config.yml in Placeholders section. Unused placeholders do not affect performance in any way.

Placeholders must be refreshed. All internal placeholders have manually defined refresh interval, which I found the most optimal and cannot be changed. Time is in milliseconds. -1 is used for placeholders which are in fact constants (such as %player%), or fire an event each time they change, which can be listened to (such as %world%) and value updated. Refresh interval for conditions is set to be equal to fastest refreshing placeholder used inside each condition.

Warning: Trying to use a bukkit-only placeholder on bungeecord because you decided to copypaste config to bungee installation will result in those placeholders to not work! Use their PlaceholderAPI alternatives with PlaceholderAPI support on bungeecord.

Universal

Identifier Refresh interval Description
%online% 1000 total online player count (excluding vanished players)
%world% -1 name of world where player is
%worldonline% 1000 amount of players in the same world (excluding vanished players)
%ping% 500 Player's ping to the server where TAB is installed.
Note: This value is measured by the server and TAB is only retrieving that value. If it's wrong, it's not a TAB issue.
%player% -1 player's real name, result of .getName(), cannot be fooled by plugins that change player name
%time% 500 current real time, output configurable in config.yml
%date% 60000 current date, output configurable in config.yml
%staffonline% 2000 amount of online players with tab.staff permission
%nonstaffonline% 2000 amount of online players without tab.staff permission ( online - staffonline )
%memory-used% 200 used RAM of server in MB
%memory-max% -1 total RAM of server in MB
%memory-used-gb% 200 used RAM of server in GB
%memory-max-gb% -1 total RAM of server in GB
%player-version% -1 version of player, such as "1.14.4"
%player-version-id% -1 network ID of player's version
%luckperms-prefix% 1000 prefix from LuckPerms from the same instance when TAB is installed
%luckperms-suffix% 1000 suffix from LuckPerms from the same instance when TAB is installed
%displayname% 500 display name set by permission plugin, typically prefix + name + suffix
%group% 1000 Returns player's primary group name. Used for internal functionality, but can be used as a display placeholder as well.
%vanished% 1000 Returns true/false based on player's vanish status. Used for internal functionality, but can be used as a display placeholder as well.
%% -1 Returns the % symbol. Useful to display % symbol without breaking all placeholders after it

Bukkit only

Identifier Refresh interval Description
%health% 100 Player's health, rounded up to match Minecraft's heart display.
%tps% 1000 TPS of server from the last minute (measured by server)
%vault-prefix% 1000 prefix of player detected by Vault
%vault-suffix% 1000 suffix of player detected by Vault
%afk% 500 afk status of player, detected by Essentials / Purpur
%mspt% 1000 server's current milliseconds per tick (requires paper core)
%essentialsnick% -1 Nickname from Essentials, otherwise player's name

BungeeCord only

Identifier Refresh interval Description
%server% -1 name of server where player is
%serveronline% 1000 amount of online players on server where the player is (excluding vanished players)
%online_<servername>% 1000 amount of online players on specified server (excluding vanished players)

PlaceholderAPI

PlaceholderAPI is supported and relational placeholders are supported too. When parsing relational placeholders, TAB puts viewer as the first player argument and target player as second argument.

You can find most of placeholders that PlaceholderAPI offers on PlaceholderAPI wiki. Some plugins are not listed there, for those you'll need to check their own wiki for placeholders.

TAB also offers its own placeholders into PlaceholderAPI. To enable the expansion, set

placeholders:
  register-tab-expansion: true

in config.yml.

Full list of placeholders:

Identifier Description
%tab_tabprefix% Current tabprefix with replaced placeholders
%tab_tabsuffix% Current tabsuffix with replaced placeholders
%tab_tagprefix% Current tagprefix with replaced placeholders
%tab_tagsuffix% Current tagsuffix with replaced placeholders
%tab_customtabname% Current customtabname with replaced placeholders
%tab_customtagname% Current customtagname with replaced placeholders
%tab_belowname% Current belowname with replaced placeholders
%tab_abovename% Current abovename with replaced placeholders
%tab_tabprefix_raw% Raw tabprefix containing unparsed placeholders
%tab_tabsuffix_raw% Raw tabsuffix containing unparsed placeholders
%tab_tagprefix_raw% Raw tagprefix containing unparsed placeholders
%tab_tagsuffix_raw% Raw tagsuffix containing unparsed placeholders
%tab_customtabname_raw% Raw customtabname containing unparsed placeholders
%tab_customtagname_raw% Raw customtagname containing unparsed placeholders
%tab_belowname_raw% Raw belowname containing unparsed placeholders
%tab_abovename_raw% Raw abovename containing unparsed placeholders
%tab_scoreboard_name% Returns name of player's currently displayed scoreboard or empty string if none is displayed due to no display condition being met
%tab_scoreboard_visible% "Enabled" if visible, "Disabled" if not
%tab_bossbar_visible% "Enabled" if visible, "Disabled" if not
%tab_nametag_preview% "Enabled" if previewing armor stands using /tab nametag preview, "Disabled" if not
%tab_nametag_visibility% "Enabled" if player can see nametags, "Disabled" if disabled using /tab nametag toggle
%tab_replace_<placeholder>% Applies Placeholder output replacements to a PlaceholderAPI placeholder (for example %tab_replace_essentials_vanished%)
%tab_placeholder_<placeholder>% returns value of tab's internal placeholder (such as %tab_placeholder_animation:name% for %animation:name%)

Relational placeholders

About

Unlike classic placeholders which take either 0 (placeholders with same output for all players) or 1 (per-player placeholders) players, relational placeholders take in 2 players. The first usage was to display relation between two players, specifically enemies / allies (red / green) for factions, allowing players to see faction names of other players colored based on relation.

Usage

TAB does not offer any internal relational placeholders. However, it has full support for PlaceholderAPI placeholders. You can also register your own relational placeholders using the API. In PlaceholderAPI, all relational placeholder identifiers must start with %rel_. Same rule is used for placeholders registered with the API as well.
When passing players into the function, first player is the player viewing the text, second player is the one text is being displayed on.

When trying to use placeholders from other plugins, you will need to check their documentation and search for relational placeholders. If your plugin does not appear to offer any, you ran out of luck and TAB cannot do anything about it.

Refreshing

Refresh intervals

TAB is refreshing placeholders in intervals. For internal placeholders it's using values I found the most optimal and set directly in the plugin. Refresh intervals for PlaceholderAPI placeholders can be configured.

Sync refreshing

By default, all placeholders are refreshed asynchronously so they don't slow down the server, since reading should be a thread-safe operation. Some placeholders, however, require to be refreshed in the main thread, causing problems or throwing errors when refreshed asynchronously. For these, replace them with %sync:<original placeholder>% and they will be refreshed in the main thread, for example %sync:server_total_entities%.
Keep in mind that now you should configure reasonable refresh interval for these placeholders to not cause TPS drops (with async placeholders it doesn't really matter). Configured refresh intervals and CPU usage of placeholders can be checked using /tab cpu.

Placeholder is not working

When using a placeholder, you should know if it's a TAB's internal placeholder or a PlaceholderAPI placeholder. If you don't, that's the problem.

Note: Don't forget that using % symbol will mess up placeholder starts and ends, breaking all placeholders after it. To make the symbol display correctly without messing up placeholders, use %% instead.
Example: Sale 100% OFF! -> Sale 100%% OFF!.

Internal placeholder is not working

All TAB's internal placeholders are listed above. Some of them are bukkit only (meaning they won't work on bungeecord) and some are bungee only. Trying to use a bukkit-only placeholder on bungeecord as a result of copypasting the config from bukkit version thinking it's identical will not work for you and those placeholders will not work.
If you want to use those, set up PlaceholderAPI support on bungeecord and find their PlaceholderAPI equivalent. Large portion of those are included on PlaceholderAPI's wiki.
For example you can use %vault_prefix% instead of %vault-prefix%, %essentials_afk% instead of %afk% and so on.

PlaceholderAPI placeholder is not working

If you have TAB installed on bungeecord, make sure you set up PlaceholderAPI support on bungeecord as there is no other way to retrieve data from technically a different server.

If you have TAB on bukkit or the previous step did not work, make sure it works when using /papi parse me <placeholder>. If it does not work, the issue is not on TAB's end. Most of the time it's just a missing expansion (/papi ecloud download <name> and /papi reload).

API

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

For working with placeholders, you will need the PlaceholderManager. Get it using TabAPI.getInstance().getPlaceholderManager().

Placeholders have two attributes:

  • An identifier, which is used to uniquely identify the placeholder. This is also what's usually used for replacement. For example, in %uptime%, the identifier is %uptime%.
  • A refresh rate in milliseconds, which is how often the placeholder's refresh function will be called, to get a new value to display.

Server placeholders

Server placeholders are global to the entire plugin. Their values are not dependent on player.
Examples of server placeholders would be uptime and TPS placeholders.

To register a new server placeholder, use PlaceholderManager#registerServerPlaceholder(String, int, Supplier<Object>). The first two parameters are explained above, and the last parameter is a function that will be called to refresh the value of the placeholder. Example:

TabAPI.getInstance().getPlaceholderManager().registerServerPlaceholder("%system-time%", 50, () -> System.currentTimeMillis());

This placeholder will show current system time and update every 50 milliseconds.

Player placeholders

Player placeholders are calculated on a per-player basis. These depend on the player that we want to get the value for.
Examples of player placeholders would be nickname and prefix.

To register a new player placeholder, use PlaceholderManager#registerPlayerPlaceholder(String, int, Function<TabPlayer, Object>). The first two parameters are explained above, and the last parameter is a function that will be called to refresh the value of the placeholder. Example:

TabAPI.getInstance().getPlaceholderManager().registerPlayerPlaceholder("%player-uuid%", -1, player -> player.getUniqueId());

This placeholder will show player's UUID and never refreshes, since UUID doesn't change at runtime.

Relational placeholders

Relational placeholders are calculated using a pair of players, instead of a single one. These depend on the player pair that we want to get the value for. Their identifier must start with rel_.

To register a new relational placeholder, use PlaceholderManager#registerRelationalPlaceholder(String, int, BiFunction<TabPlayer, TabPlayer, Object>). The first two parameters are explained above, and the last parameter is a function that will be called to refresh the value of the placeholder. Example:

TabAPI.getInstance().getPlaceholderManager().registerRelationalPlaceholder("%rel_staff_version%", 1000, (viewer, target) -> {
    if (viewer.hasPermission("tab.staff")) {
        return target.getVersion().getFriendlyName();
    } else {
        return "";
    }
});

This placeholder will show version of players, but only to those, who have tab.staff permission. First player in the method is viewer, second player is target. Same order is applied when hooking into PlaceholderAPI as well.

Getting started

Core features

Functions

Other

Clone this wiki locally