Custom Placeholders

A custom placeholder is a new placeholder that is created in the config. Custom placeholders can

be simple aliases,
add complex logic based on placeholders,
create animations or
do some basic calculations.

Content

Creating Custom Placeholders
Different Types of Custom Placeholders
Useful Custom Placeholders

Creating Custom Placeholders

Custom placeholders can be in the customPlaceholders section in config.yml as well as in the customPlaceholders section of each tab list configuration file. Custom placeholders created in config.yml can be used in all tab list configuration files. Custom placeholders created in a tab list configuration file can only be used in that file.

Each custom placeholder consists of

a name,
a type tag and
options specific to the custom placeholder.

The basic schema of the customPlaceholders looks like this:

customPlaceholders:
  name:
    !tag
    option: value
    option: value
  name:
    !tag
    option: value
    option: value
  ...

Example:

customPlaceholders:
  afk_tag:
    !conditional
    condition: ${player essentials_afk}
    true: "&7|&oaway"
    false: ""

In the example above the name of the custom placeholder is afk_tag, the type tag is !conditional, and we set the three options condition, true and false. That creates the ${afk_tag} placeholder, which will be replaced with &7|&oaway if the player is afk.

Different Types of Custom Placeholders

The following types of custom placeholders are available:

!conditional

The !conditional custom placeholder is replaced with one of two replacements depending on a condition. It offers the following options for customization:
- condition
  
  The condition option is a boolean expression deciding which replacement is used. You can use placeholders and compare them using operators such as =, < or > to create the condition.
  
  Additional information on creating expressions is available on the Expression Syntax page.
- true
  
  The true option sets the replacement text to be used if the condition is true. You can use formatting codes and placeholders.
- false
  
  The false option sets the replacement text to be used if the condition is false. You can use formatting codes and placeholders.
- parameters
  
  The optional parameters option allows creating a custom placeholder with parameters. The parameters option must be set to the number of parameters the placeholder accepts. You can use %0, %1, ... in the other options to refer to the first, second, ... parameter. When using the custom placeholder you can specify parameters by adding them after the placeholder name, separated by spaces: ${name param1 param2 ...}.
  
  Note that the first parameter is %0. If you have e.g. parameters: 5 the last parameter is %4. So if you were to use %5 somewhere it will not be replaced since you have only 5 (not 6) parameters. If you use the placeholder with more parameters that its number of parameters, the last parameter will also contain all the additional parameters.
  
  Example:
  
  Assume you want to create a placeholder that displays Online if a server is online and Offline if a server is offline. Instead of creating a custom placeholder for each server you want to create just one placeholder that has a parameter for the server name. The following code creates a custom placeholder called server_state doing just that:
```
customPlaceholders:
  # ...
  server_state:
    !conditional
    parameters: 1
    condition: ${server:%0 online}
    true: "&aOnline"
    false: "&cOffline"
```
  You can use that placeholder by using ${server_state <server>} anywhere in your config. Just replace <server> with an actual server name. E.g. if you want to display whether the minigames server is online use ${server_state minigames}.
Schema:
```
<name>:
  !conditional
  parameters: <Number>
  condition: <Expression>
  true: <Text>
  false: <Text>
```
!switch

The !switch custom placeholder maps the results of an expression, typically a placeholder, to an arbitrary replacement text. It is often used to create custom prefixes specific to the tab list. The !switch custom placeholder offers the following options for customization:
- expression
  
  The expression option is an expression which is evaluated to select the replacement. The result of evaluating the expression is text. In many cases the expression consists just of a single placeholder. However, that is not required. You can also concatenate multiple placeholders using the . operator.
  
  Additional information on creating expressions is available on the Expression Syntax page.
- replacements
  
  The replacements options defines a map of different replacements for the !switch custom placeholder. The replacement for the !switch custom placeholder is selected by
  1. evaluating the expression and
  2. looking up a replacement for its value in the replacements map.
  Example:
  
  Assuming you set up the expression to return the players group, you can have the placeholder return small tags suitable as prefixes using the following code:
```
replacements:
  "admin": "&c[A]&f"
  "mod": "&b[M]&f"
  "vip": "&b[V]&f"
```
- defaultReplacement
  
  The defaultReplacement option defines the replacement text to be used when there is no suitable replacement in the replacements map.
- parameters
  
  The optional parameters option allows creating a custom placeholder with parameters. Refer to the !conditional custom placeholder type for more information.
