Placeholders

Standard placeholder

Underscores (_) separate namespace tokens. A placeholder is parsed left-to-right: the first token selects a namespace, and each subsequent token narrows the lookup inside that namespace.

Inner placeholders

A placeholder can be nested inside another using curly braces. The inner placeholder is resolved first and its result is substituted into the outer key before the outer lookup runs.

Inner placeholders may be combined with literal segments:

A brace group may also hold an inline function call or an $e(...) expression rather than a placeholder name. It is computed first and its result is spliced into the outer key, with no second resolution pass:

Expression evaluation

Wrap an arithmetic expression in $e(...) to evaluate it. Placeholders inside the expression are resolved first; the result must be numeric. Returns an integer when the result is a whole number, otherwise a double.

Supported operators come from the Crunch math library: +, -, *, /, ^, plus parentheses. The custom round(value, precision) function is registered out of the box.

Expressions may be nested to any depth — the parser matches balanced parentheses rather than using a regex, so there is no depth limit. Inner expressions are evaluated first and passed to the outer one as raw doubles, so precision is never lost to a string round-trip.

Each %placeholder% and each nested $e(...) is substituted by a positional variable and the expression is compiled once. A resolved placeholder must be a Number or a string that parses as a double; anything else — including null — fails with an error instead of falling back to a value.

An expression may appear inside an inline function's argument, where it is resolved by that argument's own wrapper:

The reverse also works: an inline function may be nested inside an expression, at any depth. Each nested call becomes a positional input of the compiled expression and is fed in as a raw double — the function's return value is used, not its rendered text.

The nested function must return a Number, or a string that parses as a double. Anything else fails resolution with an error naming both the call and the enclosing expression (Function $x(...) in expression $e(...) must produce a number, but returned "…"). In particular a formatting function cannot feed an expression back — $format-number emits grouping separators, so $e($format-number(%big%)+1) fails at render time:

Expressions are commonly used with set-variable:

Inline functions

For named, multi-argument helpers (clamped arithmetic, number formatting, date formatting, etc.), see Functions — invoked as $name(arg1, arg2, ...).

MiniMessage in resolved values

When a resolved placeholder or inline-function value is substituted into a component field — an item name, a menu title, any lore line — a value containing MiniMessage tags (<red>, <#FFFFFF>, <gradient:…>) is deserialized as MiniMessage and rendered as formatting. Values with no <…> tag are inserted as plain text and inherit the surrounding style. Detection is the regex <[^<>]+>, and the rule applies to every element of a lore list. Placeholder values substituted into a hover tooltip follow the same rule.

Substitution is a single pass over the line: every registered key is matched by one compiled alternation, so a resolved value is spliced in as-is and is never re-scanned for placeholders or inline tokens. A value that itself contains %…% text therefore renders literally instead of being resolved a second time. List-valued placeholders are the one case where a line expands into several.

List-valued placeholders

A placeholder may resolve to a List. What happens then depends on the context it is written in:

• In a list context (a lore: line, or any multi-line field) the line expands into one line per element. Surrounding text on the same line is kept on the first produced line only — the remaining elements are emitted as bare lines — so such a placeholder is normally the whole line.

• An empty list produces zero lines — the lore line disappears entirely rather than rendering [] or an empty line.

• In a single-component field (an item name:, a menu title, a message line) the list resolves to its first element; an empty list resolves to the empty string.

This is the same rule the iterable and conditional lore modifiers follow — see Lore modifiers and Items.

Placeholders in click and hover events

Inside a <hover:show_text:…> tooltip, placeholders, $e(...) expressions and $fn(...) inline functions resolve exactly as they do in the line's own text — tooltip text goes through the same substitution pass. This includes:

• a tooltip attached to the whole line (the component the walk starts from), not only to a child span;

• a line that consists of nothing but a single placeholder and carries a tooltip — the tooltip is preserved and substituted rather than dropped.

A tooltip shares the line's resolved values, so the same token yields the same value in the line and in its tooltip.

Inside a <click:…> value the rule is narrower: only %placeholder% tokens are substituted. A click payload is scanned for %…% alone, so $e(...) and $fn(...) written in a click value are never resolved and are sent through as literal text. Each %…% value is inserted as a plain string (no MiniMessage handling), which is what a command or URL payload needs.

Style-valued placeholders

A placeholder (or inline function) that resolves to an Adventure style rather than to text — a TextColor, a TextDecoration, a whole Style, anything StyleBuilderApplicable — carries no characters of its own. Such a value styles everything that follows it on the same line:

%rank_color% renders nothing itself and hands its colour to %rank_name% and any text after it. Reach is the rest of that line only — the next lore line starts clean.

Two rules govern what wins:

• Style set explicitly on the text that follows still wins. %rank_color%<bold>Name</bold> keeps the bold.

• A second style placeholder restyles from its own position onward, overriding the first one from there:

  name: "%a%first %b%second" # "first" takes %a%, "second" takes %b%

A style placeholder with nothing after it — or one that is the entire value of the field — renders as nothing at all, which is the expected no-op.

Equipment sub-keys

The equipment placeholder returns an ItemStackPlaceholder instance, so the remaining tokens drill into the item:

An unrecognised sub-key yields the ItemStack itself.

enchantments and stored-enchantments return an ItemProvider, so they take the usual provider sub-keys — _size, _max-index, _at_<index>, _list — and each element is an enchantment placeholder. stored-enchantments is empty for anything that is not an enchanted book, and enchantments is empty (not null) for an unenchanted item.

Enchantment sub-keys

%item_enchantment_<key>_…% resolves a single enchantment on the stack. The enchantment key is read greedily: arguments are consumed until one of them is a known sub-key, so a multi-word key such as silk_touch works without escaping — %item_enchantment_silk_touch_level% reads silk_touch, then level. An unknown or malformed key raises an error rather than resolving to nothing.

Because level is 0 rather than null for a missing enchantment, guard on it explicitly instead of relying on the line disappearing:

A bare %item_enchantment_<key>% with no sub-key yields the enchantment object itself, which is what an Enchantment argument on an action, requirement or function expects — the enchantment adapter unwraps it.

Material sub-keys

%…_material% returns a MaterialPlaceholder; a bare token yields the Bukkit Material itself.

Any other sub-key resolves to null.

Location, world, block and entity sub-keys

%player_location% and %player_world% return chaining objects — a bare %player_location% or %player_world% is not useful on its own; append a sub-key to drill in. The same applies to the block and entity objects documented below.

location sub-keys (also reachable via %player_location_world_*%):

world sub-keys (reached via %player_world_*% or %player_location_world_*%):

block sub-keys:

entity sub-keys:

A bare token with no sub-key yields the Bukkit Block/Entity object itself, which is useful only where an adapter unwraps it (a block: or entity: argument). Any other sub-key resolves to null.

Playtime and last-seen semantics

• %player_playtime%/%player_raw-playtime% use effectivePlaytime(): the session in progress is added only while the player is actually online. The persisted value settles on quit. An offline player's playtime is the stored value, with no live delta added.

• %player_last_login% is the time since the actual login — the login stamp is no longer rewritten on quit, so it no longer means "time since last logout".

• %player_last_seen%/%player_raw-last_seen% carry the "last observed connected" meaning. The timestamp is stamped on login and on quit, so for a player who is online right now last_seen is the start of their current session.

• When the timestamp was never recorded (records predating the column read back as -1), the expansion returns null for %player_last_seen%. That is PlaceholderAPI's "not handled" signal, so the raw %player_last_seen% text is left in place rather than rendering as an empty string.