Text and placeholders
One parser for every player-facing string, the shared palette, a plugin's own message lines, and one registry for %placeholders%.
Four notations, one string#
Everything a player reads goes through Text and comes out an Adventure component. All four forms mix
freely:
| Form | Example |
|---|---|
| Palette token | {primary}, {error} |
| Legacy code | &a, &l, and §a |
| Legacy hex | a51c4, &x&8&a&5&1&c&4 |
| MiniMessage | <bold>, <gradient:#8a51c4:#ff6b9d>…</gradient> |
Text.of("{primary}&lWELCOME &8[{success}online&8]").send(player);A section sign reads as a legacy code exactly like &. That matters for placeholder output: what
PlaceholderAPI hands back is usually already translated to §, and a line carrying one used to reach
the screen raw.
Lines the library puts on items — menu icons, items built from a config — are not italic unless they
ask to be, the opposite of vanilla's default for renamed items. A component you put on an item yourself
gets that through PluginMessages.item (below) or decorationIfAbsent(ITALIC, FALSE).
The API#
| Call | What it does |
|---|---|
Text.of(string) | The chainable form. |
Text.from(plugin, string) | The same, for a message belonging to a plugin, so %prefix% resolves. |
Text.component(string) | Straight to a Component; the shortest path when there is nothing to substitute. |
.with("%coins%", value) | Substitutes a value as literal text. The first argument is the exact text it replaces. |
.withFormatted("%class%", value) | Substitutes a value that carries its own formatting — a display name from a config. |
.withColored("%tag%", value) | A value a player had a hand in that may still be coloured — a clan tag, a nickname. Colours, gradients and decorations work; click, hover, fonts, selectors and line breaks stay text. |
.withVerbatim("%sample%", value) | Like withFormatted, but the value keeps its own letters (no small capitals) — somebody's words drawn inside a server line. |
.withAll(values, formatted, verbatim) | Many values at once, keyed by bare name; cheaper than a chain of with calls. |
.forPlayer(player) | Resolves %placeholders% for that viewer. |
.forPlayerFormatted(player) | The same, honouring resolver values that carry formatting. |
.verbatim() / Text.verbatim(string) | Draws the line in the letters it was written in, whatever small-text says. For a chat message or a name. |
.build() / .send(receiver) | Finish, or finish and deliver. |
.plain() / .legacy() / .raw() | Serialisers. legacy() is for old APIs that demand it. |
.wire() / Text.fromWire(plugin, wire) | The text and its values as one string for a Redis channel, and back; the receiving server builds it with its own prefix, palette and sound. |
Getting it backwards is a bug in both directions: a display name printing {highlight} to the screen,
or a player called <rainbow> recolouring your message. Ask whose value it is — a server owner
wrote it, or a player typed it.
Text a player typed that has to travel as a string — into a config line, to another plugin — goes
through Text.escape(typed), which neutralises tags, legacy codes and palette tokens so it reads exactly
as typed when parsed later. Text.strip(typed) removes every bit of formatting for good, parsing until
nothing changes, for a name or description stored without it.
Three more for plugins that build components themselves: Text.tag(resolver) adds a MiniMessage tag of
your own for the whole server (standard tags are tried first, so it cannot take <red> away);
Text.click("suggest_command", "/msg Notch ") builds a click event by the name a config writes, which
survives Adventure 5 where a switch over ClickEvent.Action does not; and Text.shadowed(component)
puts the server's configured text shadow under a component painted after the parse.
Values inside tag arguments#
A placeholder written inside a tag argument resolves before the parse, so the tag sees the value:
icon: "<head:%player_name%> {letters}%player_name%"Angle brackets are dropped from such a value, so it cannot close the tag or open another. Click and hover tags are the exception: their values go in after the parse, where a command or a tooltip cannot be broken by them.
The palette#
Messages name a role, not a hex value. Sixteen roles ship, defined in the library's own colors.yml,
and changing one recolours every plugin in the ecosystem at once:
| Token | Default | Token | Default |
|---|---|---|---|
{primary} | #8a51c4 | {info} | #59a4ff |
{secondary} | #aa76de | {info_light} | #7db7ff |
{secondary_light} | #b48fd9 | {accent} | #ff6b9d |
{letters} | #e7cfff | {neutral} | #6c757d |
{letters_black} | #a89ab5 | {highlight} | #ffd700 |
{error} | #a33b53 | {muted} | #868e96 |
{error_light} | #d4617d | ||
{success} | #8fffc1 | {warning} | #ff9500 |
{success_light} | #a1ffc3 | {warning_light} | #ffd2a8 |
{error_light} (1.477.0) is the light end of an error gradient and is added to an existing colors.yml with
its default.
colors.yml also holds server-ip, written {server-ip} in any message, so the address on every
scoreboard and message changes in one place. Colors.get(token) reads a colour as a TextColor, and
Colors.names() lists them.
The look: small capitals and shadow#
Every line an Exylia plugin writes is drawn in Unicode small capitals and with a soft shadow in its own
colour, switched in ExyliaLib's config.yml (small-text, text-shadow). Both apply to the template,
never to substituted values: a player named Steve stays Steve and a balance stays 1500. Text that
is somebody else's words rather than the server's — a chat message, a name — uses verbatim() so it
keeps its letters too.
The prefix#
Nearly every message starts with the same tag. Written into each line it cannot be changed centrally;
registered as a global placeholder, two plugins fight over %prefix%. So it belongs to a plugin:
Prefixes.set(this, messages.prefix()); // on enable, and again on reload
Text.from(this, messages.ready()).send(player); // %prefix% resolves to yoursText.of leaves %prefix% alone, and a plugin that never set one leaves it visible, so the omission is
obvious rather than silent.
An edited prefix that is not re-registered stays stale until the next restart. Every Exylia plugin
calls Prefixes.set as the last step of loading its configs for exactly this reason.
A plugin's own lines#
A plugin that reads its lines from a messages file holds one PluginMessages and builds a Values bag
per message:
messages = PluginMessages.of(this); // onEnable
messages.send(player, lang.created(), Values.of("mine", mine.id()));
messages.send(player, lang.renamed(), Values.of("old", old).putText("new", typedName));
menus.open(player, "mine_list", values.map()); // the same bag as a menu context- Every line goes through
Text.from, so%prefix%is this plugin's and an effect tag at the start plays. - A blank line sends nothing. Emptying a message in the file is how an owner turns it off;
Text.senditself still sends an empty line. putis a value the server wrote and its formatting is honoured;putTextis something a player typed and stays literal. Names are bare:"mine"fills%mine%, andnullbecomes an empty string.Valuestakes the three shapes its consumers want:applyTo(text)in onewithAll,map()for a menu context,apply(string)spliced into a raw line. Spliced in, a typed value goes throughValues.inert, so a player who types%player_ip%never has it resolved.messages.text(line, values),item(line, values)(not italic) andplain(line, values)give the same line as aText, an itemComponentor plain text for the console.
Effects and centring inside a message#
A message can carry a sound, particles, a firework or centring, in one bracketed block at the very start of the line:
level-up: "[sound:ENTITY_PLAYER_LEVELUP|1.0|1.2;particle:FLAME|20;center]{success}Well done"; separates the kinds, , several of one kind, and | a kind's own arguments. The kinds are
sound, particle, firework and center (each also in plural, centered too). The tag never reaches
the screen, a log or an item name; only a player gets the effects; a bracket that means nothing, such as
[Server] Restarting, is left alone; and a malformed entry is reported once without eating the message.
Centring is measured in pixels on what the player will read — values included, bold counted, small
capitals measured as the glyph drawn. A value that breaks lines (a rewards list, a top three) centres
every line it makes, not just the first. Centering.center(line), centerWithin(line, width) and
pixelWidth(line) do the same directly.
Placeholders#
One registry, whether or not PlaceholderAPI is installed.
Placeholders.group(this, "clan")
.describe("The reader's clan")
.add("name", request -> clans.of(request.requireViewer()).name())
.add("members", request -> clans.of(request.requireViewer()).size())
.register();That declares %clan_name% and %clan_members%. The final name is the group prefix, an underscore
and the entry name — add("") registers the bare prefix itself. Registering the same name again
replaces it, so a reload duplicates nothing, and the whole group goes when the plugin disables.
| Written | Means |
|---|---|
%clan_top_3% | Argument 3. |
%eco_balance:comma% | Formatted: comma, compact, percent, upper, lower, yesno, time, fixed1, fixed2, or a DecimalFormat pattern. |
%clan_name|No clan% | A fallback when there is no value. |
%% | A literal percent sign. |
Arguments#
The longest registered name wins and whatever is left becomes arguments:
.add("players", request -> occupants(request.arg(0, "")))%arena_players_the_pit% finds the registered arena_players and hands over the_pit — the argument
is cut from the text as written, so a value's capitals survive even though the name is matched
folded.
For an argument that is an id which may itself contain _, : or |, mark the names .verbatim():
everything after the name reaches the resolver as one argument, exactly as written, with no
splitting, no format and no fallback.
Placeholders.group(this, "exyliashields")
.verbatim()
.add("unlocked", r -> r.argCount() == 0 ? total(r) : owns(r, r.arg(0, "")))
.register();%exyliashields_unlocked_pattern:globe% arrives with ["pattern:globe"]. A verbatim name takes the
whole rest, so do not register another name that starts with it.
No answer is not an empty string#
A resolver returning null means "no value", and the text keeps whatever fallback was written — or
the placeholder itself, so a typo shows. Return "" only when empty is the real answer.
Returning "-" instead would make "nobody is in third place" indistinguishable from "that arena does
not exist".
Reading them#
| Call | What it does |
|---|---|
Placeholders.apply(text, viewer) | Resolve everything for a viewer. |
Placeholders.apply(text, viewer, data) | The same, with values for this one message; a registered resolver still wins. |
Placeholders.applyRelational(text, viewer, target) | Resolve a two-player placeholder. |
Placeholders.compile(text) | Compile once, resolve many times. |
Placeholders.isDynamic(text) | Whether it contains anything to resolve at all. |
Placeholders.unresolved(text) | Names nothing answered — the way to catch a typo. |
With PlaceholderAPI#
Registering a group registers the expansion; there is nothing to install from eCloud. Outside, the
plugin's own name is the identifier: total_players registered by ExyliaFFA is read as
%exyliaffa_total_players%. That spelling also works in any Exylia text, with or without
PlaceholderAPI, and asks that plugin only — the way to reach a name two plugins both register.
A group whose prefix already is the plugin's name is handled too — PlaceholderAPI strips that word as the identifier, and the library puts it back rather than making anybody write it twice. Such a group registers nothing short, so its names never clash with another plugin's.
A plugin may add one shorter identifier of its own:
Placeholders.identifier(this, "practice"); // %practice_stats_kills% as well as %exyliapracticecore_stats_kills%Both spellings keep working. The identifier is one word with no _, % or space; one another plugin
already answers to is refused with a warning rather than taken from it, and it is forgotten when the
plugin disables.
Lines written for several lines#
A value containing <nl> becomes several lore lines. Lines.value(section, key) reads a config key
that may be a string or a list into that one canonical form, normalising real line breaks and literal
\n on the way; Lines.read(section, keys...) returns the lines themselves, trying each key in order
so a renamed key still reads old files.
Only lines that actually mention the multi-line value are stretched, and the rest of the template repeats around each one — so a bullet stays a bullet on the second line.
Palette tokens in gradients (since 1.477.0)#
A token written as a tag's argument is the bare colour, so gradients follow the palette: {primary} is
<#8a51c4> in text and #8a51c4 inside <gradient:…>, <transition:…>, <color:…> or <shadow:…>.
name: '{letters}Queue {letters_black}▸ <gradient:{info}:{info_light}>%kit_name%</gradient>'A gradient around a value (%kit_name%) is painted once the value is in, across its real letters. Bold and other
decorations written inside it are kept; only the gradient's colours are read.
Moving text (since 1.579.0)#
The colour and text effects of hologram lines work in any text the library parses: sidebar titles and lines, boss bars, action bars and titles. They are read from the very start of the text and move all of it.
| Tag | Effect |
|---|---|
<flow> / <flow:8> | The text's own colours flow along it, in characters a second (default 4). |
<shine> | A band of light sweeps over it every few seconds (speed, pause, width options). |
<rainbow> / <rainbow:10> | A soft rainbow runs along it (default 6 characters a second). |
<frames> / <frames:1.5> | The text is split by ` |
<marquee:20> | Shows 20 characters of a longer text at a time, scrolling. |
<blink> / <blink:0.5> | Shows and hides every that many seconds. |
The frame comes from the clock. A sidebar sends a moving line again only when its frame changed, so a smooth flow
wants update.interval: 2 (or 1); at the default 20 it moves in one-second steps. Text drawn once (chat, lore,
item names) shows one frame. Fade, scramble, typewriter and the motion tags need a display entity and stay
hologram-only.
Icons (since 1.477.0)#
{icon:name} draws a game sprite inside a line, eight pixels square: {icon:clock}, {icon:kills},
{icon:heart}, {icon:gold}, {icon:pickaxe}, {icon:click} and more. Any sprite works as
{icon:items:item/diamond|♦} (atlas, id, then the glyph that stands in), and |tint draws it in the colour around it.
- Write the colour first, so the stand-in glyph is right everywhere:
{info}{icon:clock} {letters}Played. - A server or client older than 1.21.9 gets the glyph. With PacketEvents, a pre-1.21.9 client behind ViaBackwards gets it swapped on item names, lore and sidebars (1.541.0).
- Icons belong in item names and lore, scoreboard lines (1.541.0) and screen text (1.568.0). Titles, chat, action bars, boss bars and Discord keep plain text, and time there keeps the literal ⌚.
- Interface icons (1.487.0):
clickandright_clickopen action lines,onandoffandlockedandunlockedshow states,upanddowntrends,warninga problem on a card,signal_1…signal_5five-step levels.
Card lore in code: Lore (since 1.477.0)#
Lore a plugin builds in Java follows the card layout its YAML menus use, and Lore writes the strings so code and
files cannot drift apart.
String name = Lore.name(Lore.Tone.PRIMARY, "Mine", "%mine_name%");
List<String> lore = Lore.of(Lore.Tone.PRIMARY)
.subtitle("Mine setting")
.section("Information").text("How and when this mine").text("refills its blocks.")
.section("✦", "Status").stat("clock", "info", "Interval", "%interval%")
.click("Left-click", "edit interval")
.lines();Tone picks the colour pair: PRIMARY, INFO, SUCCESS, HIGHLIGHT, WARNING, ERROR, ACCENT.
Writing a line out and countdowns#
Typewriter.of(component, lineWidth)(1.528.0) wraps a line once;frame(n)is the line with its firstncharacters written and spaces as wide as the rest, so a centred panel keeps its size.TimeTokens.resolve(text)(1.563.0) fills{countdown:2026-12-01 18:00 Europe/Madrid|{success}now!}(time left, leading zero units dropped, the text after|once passed) and{date:HH:mm}(now, in aDateTimeFormatterpattern) before the text is parsed. Without a zone it uses the server's. Holograms re-render such a line every second.
Performance#
Text with no formatting characters skips the parser, and everything else is parsed once and cached, so
re-sending the same line every tick is a lookup. Values substituted with with and forPlayer are put
in after the parse, which is what keeps that cache shared across players. Concatenating a value into
the string instead gives every player a different string and misses it.
Something missing on this page? Tell us on Discord