Schema:
```
<name>:
  !switch
  parameters: <Number>
  expression: <Expression>
  replacements:
    <value>: <Text>
    <value>: <Text>
    ...
  defaultReplacement: <Text>
```
!animated

The !animated custom placeholder allows creating animations in a simple way. It has the following options:
- elements
  
  The elements is a list of replacement texts for the !animated custom placeholder. The replacements will be used one at a time and cycled through at a configurable interval.
- interval
  
  The interval options controls the interval (in seconds) after which the plugin will switch to the next replacement.
- randomize
  
  The optinal randomize option can be set to either true or false. Not setting it has the same effect as setting it to false. When randomize is set to true the different replacements will be displayed in random order, otherwise they will be cycled through from top to bottom.
- parameters
  
  The optional parameters option allows creating a custom placeholder with parameters. Refer to the !conditional custom placeholder type for more information.
Schema:
```
<name>:
  !animated
  parameters: <Number>
  elements:
    - <Text>
    - <Text>
    ...
  interval: <Number>
  randomize: <true/false>
```
!compute

The !compute custom placeholder can be used to perform some simple calculations. It is simpler to use than the other types of custom placeholders as it does not have any options. You just need to provide a name and the expression to be computed. In the expression you can use placeholders and basic math operators such as +, -, * and /.

Additional information on creating expressions is available on the Expression Syntax page.

Schema:
```
<name>:
  !compute
  <Expression>
```
Example:

The following example creates the ${health_percentage} placeholder, which can be used to display the health as a percentage value.
```
health_percentage:
  !compute
  (${viewer health} / ${viewer max_health}) * 100
```
Alias

The alias custom placeholder type is event more simple. It does not even have a tag. You just need to specify the name and the text that should replace the custom placeholder.

Schema:
```
<name>: <Text>
```
!color_animation

The !color_animation custom placeholder allows creating color gradients, rainbow-like animations and other effects in a simple way. It has the following options:
- effect
  
  Can be one of rainbow, uniformRainbow, random, wave, waveCenter or glitter.
- colors
  
  The colors is a list of colors used in the animation. A color can be a legacy color code such as &a or an rgb color such as #012345.
  
  Needs to be specified for rainbow, uniformRainbow, random, but not the other effects.
- baseColor
  
  Base color used for the animation. A color can be a legacy color code such as &a or an rgb color such as #012345.
  
  Needs to be specified for wave, waveCenter and glitter, but not the others.
- effectColor
  
  Highlight color used for the animation. A color can be a legacy color code such as &a or an rgb color such as #012345.
  
  Needs to be specified for wave, waveCenter and glitter, but not the others.
- distance
  
  The distance between two colors. If this is not set, the distance is calculated such that the first color is applied to the first letter of the text and the last color is applied to the last letter of the text.
- speed
  
  Determines how fast the colors move through the text. Can be zero or negative to inverse the direction.
- formats
  
  Sets formatting codes that should be applied to the color animation. You have to provide valid formatting codes such as &l for bold or &o for italic.
Schema:
```
<name>:
  !color_animation
  colors: [<color>, <color>, ..., <color>]
  distance: <Number>
  speed: <Number>
  formats: <String>
```
Example: The following example creates the ${my_rainbow <text>} placeholder which applies a slowly shifting rainbow effect to the text. It can be used e.g. using ${my_rainbow This is some lovely rainbow text}.
```
customPlaceholders:
  my_rainbow:
    !color_animation
    colors: ['#FF0000', '#FFA500', '#FFFF00', '#32CD32', '#00BFFF', '#8A2BE2', '#EE82EE']
```
!progress_bar

The !progress_bar custom placeholder creates a progress bar.

Example: The following example creates the ${health_bar} placeholder which display the health of the player looking at the tab list.
```
customPlaceholders:
  health_bar:
    !progress_bar
    value: ${viewer health}
    maxValue: ${viewer max_health}
    style: hearts
```
Basic options

The following options you will typically use when creating a progress bar:
- value
  
  Expression for the number the progress bar will be based on.
- minValue
  
  Expression for the number corresponding to 0%. If not set the default is 0.
- maxValue
  
  Expression for the number corresponding to 100%.
