Texto y placeholders
Un solo parser para cada cadena visible, la paleta compartida, las líneas propias de un plugin y un registro para %placeholders%.
Cuatro notaciones, una cadena#
Todo lo que lee un jugador pasa por Text y sale como componente de Adventure. Las cuatro formas se
mezclan libremente:
| Forma | Ejemplo |
|---|---|
| Token de paleta | {primary}, {error} |
| Código legacy | &a, &l, y §a |
| Hex legacy | a51c4, &x&8&a&5&1&c&4 |
| MiniMessage | <bold>, <gradient:#8a51c4:#ff6b9d>…</gradient> |
Text.of("{primary}&lBIENVENIDO &8[{success}online&8]").send(player);El signo de sección se lee como código legacy igual que &. Importa para la salida de los
placeholders: lo que devuelve PlaceholderAPI suele venir ya traducido a §, y una línea que lo llevaba
llegaba a la pantalla en crudo.
Las líneas que la librería pone en items — iconos de menú, items construidos desde una config — no van
en cursiva salvo que lo pidan, lo contrario de lo que hace vanilla con los items renombrados. Un
componente que pongas tú en un item lo consigue con PluginMessages.item (más abajo) o con
decorationIfAbsent(ITALIC, FALSE).
La API#
| Llamada | Qué hace |
|---|---|
Text.of(cadena) | La forma encadenable. |
Text.from(plugin, cadena) | Lo mismo, para un mensaje de un plugin, para que %prefix% resuelva. |
Text.component(cadena) | Directo a un Component; el camino más corto cuando no hay nada que sustituir. |
.with("%coins%", valor) | Sustituye un valor como texto literal. El primer argumento es el texto exacto que reemplaza. |
.withFormatted("%class%", valor) | Sustituye un valor que trae su propio formato — un nombre visible de una config. |
.withColored("%tag%", valor) | Un valor en el que metió mano un jugador pero que puede ir coloreado — un tag de clan, un nick. Funcionan colores, degradados y decoraciones; click, hover, fuentes, selectores y saltos de línea quedan como texto. |
.withVerbatim("%sample%", valor) | Como withFormatted, pero el valor conserva sus propias letras (sin versalitas) — palabras de alguien dibujadas dentro de una línea del servidor. |
.withAll(valores, formatted, verbatim) | Muchos valores de una vez, por nombre a secas; más barato que encadenar with. |
.forPlayer(player) | Resuelve %placeholders% para ese lector. |
.forPlayerFormatted(player) | Lo mismo, honrando valores de resolver que traen formato. |
.verbatim() / Text.verbatim(cadena) | Dibuja la línea con las letras con que se escribió, diga lo que diga small-text. Para un mensaje de chat o un nombre. |
.build() / .send(receptor) | Terminar, o terminar y entregar. |
.plain() / .legacy() / .raw() | Serializadores. legacy() es para APIs antiguas que lo exigen. |
.wire() / Text.fromWire(plugin, wire) | El texto y sus valores como una sola cadena para un canal de Redis, y de vuelta; el servidor que lo recibe lo construye con su propio prefijo, paleta y sonido. |
Equivocarse es un bug en las dos direcciones: un nombre visible imprimiendo {highlight} en pantalla, o
un jugador llamado <rainbow> recoloreando tu mensaje. Pregunta de quién es el valor — lo escribió
el dueño del servidor, o lo tecleó un jugador.
El texto que tecleó un jugador y que tiene que viajar como cadena — a una línea de config, a otro
plugin — pasa por Text.escape(typed), que neutraliza tags, códigos legacy y tokens de paleta para que
se lea tal cual al parsearse después. Text.strip(typed) quita todo el formato para siempre, parseando
hasta que nada cambie, para un nombre o una descripción que se guardan sin él.
Tres más para plugins que construyen componentes por su cuenta: Text.tag(resolver) agrega un tag de
MiniMessage propio para todo el servidor (los tags estándar se prueban primero, así que no puede
quitarle <red> a nadie); Text.click("suggest_command", "/msg Notch ") construye un click por el
nombre que escribe una config, y sobrevive a Adventure 5 donde un switch sobre ClickEvent.Action no;
y Text.shadowed(component) pone la sombra configurada del servidor bajo un componente pintado después
del parseo.
Valores dentro de argumentos de tags#
Un placeholder escrito dentro del argumento de un tag se resuelve antes del parseo, así que el tag ve el valor:
icon: "<head:%player_name%> {letters}%player_name%"A ese valor se le quitan los < y >, así que no puede cerrar el tag ni abrir otro. Los tags de click
y hover son la excepción: sus valores entran después del parseo, donde no pueden romper un comando ni un
tooltip.
La paleta#
Los mensajes nombran un rol, no un valor hexadecimal. Vienen dieciséis roles, definidos en el
colors.yml de la propia librería, y cambiar uno recolorea todo el ecosistema a la vez:
| Token | Por defecto | Token | Por defecto |
|---|---|---|---|
{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) es el extremo claro de un degradado de error y se añade con su valor por defecto a un
colors.yml existente.
colors.yml también guarda server-ip, escrito {server-ip} en cualquier mensaje, así que la
dirección de cada scoreboard y mensaje cambia en un solo lugar. Colors.get(token) lee un color como
TextColor, y Colors.names() los lista.
El estilo: versalitas y sombra#
Cada línea que escribe un plugin de Exylia se dibuja en versalitas Unicode y con una sombra suave de su
propio color, configurables en el config.yml de ExyliaLib (small-text, text-shadow). Las dos se
aplican a la plantilla, nunca a los valores sustituidos: un jugador llamado Steve sigue siendo
Steve y un saldo sigue siendo 1500. El texto que son palabras de otro y no del servidor — un mensaje
de chat, un nombre — usa verbatim() para conservar también sus letras.
El prefijo#
Casi todos los mensajes empiezan con la misma etiqueta. Escrita en cada línea no se puede cambiar de
forma centralizada; registrada como placeholder global, dos plugins pelean por %prefix%. Así que
pertenece a un plugin:
Prefixes.set(this, messages.prefix()); // al activar, y otra vez al recargar
Text.from(this, messages.ready()).send(player); // %prefix% resuelve al tuyoText.of deja %prefix% tal cual, y un plugin que nunca fijó uno lo deja visible, así que el olvido se
nota en vez de pasar en silencio.
Un prefijo editado que no se vuelve a registrar se queda obsoleto hasta el siguiente reinicio. Cada
plugin de Exylia llama a Prefixes.set como último paso de cargar sus configs precisamente por esto.
Las líneas propias de un plugin#
Un plugin que lee sus líneas de un archivo de mensajes tiene un PluginMessages y arma una bolsa
Values por mensaje:
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()); // la misma bolsa como contexto de menú- Cada línea pasa por
Text.from, así que%prefix%es el de este plugin y un tag de efecto al inicio suena. - Una línea vacía no manda nada. Vaciar un mensaje en el archivo es como el dueño lo apaga;
Text.senden cambio sí manda una línea vacía. putes un valor que escribió el servidor y se honra su formato;putTextes algo que tecleó un jugador y queda literal. Los nombres van a secas:"mine"llena%mine%, ynullpasa a ser cadena vacía.Valuestoma las tres formas que piden sus consumidores:applyTo(text)en un solowithAll,map()para un contexto de menú,apply(cadena)empalmado en una línea cruda. Empalmado, un valor tecleado pasa porValues.inert, así que un jugador que escribe%player_ip%nunca lo ve resuelto.messages.text(línea, values),item(línea, values)(sin cursiva) yplain(línea, values)dan la misma línea comoText, comoComponentde item o como texto plano para la consola.
Efectos y centrado dentro de un mensaje#
Un mensaje puede llevar un sonido, partículas, un fuego artificial o centrado, en un bloque entre corchetes al principio de la línea:
level-up: "[sound:ENTITY_PLAYER_LEVELUP|1.0|1.2;particle:FLAME|20;center]{success}Bien hecho"; separa los tipos, , varios del mismo tipo, y | los argumentos de un tipo. Los tipos son sound,
particle, firework y center (cada uno también en plural, y centered). El tag nunca llega a la
pantalla, a un log ni al nombre de un item; solo un jugador recibe los efectos; un corchete que no
significa nada, como [Server] Reiniciando, se deja tal cual; y una entrada mal escrita se avisa una
vez sin comerse el mensaje.
El centrado se mide en píxeles sobre lo que leerá el jugador — valores incluidos, negrita contada,
versalitas medidas como el glifo que se dibuja. Un valor que parte líneas (una lista de recompensas, un
top tres) centra cada línea que genera, no solo la primera. Centering.center(línea),
centerWithin(línea, ancho) y pixelWidth(línea) hacen lo mismo directamente.
Placeholders#
Un registro, esté o no PlaceholderAPI instalado.
Placeholders.group(this, "clan")
.describe("El clan del lector")
.add("name", request -> clans.of(request.requireViewer()).name())
.add("members", request -> clans.of(request.requireViewer()).size())
.register();Eso declara %clan_name% y %clan_members%. El nombre final es el prefijo del grupo, un guion bajo
y el nombre de la entrada — add("") registra el prefijo a secas. Registrar otra vez el mismo nombre
lo reemplaza, así que una recarga no duplica nada, y el grupo entero se va cuando el plugin se
desactiva.
| Escrito | Significa |
|---|---|
%clan_top_3% | Argumento 3. |
%eco_balance:comma% | Con formato: comma, compact, percent, upper, lower, yesno, time, fixed1, fixed2, o un patrón de DecimalFormat. |
%clan_name|Sin clan% | Una alternativa cuando no hay valor. |
%% | Un signo de porcentaje literal. |
Argumentos#
Gana el nombre registrado más largo y lo que sobra pasa a ser argumentos:
.add("players", request -> occupants(request.arg(0, "")))%arena_players_the_pit% encuentra el registrado arena_players y entrega the_pit — el argumento se
corta del texto tal y como está escrito, así que las mayúsculas de un valor sobreviven aunque el
nombre se compare en minúsculas.
Para un argumento que es un id que puede contener _, : o |, marca los nombres con .verbatim():
todo lo que va después del nombre llega al resolver como un argumento, tal cual está escrito, sin
partir, sin formato y sin alternativa.
Placeholders.group(this, "exyliashields")
.verbatim()
.add("unlocked", r -> r.argCount() == 0 ? total(r) : owns(r, r.arg(0, "")))
.register();%exyliashields_unlocked_pattern:globe% llega con ["pattern:globe"]. Un nombre verbatim se lleva
todo el resto, así que no registres otro nombre que empiece igual.
Sin respuesta no es cadena vacía#
Un resolver que devuelve null significa "no hay valor", y el texto conserva la alternativa que se
escribiera — o el propio placeholder, para que una errata se vea. Devuelve "" solo cuando vacío es la
respuesta real.
Devolver "-" en su lugar haría indistinguible "no hay nadie en el tercer puesto" de "esa arena no
existe".
Leerlos#
| Llamada | Qué hace |
|---|---|
Placeholders.apply(texto, lector) | Resolver todo para un lector. |
Placeholders.apply(texto, lector, data) | Lo mismo, con valores para este mensaje; un resolver registrado sigue ganando. |
Placeholders.applyRelational(texto, lector, objetivo) | Resolver un placeholder de dos jugadores. |
Placeholders.compile(texto) | Compilar una vez, resolver muchas. |
Placeholders.isDynamic(texto) | Si contiene algo que resolver. |
Placeholders.unresolved(texto) | Nombra lo que no respondió — la forma de cazar una errata. |
Con PlaceholderAPI#
Registrar un grupo registra la expansión; no hay nada que instalar desde eCloud. Fuera, el nombre del
plugin es el identificador: total_players registrado por ExyliaFFA se lee como
%exyliaffa_total_players%. Esa forma también funciona en cualquier texto de Exylia, con o sin
PlaceholderAPI, y le pregunta solo a ese plugin — la manera de llegar a un nombre que registran dos
plugins.
Un grupo cuyo prefijo ya es el nombre del plugin también está contemplado — PlaceholderAPI se come esa palabra como identificador, y la librería la vuelve a poner en vez de obligar a nadie a escribirla dos veces. Ese grupo no registra nada corto, así que sus nombres nunca chocan con los de otro plugin.
Un plugin puede agregar un identificador propio más corto:
Placeholders.identifier(this, "practice"); // %practice_stats_kills% además de %exyliapracticecore_stats_kills%Las dos formas siguen funcionando. El identificador es una palabra sin _, % ni espacios; uno al que
ya responde otro plugin se rechaza con un aviso en vez de quitárselo, y se olvida cuando el plugin se
desactiva.
Líneas escritas para varias líneas#
Un valor que contenga <nl> se convierte en varias líneas de lore. Lines.value(section, key) lee una
clave de config que puede ser cadena o lista a esa misma forma canónica, normalizando saltos de línea
reales y \n literales por el camino; Lines.read(section, claves...) devuelve las líneas en sí,
probando cada clave en orden para que una clave renombrada siga leyendo archivos viejos.
Solo se estiran las líneas que mencionan el valor multilínea, y el resto de la plantilla se repite alrededor de cada una — así que una viñeta sigue siendo una viñeta en la segunda línea.
Tokens de la paleta en degradados (desde 1.477.0)#
Un token escrito como argumento de una etiqueta es el color en bruto, así que los degradados siguen la paleta:
{primary} es <#8a51c4> en texto y #8a51c4 dentro de <gradient:…>, <transition:…>, <color:…> o <shadow:…>.
name: '{letters}Queue {letters_black}▸ <gradient:{info}:{info_light}>%kit_name%</gradient>'Un degradado alrededor de un valor (%kit_name%) se pinta una vez puesto el valor, a lo largo de sus letras reales.
La negrita y otras decoraciones escritas dentro se conservan; solo se leen los colores del degradado.
Texto en movimiento (desde 1.579.0)#
Los efectos de color y texto de las líneas de holograma funcionan en cualquier texto que la librería procesa: títulos y líneas de scoreboard, bossbars, action bars y títulos. Se leen desde el principio del texto y mueven todo.
| Etiqueta | Efecto |
|---|---|
<flow> / <flow:8> | Los colores del texto fluyen a lo largo de él, en caracteres por segundo (4 por defecto). |
<shine> | Una banda de luz lo recorre cada pocos segundos (opciones speed, pause, width). |
<rainbow> / <rainbow:10> | Un arcoíris suave lo recorre (6 caracteres por segundo por defecto). |
<frames> / <frames:1.5> | El texto se divide por ` |
<marquee:20> | Muestra 20 caracteres de un texto largo cada vez, desplazándose. |
<blink> / <blink:0.5> | Se muestra y oculta cada tantos segundos. |
El fotograma sale del reloj. Un scoreboard reenvía una línea en movimiento solo cuando cambió su fotograma, así que un
flujo suave pide update.interval: 2 (o 1); con el 20 por defecto avanza a saltos de un segundo. El texto que se
dibuja una vez (chat, lore, nombres de objetos) muestra un fotograma. Fundido, scramble, máquina de escribir y las
etiquetas de movimiento necesitan una entidad display y siguen siendo solo de hologramas.
Iconos (desde 1.477.0)#
{icon:nombre} dibuja un sprite del juego dentro de una línea, de ocho píxeles: {icon:clock}, {icon:kills},
{icon:heart}, {icon:gold}, {icon:pickaxe}, {icon:click} y más. Cualquier sprite sirve como
{icon:items:item/diamond|♦} (atlas, id y el glifo que lo sustituye), y |tint lo dibuja en el color que lo rodea.
- Escribe antes el color, para que el glifo sustituto sea correcto en todas partes:
{info}{icon:clock} {letters}Jugado. - Un servidor o cliente anterior a 1.21.9 recibe el glifo. Con PacketEvents, un cliente anterior a 1.21.9 tras ViaBackwards lo recibe cambiado en nombres de objetos, lore y scoreboards (1.541.0).
- Los iconos van en nombres y lore de objetos, líneas de scoreboard (1.541.0) y texto de pantallas (1.568.0). Títulos, chat, action bars, bossbars y Discord mantienen texto plano, y el tiempo ahí conserva el ⌚ literal.
- Iconos de interfaz (1.487.0):
clickyright_clickabren las líneas de acción,on/offylocked/unlockedmuestran estados,up/downtendencias,warningun problema en una tarjeta,signal_1…signal_5niveles de cinco pasos.
Lore de tarjetas en código: Lore (desde 1.477.0)#
El lore que un plugin construye en Java sigue el diseño de tarjeta de sus menús YAML, y Lore escribe las cadenas
para que código y archivos no se desincronicen.
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 elige el par de colores: PRIMARY, INFO, SUCCESS, HIGHLIGHT, WARNING, ERROR, ACCENT.
Escribir una línea y cuentas atrás#
Typewriter.of(component, lineWidth)(1.528.0) ajusta una línea una vez;frame(n)es la línea con sus primerosncaracteres escritos y espacios igual de anchos para el resto, así un panel centrado conserva su tamaño.TimeTokens.resolve(text)(1.563.0) rellena{countdown:2026-12-01 18:00 Europe/Madrid|{success}now!}(tiempo restante, sin unidades iniciales a cero, y el texto tras|una vez pasado) y{date:HH:mm}(ahora, con un patrón deDateTimeFormatter) antes de procesar el texto. Sin zona usa la del servidor. Los hologramas reprocesan esa línea cada segundo.
Rendimiento#
El texto sin caracteres de formato se salta el parser, y todo lo demás se parsea una vez y se cachea,
así que reenviar la misma línea cada tick es una búsqueda. Los valores sustituidos con with y
forPlayer entran después del parseo, que es lo que mantiene esa caché compartida entre jugadores.
Concatenar un valor en la cadena, en cambio, le da a cada jugador una cadena distinta y la pierde.
¿Falta algo en esta página? Dínoslo en Discord