Placeholders and tags
On this page6 sections
Everything the plugin understands inside a line, and everything it offers to other plugins. For examples and pictures of the icons see text, placeholders and icons.
Built-in placeholders
They work without PlaceholderAPI, in every line and in show-if conditions.
| Placeholder | Value | Refreshed |
|---|---|---|
{player} | the player's name | never (it does not change) |
{displayname} | display name (nicknames), with its colours | yes |
{ping} | ping in milliseconds | yes |
{health} | health points, rounded up (20 = 10 hearts) | yes |
{max_health} | maximum health, rounded up | yes |
{level} | experience level | yes |
{food} | hunger points (0–20) | yes |
{world} | world name | yes |
{animated} … {/animated} | same as <anim> … </anim> |
"Refreshed" lines are re-read every refresh-ticks (line, then template, then
updates.refresh-ticks, 20 by default). A line with no placeholder, icon or <badge> is never
refreshed, so it costs nothing after it is sent.
PlaceholderAPI
With PlaceholderAPI (opens in a new tab) installed, any %placeholder%
works in lines and conditions (install the expansion with /papi ecloud download <name>).
The plugin also registers its own expansion, advancednametags, for TAB, scoreboards and other
plugins:
| Placeholder | Returns |
|---|---|
%advancednametags_badge% | the badge the player shows, as <head_texture:…> tags (one per tile), or its fallback text while it is not generated; empty if none |
%advancednametags_badge_<id>% | badge <id> in the same format, for any player (also without one) |
%advancednametags_badges% | every badge the player owns, separated by spaces |
%advancednametags_badge_id% | id of the badge the player shows, or empty |
%advancednametags_template% | id of the template applied right now |
%advancednametags_line_<n>% | plain text of line n (from 1), without colours or images |
%advancednametags_lines% | number of lines |
%advancednametags_hidden% | true if the nametag is hidden (by an admin or the API) |
%advancednametags_self_view% | true if the player sees their own nametag |
%advancednametags_show_others% | true if the player sees other players' nametags |
The template, line and preference placeholders need the player online; for offline players they are
empty. <head_texture:…> is TAB's syntax for heads, so TAB draws these badges in the tab list,
scoreboard and its own nametags (for 1.21.9+ clients).
MiniPlaceholders
With MiniPlaceholders (opens in a new tab) the badges are offered as real components (no texture tags), to any plugin that supports it:
| Tag | Returns |
|---|---|
<advancednametags_badge> | the badge the player shows |
<advancednametags_badge:<id>> | a specific badge, e.g. <advancednametags_badge:vip> |
<advancednametags_badges> | every badge the player owns |
MiniPlaceholders tags from other plugins also work in nametag lines.
Tags the plugin adds
On top of every standard MiniMessage (opens in a new tab) tag
(colours, <gradient>, <b>, <newline>, <sprite>, <head>...):
| Tag | Draws | Clients before 1.21.9 and Bedrock see |
|---|---|---|
<badge:id> | badge id from badges.yml; an unknown id is shown literally | its fallback |
<badge> | the badge the player shows, followed by a space; nothing if none | its fallback |
<icon:ping> | ping bars like the tab list (150, 300, 600, 1000 ms steps) | ● green → red |
<icon:heart> | one heart: full (half health or more), half, empty | ❤ |
<icon:hearts> | health bar, up to 10 hearts, poisoned/withered/frozen/hardcore variants | a row of ❤ |
<icon:armor> | one armour icon per 2 armour points (up to 10) | a row of ⛨ |
<icon:food> | 10 hunger icons | a row of ◆ |
<face> | the player's skin face, with the hat layer (follows skin plugins) | nothing |
<head_texture:hash> | any skin by its textures.minecraft.net hash (32–128 hex characters), with the hat layer | nothing |
<anim> … </anim> | the template's animation, else animations.text-effect | the colours of the current frame |
<anim:spec> … </anim> | any effect or preset with options, e.g. <anim:wave:speed=2:#f00:#00f> | same |
<wave>, <pulse>, <shine>, <preset-name> | short form of <anim:…> | same |
<rainbow> and <gradient> stay MiniMessage's static tags; the animated rainbow is
<anim:rainbow>. The standard <head:Notch> and <sprite:atlas:path> tags also disappear on old
clients.
Values players can type
Placeholders that return text players choose (nicknames, clan names) cannot inject tags. For every
PlaceholderAPI value that is not trusted, colours and decorations are kept (<red>, <#hex>,
<gradient>, <rainbow>, <b>, <i>, <u>, <st>, <obf>, <shadow>, <reset>...) and every
other tag is shown as plain text. So a clan called <badge:owner> prints those characters instead
of the OWNER badge.
placeholders:
# Values you write yourself, which may use badges and images:
trusted: ['%luckperms_prefix%', '%luckperms_suffix%', '%vault_prefix%', '%vault_suffix%']Add a placeholder here only if players cannot change its text. '*' trusts all of them.
In what order a line is processed
placeholders.replacementsswap the values of the placeholders they list.- Built-in
{placeholders}are filled in. <icon:…>,<badge>and<face>become sprites, badges and heads for this player.- PlaceholderAPI placeholders are resolved one by one; untrusted values are restricted.
- Legacy
&and§codes are converted (placeholders.legacy-colors). - MiniMessage parses the result, with the badge, head and effect tags.
Consequences: the text of a replacement may itself use {placeholders}, icons and badges
('yes': ' <badge:afk>'), while text returned by PlaceholderAPI cannot use {placeholders}; and a
LuckPerms prefix such as &c[Admin] works without changes. If the line is not valid MiniMessage,
it is shown as plain text and the console says Invalid MiniMessage: … once.