- style
  
  Style preset. This options allows you use one of the pre-made styles. Using one of the pre-made style sets of the symbolX, borderX, colorX and length options. You can set any of those options yourself, which will take precedence over the pre-definded value, to further customize the appearance of the progress bar.
  
  The following style presets are available:
  
  style preview
  
  default
  
  largediv
  
  tricolor
  
  default_shaded
  
  largediv_shaded
  
  tricolor_shaded
  
  hearts
  
  Shaded variants only work for Minecraft 1.16 or later.
- length
  
  Length of the progress bar (number of symbols the progress bar is made up of).
- textCenter
  
  Text to be displayed on the center of the progress bar. This is optional. If specified it will replace some of the symbols at the middle of the progress bar. You can use it e.g. to display the progress percentage or to display the underlying value of the progress bar. The special placeholders ${progress_percentage}, ${progress_value}, ${progress_min} and ${progress_max} can be used to access the percentage and value of the progress as well as the minimum and maximum value. This should not contain color codes. The text is colored with colors provided by the colorCompleted, colorRemaining and other color options.
  
  Example:
- colorCompleted
  
  Color to use for completed progress.
- colorRemaining
  
  Color to use for remaining progress.
Advanced options

These options allow you to completely customize the appearance of a progress bar.
- symbolCompleted
  
  Symbol (or text) to be used for completed progress. This should not contain color codes. Color codes should be added using the colorCompleted option (or related options).
- symbolRemaining
  
  Symbol (or text) to be used for remaining progress. This should not contain color codes. Color codes should be added using the colorRemaining option (or related options).
- symbolCurrent
  
  Symbol (or text) to be used for current progress (head of the progress bar). This should not contain color codes. Color codes should be added using the colorCurrent option (or related options).
- symbolCurrentSteps
  
  List of symbols (or text) to be used for current progress. By providing multiple symbols the progress can be divided in smaller steps. E.g. providing a half filled heart and a filled heart will display the half filled heart as an in between step to displaying the filled heart. This should not contain color codes. Color codes should be added using the colorCurrent option (or related options). This option is mutually exclusive with symbolCurrent.
  
  Example:
```
symbolCurrentSteps: ["\u25CC", "\u25D0"]
```
- borderLeft
  
  Left border of the progress bar. Does not count towards length.
- borderRight
  
  Right border of the progress bar. Does not count towards length.
- textCenterEmpty
  
  Text to be displayed on the center of the progress bar when it is empty, i.e. the progress is 0.
- textCenterFull
  
  Text to be displayed on the center of the progress bar when it is full, i.e. the progress is 100.
- colorCompletedSteps
  
  Specifies the color to use for completed progress. Divides the progress bar into multiple segments with different color. The number is the percentage where the color is first used. E.g. if there are two entries i: c1 and j: c2 then the color c1 ist used in the interval from i to j - 1. This option is mutually exclusive with colorCompleted.
  
  Example:
```
colorCompletedSteps:
  0: "&a"
  60: "&e"
  80: "&c"
```
- colorCompletedInterpolateSteps
  
  If enabled the color for completed progress is interpolated between individual progress points specified by colorCompletedSteps. This can only be used in conjunction with colorCompletedSteps and thus is mutually exclusive to colorCompleted. This option only works on Minecraft 1.16+.
- colorCurrent
  
  Color to use for current progress, i.e. the symbol that is the head of the progress bar. This is optional. If not set it defaults to the value of colorCompleted.
- colorCurrentInterpolate
  
  If enable the color to use for current progress, i.e. the symbol that is the head of the progress bar, is interpolated between the color used for remaining progress and the color used for completed progress. This option is mutually exclusive to colorCurrent. This option only works on Minecraft 1.16+.
- colorRemainingSteps
  
  Specifies the color to use for remaining progress. Divides the progress bar into multiple segments with different color. The number is the percentage where the color is first used. E.g. if there are two entries i: c1 and j: c2 then the color c1 ist used in the interval from i + 1 to j. To specify the color for remaining progress there are three options with are mutually exclusive:
  - colorRemaining
  - colorRemainingSteps and colorRemainingInterpolateSteps
  - colorRemainingFromColorCompleted
- colorRemainingInterpolateSteps
  
  If enabled the color for remaining progress is interpolated between individual progress points specified by colorRemainingSteps. This can only be used in conjunction with colorRemainingSteps and thus is mutually exclusive to colorRemaining. This option only works on Minecraft 1.16+.
- colorRemainingFromColorCompleted
  
  If enabled the color for remaining progress is computed as a dark version of the color for completed progress. This option only works on Minecraft 1.16+.
