Skip to content

Custom Placeholders

CodeCrafter47 edited this page Sep 8, 2022 · 10 revisions

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

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:

  1. !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.

    Schema:

    <name>:
      !conditional
      parameters: <Number>
      condition: <Expression>
      true: <Text>
      false: <Text>
  2. !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>
  3. !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>
  4. !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
  5. 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>
  6. !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']
  7. !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.

  8. !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:

  1. The condition is evaluated to determine whether the player is afk.
  2. 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 AdvancedTabOverlay. Have a look at the Hidden Players page for more information on vanish support.

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:

We use the server_tps_1 placeholder from PlaceholderAPI which returns the average TPS from the past minute.
You can also use server_tps_1_colored to get the TPS with color already applied to it. This example here however allows you to define more colors.

Remember to have PlaceholderAPI installed and to have the Server Expansion installed (/papi ecloud download server) for this custom placeholder to work.

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
    condition: ${viewer server_tps_1} > 20
    true: "&a*20.00"
    false: "&e${colored_tps0}"

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: ${viewer server_tps_1} >= 18
    true: "&a${viewer server_tps_1}"
    false: "${colored_tps1}"

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: ${viewer server_tps_1} >= 15
    true: "&e${viewer server_tps_1}"
    false: "${colored_tps2}"

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${viewer server_tps_1}"
    false: "&c${viewer server_tps_1}"

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

- "&cTPS: ${colored_tps}"

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}"

Clone this wiki locally