Text and placeholders

Four notations, one string

Everything a player reads goes through Text and comes out an Adventure component. All four forms mix freely:

Text.of("{primary}&lWELCOME &8[{success}online&8]").send(player);

Italics are off unless asked for, which is the opposite of vanilla's default for renamed items.

The API

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:

Colors.get(token) reads one as a TextColor, and Colors.names() lists them.

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 yours

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.

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.

No answer is not an empty string

A resolver returning null means "no value", and the text keeps whatever fallback was written:

%clan_name|No clan%

Returning "-" instead would make "nobody is in third place" indistinguishable from "that arena does not exist".

Reading them

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%.

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.

There is no second identifier: a plugin answers under its own name only.

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.

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.