- colorEmptyBar
  
  Color to use for the bar when it is empty, i.e. the progress is 0. This is optional. If not set it defaults to the color used for remaining progress.
- colorFullBar
  
  Color to use for the bar when it is full, i.e. the progress is 100. This is optional. If not set it defaults to the color used for completed progress.
- emptyBarShowSymbols
  
  Whether the progress symbols are shown if the bar is empty. If this is set to false the symbols will be replaced with spaces.
- fullBarShowSymbols
  
  Whether the progress symbols are shown if the bar is full. If this is set to false the symbols will be replaced with spaces.
- emptyBar
  
  Text to replace the entire progress bar with, if it is empty i.e. the progress is 0. This is optional. If used this text will be shown instead of the entire bar (including the border) when the progress is 0.
- fullBar
  
  Text to replace the entire progress bar with, if it is full i.e. the progress is 100. This is optional. If used this text will be shown instead of the entire bar (including the border) when the progress is 100.
!select

The !select custom placeholder can be seen as an enhanced version of the !switch custom placeholder.

The major difference is that instead of having a expression followed by a list of replacements do you have the expressions directly within the replacements map.

Example:
```
customPlaceholders:
  color_prefix:
    !select
    replacements:
      ${player permission color.red}: "&c"
      ${player permission color.green}: "&a"
    defaultReplacement: "&f"
```
- replacements
  
  The replacements options defines a map of different replacements for the !select custom placeholder. Unlike the !switch custom placeholder does this one have some minor differences. The replacement for the !select custom placeholder is selected by
  1. Evaluating the provided expression within the replacements section and
  2. Returns the provided value when the defined expression is true or moves on to the next entry or the defaultReplacement if it reached the end.
  Example:
  
  Assuming you want to return a different color depending on the player's permission, can you use the following code to achieve this:
```
replacements:
  "${player permission color.red}": "&c"
  "${player permission color.green}": "&a"
  "${player permission color.white}": "&f"
```
- defaultReplacement
  
  The defaultReplacement option defines the replacement text to be used when there is no suitable replacement in the replacements map.
- parameters
  
  The optional parameters option allows creating a custom placeholder with parameters. Refer to the !conditional custom placeholder type for more information.
Schema:
```
<name>:
  !select
  parameters: <Number>
  replacements:
    <Expression>: <Text>
    <Expression>: <Text>
    ...
  defaultReplacement: <Text>
```

Useful Custom Placeholders

In the following you will find several useful custom placeholders which you can add to your own configuration.

The `${afk_tag}` Placeholder

The ${afk_tag} custom placeholder created by the following code can be used to display whether a player is afk.

customPlaceholders:
  # ...
  afk_tag:
    !conditional
    condition: ${player essentials_afk}
    true: "&7|&oaway"
    false: ""

The ${afk_tag} custom placeholder works as follows:

The condition is evaluated to determine whether the player is afk.
The custom placeholder is replaced with the text specified by either the true or the false option, depending on whether condition is fulfilled.

After adding the code of the afk_tag placeholder to the customPlaceholders section of your config, you can use it by adding ${afk_tag} to the playerComponent option, in the following example shown for displaying players using the !players component:

- !players
  # ...
  playerComponent: "${player name}${afk_tag}"

Changing the Text

Now if we want to display &7|&oAFK instead of &7|&oaway to identify AFK players we can do that by changing the true option of the afk_tag custom placeholder:

customPlaceholders:
  # ...
  afk_tag:
    !conditional
    condition: ${player essentials_afk}
    true: "&7|&oAFK"
    false: ""

Using a Different AFK Plugin

Let's assume you're not using Essentials but CMI to provide the AFK functionality. Now there's no built-in placeholder for CMI, however we can use the one provided by PlaceholderAPI (assuming it's installed). However the cmi_user_afk placeholder from PlaceholderAPI has one small problem. It doesn't evaluate to true or false like the essentials_afk placeholder does. Instead, it evaluates to §2true if the player is AFK. As you can see it's uppercase and there's a color code. This is good if you want to display the placeholder just like that, but it doesn't work well with the Custom Placeholder mechanic. To fix this issue we can change the condition to check if the output of the cmi_user_afk placeholder is §2true. This leads to the following code:

customPlaceholders:
  # ...
  afk_tag:
    !conditional
    condition: ${player cmi_user_afk} == "§2true"
    true: "&7|&oaway"
    false: ""

Adding a `${vanish_suffix}` Placeholder

The ${vanish_suffix} custom placeholder works similar to the ${afk_tag} custom placeholder and can be used to add a suffix to all vanished players, such that staff who can see other vanished players can tell who is vanished.

customPlaceholders:
  vanish_suffix:
    !conditional
    condition: ${player is_hidden}
    true: "&b|v"
    false: ""

Using the ${player is_hidden} placeholder in the condition makes this custom placeholder work with all vanish plugins supported by BungeeTabListPlus. Have a look at the Hidden Players page for more information on vanish support.

Creating the `${server_state}` Placeholder to Display Whether a Server is Online

Now we want to leverage the Custom Placeholder mechanic to display whether a server is online or offline. For that purpose we use the ${server online} placeholder as condition. It will be true if the server is online and false otherwise.

customPlaceholders:
  # ...
  server_state:
    !conditional
    parameters: 1
    condition: ${server:%0 online}
    true: "&aOnline"
    false: "&cOffline"

We use the server_state placeholder created by the above code to display whether a specific server is online by using ${server_state <server>} somewhere in the config, where <server> needs to be replaced with an actual server name. E.g. if you want to show whether the survival server is online use ${server_state survival}.

Alternative Definition of the `${server_state}` Placeholder

There are several ways to create a custom placeholder to display whether a server is online. In the following we have a look at an alternative that can also be used in the serverHeader of the !players_by_server component. To make that possible the parameter is used slightly differently:

customPlaceholders:
  # ...
  server_state:
    !conditional
    parameters: 1
    condition: ${%0 online}
    true: "&aOnline"
    false: "&cOffline"

If we want to display whether a specific server is online using that definition we need to use ${server_state server:<server>}. E.g. when displaying whether the survival server is online we need to use ${server_state server:survival}. As you can see we need to add the server: prefix when using the server_state placeholder since it is no longer part of the changed custom placeholder definition.

The advantage of this change is that we can now use the server_state placeholder in the serverHeader option of the !players_by_server component using ${server_state server}. The following example shows how that works.

components:
- !players_by_server
  playerSet: all_players
  serverHeader:
  - {text: "&e&n${server}", icon: "colors/yellow.png", ping: 0}
  - {text: "${online_state}", icon: "colors/yellow.png", ping: 0}
  - {text: "&e${server_player_count} Players", icon: "colors/yellow.png", ping: 0}
  showServers: ALL
  playerComponent: "${player name}"
  morePlayersComponent: {text: "&7... and &e${other_count} &7others", icon: "colors/gray.png", ping: 0}

Change the Color of Players on a Different Server - `${other_server_prefix}`

The above example uses a Custom Placeholder to make player which are not on the same server as the player looking at the tab list appear in gray.

To achieve this we create a custom placeholder. Its condition compares the server of a player displayed on the tab list with the server of the player looking at the tab list. If they are the same the condition evaluates to true, and the placeholder is replaced with the white color code set as the true option. Otherwise the condition evaluated to false, and the placeholder is replaced with the content of the false option, in our case a gray color code.

customPlaceholders:
  other_server_prefix:
    !conditional
    condition: ${viewer server} == ${player server}
    true: "&f"
    false: "&7"

Then we add the ${other_server_prefix} placeholder in the playerComponent option as a prefix to the player's name.

playerComponent: "${other_server_prefix}${player name}"

You can find the complete configuration file used in this example at https://github.com/CodeCrafter47/BungeeTabListPlus/wiki/Examples#global-tab-list-dynamic-size.

The `${viewer_colored_ping}` Placeholder

In this example we look at how we can add a color code to the ping depending on how good it is. The following table shows the desired color scheme:

Ping	Color
0 to 49	Green
50 to 149	Yellow
150 and above	Red

Now we have three cases, but using a single conditional placeholder we can only distinguish two cases. We solve this problem by using two conditional placeholders.

The first placeholder viewer_colored_ping0 will check whether the ping is less than 50 and then color it either green or yellow:

customPlaceholders:
  viewer_colored_ping0:
    !conditional
    condition: ${viewer ping} < 50
    true: "&a${viewer ping}"
    false: "&e${viewer ping}"

The second placeholder viewer_colored_ping will check if the ping is less than 150. If so it'll let the first placeholder do its job, otherwise it'll color the ping in red.

  viewer_colored_ping:
    !conditional
    condition: ${viewer ping} < 150
    true: ${viewer_colored_ping0}
    false: "&c${viewer ping}"

Now the second placeholder can be used in the config to display the ping in different colors:

- "&cPing: ${viewer_colored_ping}ms"

Create a Generalized Version using Parameters

The ${viewer_colored_ping} we just created always displays the ping of the player looking at the tab list. Here we'll look at how we can generalize it so we can also use it do display the ping of players displayed on the tab list. For the purpose we add a parameter to our custom placeholder. This can be done by just telling the plugin that this placeholder has one parameter.

customPlaceholders:
  colored_ping0:
    !conditional
    parameters: 1
    condition: ${%0 ping} < 50
    true: "&a${%0 ping}"
    false: "&e${%0 ping}"
  colored_ping:
    !conditional
    parameters: 1
    condition: ${%0 ping} < 150
    true: ${colored_ping0 %0}
    false: "&c${%0 ping}"

If we use that placeholder we have to specify a parameter. So if we use it as ${colored_ping viewer} then viewer is the parameter and the plugin will replace all the %0 in the placeholder definition with viewer. Thus we can see that ${colored_ping viewer} is exactly the same as the ${viewer_colored_ping} placeholder from the previous section.

In the above example ${colored_ping viewer} to display the ping in the header:

header:
- "&cWelcome &f${viewer name} &6| &fPing: ${colored_ping viewer}"

To display the ping of the players on the tab list we use player as parameter:

playerComponent: "${player name} ${colored_ping player}"

The `${colored_tps}` Placeholder

In this example we look at how we can add a color code to the tps depending on how good it is. The following table shows the desired color scheme:

TPS	Color
Above 20	Green
18 to 20	Green
15 to 17	Yellow
10 to 14	Orange
0 to 9	Red

We have five cases now, but using a single conditional placeholder we can only distinguish two cases so we must use multiple conditional placeholders. We will need four placeholders in total:

The first placeholder colored_tps will check whether the server's tps is above 20, this will stop numbers from going higher and default back to *20.00:

customPlaceholders:
  colored_tps:
    !conditional
    parameters: 1
    condition: ${server:%0 tps} > 20
    true: "&a*20.00"
    false: "&e${colored_tps0 %0}"

The second placeholder colored_tps0 will check to see if the server's tps is at or above 18, and make it green:

  colored_tps0:
    !conditional
    parameters: 1
    condition: ${server:%0 tps} >= 18
    true: "&a${server:%0 tps}"
    false: "${colored_tps1 %0}"

The third placeholder colored_tps1 will check to see if the server's tps is at or above 15, and make it yellow:

  colored_tps1:
    !conditional
    parameters: 1
    condition: ${server:%0 tps} >= 15
    true: "&e${server:%0 tps}"
    false: "${colored_tps2 %0}"

The fourth and final placeholder colored_tps2 will check to see if the server's tps is at or above 10, and make it orange and if it is below 10 it will make the color red:

  colored_tps2:
    !conditional
    parameters: 1
    condition: ${server:%0 tps} >= 10
    true: "&6${server:%0 tps}"
    false: "&c${server:%0 tps}"

Now we can use the colored_tps placeholder to give TPS different colors:

- "&cTPS: ${colored_tps (server)}"

Keep in mind you will need to define the server you want in the custom placeholder.

Creating Custom Prefixes - `${custom_prefix}`

In this example we use the !switch custom placeholder type, to create custom prefixes different to the ones from your permission plugin for use in the tab list.

customPlaceholders:
  # ...
  custom_prefix:
    !switch
    parameters: 1
    expression: ${%0 vault_primary_group}
    replacements:
      "admin": "&c[A]&f"
      "mod": "&b[M]&f"
      "vip": "&b[V]&f"
    defaultReplacement: "&7"

You can edit everything after replacements: to suit your needs.

Then you can use the following placeholders:

Placeholder	Description
`${custom_prefix viewer}`	Prefix of the player viewing the tab list.
`${custom_prefix player}`	Prefix of a player listed in the tab list. For use in the `playerComponent`

To display the custom prefix for each player in the tab list add the ${custom_prefix player} custom placeholder before the name:

playerComponent: "${custom_prefix player}${player name}"

Custom Names for Servers - `${server_display_name}`

Here is a brief explanation how to use the Custom Placeholder mechanism to change the displayed server names.

Step 1:

First you need to add the code for the server_display_name custom placeholder to your config.yml. The replacements section is the part that you want to edit. There the custom display names for your servers are defined.

customPlaceholders:
  server_display_name:
    !switch
    parameters: 1
    expression: "${%0}"
    replacements:
      "creative": "Creative"
      "survival": "Survival"
      "factions": "Factions"
      "sg0": "Minigames"
      "sg1": "Minigames"
      "hidenseek": "Minigames"
      "lobby0": "Lobby"
      "lobby1": "Lobby"
    defaultReplacement: "${%0}"

The above code makes the following new placeholders available for use in your config file:

Placeholder	Description
`${server_display_name viewer server}`	Display name of the server of the player viewing the tab list.
`${server_display_name player server}`	Display name of the server of a player listed in the tab list. For use in the `playerComponent`
`${server_display_name server}`	Display name of the server for use in the `serverHeader` of the Players by Server component.
`${server_display_name server:lobby}`	Display name of a specific server.

Note: If you place the custom placeholder code in config.yml then it is available to all tab lists. You can alternatively place it in the config file of a specific tab list. Then it is only available to that one.

Step 2:

Now you need to go through your tab list configuration files (files in the tabLists folder) and replace all placeholders that display the server name with placeholders that display the server alias.

Here'a a table of where in the file to look and which placeholders to replace with which:

Where	Look for	Replace with
`header`, `footer`, custom text in `components`	`${viewer server}`	`${server_display_name viewer server}`
`serverHeader` in the `!players_by_server` component	`${server}`	`${server_display_name server}`

Note: Do not blindly put the server_display_name placeholder everywhere. Do not use the in the showTo, playerSets and customPlaceholders sections of the config. While technically you can use it there, it is probably not what you want.

Creating Server Specific Prefixes - `${server_prefix}`

Here is a brief explanation how to use the Custom Placeholder mechanism to create a server prefix placeholder:

To do so make the following changes to config.yml:

customPlaceholders:
  server_prefix:
    !switch
    parameters: 1
    expression: "${%0}"
    replacements:
      "creative": "[C]"
      "survival": "[S]"
      "factions": "[F]"
    defaultReplacement: ""

Note: If you place the custom placeholder code in config.yml then it is available to all tab lists. You can also place it in the config file of a specific tab list. Then it is only available to that one.

Then you can use the following placeholders:

Placeholder	Description
`${server_prefix viewer server}`	Prefix of the server of the player viewing the tab list.
`${server_prefix player server}`	Prefix of the server of a player listed in the tab list. For use in the `playerComponent`
`${server_prefix server}`	Prefix of the server for use in the `serverHeader` of the Players by Server component.
`${server_prefix server:lobby}`	Prefix of a specific server.

`${animated_bars}`

The following example creates a ${animated_bars} placeholder that can be used anywhere on the tab list.

customPlaceholders:
  animated_bars:
    !animated
    interval: 0.2
    elements:
    - "&6&c=&6=============="
    - "&6=&c=&6============="
    - "&6==&c=&6============"
    - "&6===&c=&6==========="
    - "&6====&c=&6=========="
    - "&6=====&c=&6========="
    - "&6======&c=&6========"
    - "&6=======&c=&6======="
    - "&6========&c=&6======"
    - "&6=========&c=&6====="
    - "&6==========&c=&6===="
    - "&6===========&c=&6==="
    - "&6============&c=&6=="
    - "&6=============&c=&6="
    - "&6==============&c=&6"

`${animated_color_prefix}`

Another use case for the !animated custom placeholder type is creating a color prefix that changes every second. The following example creates a ${animated_color_prefix} which you can put in front of player names, or any other place, to make the text continuously change its color.

customPlaceholders:
  animated_color_prefix:
    !animated
    interval: 1.0
    randomize: true
    elements:
    - "&9"
    - "&b"
    - "&a"
    - "&e"
    - "&6"
    - "&c"
    - "&d"
    - "&5"

Rainbow Animation

The !color_animation custom placeholder type can be used to create animated rainbow-like effects. In the following example we create the my_rainbow placeholder. The custom placeholder specifies the colors to use. The text is specified when using the placeholder. That way we can apply the effect at multiple places once we've defined the custom placeholder.

customPlaceholders:
  my_rainbow:
    !color_animation
    colors: ['#FF0000', '#FFA500', '#FFFF00', '#32CD32', '#00BFFF', '#8A2BE2', '#EE82EE']

The above code creates the ${my_rainbow <text>} placeholder. When using that placeholder we have to replace <text> with the text we want to apply the effect to. E.g. ${my_rainbow Animated Rainbow Text} will result in .

Static Color Gradients

We can also use the !color_animation custom placeholder type to create static color gradients. The following example creates the gradient_blue_white placeholder which applies a simple color gradient. We set the speed option to 0 to create a static effect.

customPlaceholders:
  gradient_blue_white:
    !color_animation
    colors: ['#00FFFF', '#FFFFFF']
    speed: 0

The above code creates the ${gradient_blue_white <text>} placeholder. When using that placeholder we have to replace <text> with the text we want to apply the effect to. E.g. ${gradient_blue_white static gradient} will result in .

style	preview
`default`
`largediv`
`tricolor`
`default_shaded`
`largediv_shaded`
`tricolor_shaded`
`hearts`

Custom Placeholders

Content

Creating Custom Placeholders

Different Types of Custom Placeholders

!conditional

condition

true

false

parameters

!switch

expression

replacements

defaultReplacement

parameters

!animated

elements

interval

randomize

parameters

!compute

Alias

!color_animation

effect

colors

baseColor

effectColor

distance

speed

formats

!progress_bar

Basic options

value

minValue

maxValue

style

length

textCenter

colorCompleted

colorRemaining

Advanced options

symbolCompleted

symbolRemaining

symbolCurrent

symbolCurrentSteps

borderLeft

borderRight

textCenterEmpty

textCenterFull

colorCompletedSteps

colorCompletedInterpolateSteps

colorCurrent

colorCurrentInterpolate

colorRemainingSteps

colorRemainingInterpolateSteps

colorRemainingFromColorCompleted

colorEmptyBar

colorFullBar

emptyBarShowSymbols

fullBarShowSymbols

emptyBar

fullBar

!select

replacements

defaultReplacement

parameters

Useful Custom Placeholders

The ${afk_tag} Placeholder

Changing the Text

Using a Different AFK Plugin

Adding a ${vanish_suffix} Placeholder

Creating the ${server_state} Placeholder to Display Whether a Server is Online

Alternative Definition of the ${server_state} Placeholder

Change the Color of Players on a Different Server - ${other_server_prefix}

The ${viewer_colored_ping} Placeholder

Create a Generalized Version using Parameters

The ${colored_tps} Placeholder

Creating Custom Prefixes - ${custom_prefix}

Custom Names for Servers - ${server_display_name}

Step 1:

Step 2:

`!conditional`

`condition`

`true`

`false`

`parameters`

`!switch`

`expression`

`replacements`

`defaultReplacement`

`parameters`

`!animated`

`elements`

`interval`

`randomize`

`parameters`

`!compute`

`!color_animation`

`effect`

`colors`

`baseColor`

`effectColor`

`distance`

`speed`

`formats`

`!progress_bar`

`value`

`minValue`

`maxValue`

`style`

`length`

`textCenter`

`colorCompleted`

`colorRemaining`

`symbolCompleted`

`symbolRemaining`

`symbolCurrent`

`symbolCurrentSteps`

`borderLeft`

`borderRight`

`textCenterEmpty`

`textCenterFull`

`colorCompletedSteps`

`colorCompletedInterpolateSteps`

`colorCurrent`

`colorCurrentInterpolate`

`colorRemainingSteps`

`colorRemainingInterpolateSteps`

`colorRemainingFromColorCompleted`

`colorEmptyBar`

`colorFullBar`

`emptyBarShowSymbols`

`fullBarShowSymbols`

`emptyBar`

`fullBar`

`!select`

`replacements`

`defaultReplacement`

`parameters`

The `${afk_tag}` Placeholder

Adding a `${vanish_suffix}` Placeholder

Creating the `${server_state}` Placeholder to Display Whether a Server is Online

Alternative Definition of the `${server_state}` Placeholder

Change the Color of Players on a Different Server - `${other_server_prefix}`

The `${viewer_colored_ping}` Placeholder

The `${colored_tps}` Placeholder

Creating Custom Prefixes - `${custom_prefix}`

Custom Names for Servers - `${server_display_name}`

Creating Server Specific Prefixes - `${server_prefix}`

`${animated_bars}`

`${animated_color_prefix}`