Configuración
Archivos YAML declarados como records de Java, generados a partir de ellos, y migrados cuando cambian de forma.
El record es la fuente de verdad. El archivo YAML es salida, no entrada: se genera a partir del constructor sin argumentos del record, comentarios incluidos, y se lee de vuelta a la misma forma.
ConfigFile<Settings> settings = Configs.define(this, "config", Settings.class).load();
int pool = settings.get().database().poolSize();Declarar un archivo#
public record Storage(
@Comment("Conexiones abiertas. Regla rápida: núcleos × 2.")
@Key("pool-size")
int poolSize,
@Comment("Dónde viven los datos de jugador.")
String host) {
/** Los valores con los que se genera el archivo. */
public Storage() {
this(10, "localhost");
}
}| Anotación | Qué hace |
|---|---|
@Key("otro-nombre") | La clave YAML difiere del nombre del componente. |
@Comment("…") | Se escribe encima del valor en el archivo. Repetible — varias líneas, en orden. |
Los records anidados se convierten en secciones anidadas, así que la estructura del archivo es el árbol de records.
Son lo que lee el dueño del servidor en vez de tu documentación. Di qué cambia el valor, en qué unidad
y en qué rango — Segundos que un jugador sigue marcado tras recibir un golpe, no duración del tag.
Leer y escribir#
| Llamada | Qué hace |
|---|---|
get() | La instantánea actual. Un acceso a campo, nunca un reparseo. |
reload() | Relee el archivo. Devuelve los problemas; lista vacía significa limpio. |
onReload(consumer) | Se ejecuta tras cada recarga correcta. |
save() | Escribe la instantánea actual en disco. |
update(operador) | Cambiar y persistir en un paso, en el hilo de quien llama. |
updateAsync(operador) | Lo mismo, con la escritura fuera del hilo de quien llama. |
set(clave, valor) | Escribe un valor por su clave con puntos y recarga, para que se compruebe como cualquier cosa que escriba el dueño. null borra la clave. Devuelve los problemas encontrados. |
issues() | Problemas de la última carga. |
schema() | Una descripción de solo lectura del tipo del record. |
settings.update(actual -> actual.withHost("10.0.0.5"));
config.set("forced-flags.pvp", "DENY"); // para un editor en el juego que solo conoce la claveupdateAsync es para un archivo que un editor en el juego guarda en cada clic. get() ve los valores
nuevos antes de que vuelva; solo la escritura espera. Las escrituras de un archivo van de una en una, y una
ráfaga de cambios hechos antes de que empiece la escritura se escribe una vez, con los últimos valores.
save, update, set y reload escriben primero un cambio pendiente, y lo que quede pendiente se escribe
cuando el plugin se desactiva.
Duraciones#
public record Settings(
Duration lasts, // la forma para todo lo nuevo
@Time int timeoutSeconds, // un número que ya existía
@Time(Time.Unit.TICKS) long interval) { }lasts: 1m30s
timeout-seconds: 5m # 300, para el record
interval: 1s # 20, porque esta clave se escribe en ticksEl dueño puede escribir 30s, 1m30s, 500ms, 40t, 2h, 2d, 1w, 1mo o 2.5h. Un número
suelto nunca cambia de significado: @Time declara la unidad en la que siempre se escribió la clave, que
es a la vez lo que significa un número sin unidad y la unidad que recibe el record (SECONDS salvo que se
diga otra; MILLIS, TICKS, MINUTES, HOURS, DAYS). Un Duration no necesita anotación, lee un número
suelto como segundos y se vuelve a escribir como 1m30s; un número anotado se vuelve a escribir como número.
Prefiere Duration para todo lo nuevo.
Versiones y migraciones#
Un archivo recibe un marcador config-version en cuanto declaras una versión, y las migraciones llevan
un archivo antiguo hacia adelante en el primer arranque tras actualizar:
config = Configs.define(this, "config", Settings.class)
.version(3)
.migration(1, MIGRATION_FROM_1)
.migration(2, MIGRATION_FROM_2)
.load();Los pasos se ejecutan en orden, por muy atrasado que esté el archivo. Una migración se construye con cuatro operaciones:
| Operación | Qué hace |
|---|---|
Migration.rename(de, a) | Mueve un valor a una ruta nueva. Un origen ausente se deja en paz. |
Migration.remove(ruta) | Borra una clave. |
Migration.transform(ruta, reescritura) | Reescribe el valor en el sitio. Se salta si la clave no está. |
Migration.all(pasos…) | Varias de las anteriores como una sola migración. |
public static final Migration MIGRATION_FROM_1 = Migration.all(
Migration.rename("combat.combat-actionbar.text",
"combat.combat-actionbar.action-bar.text"),
Migration.remove("combat.combat-actionbar.update-interval"));Una clave que ningún record declara se elimina al cargar. Eso es lo que mantiene los archivos limpios entre actualizaciones — y es exactamente por lo que reestructurar una sección sin migración tira en silencio lo que el dueño del servidor hubiera escrito ahí. Renombra en el record y migra en el mismo commit.
Mover claves a otro archivo#
Configs.moveTo es una migración que saca claves de este archivo y las lleva a otro archivo del mismo
plugin — normalmente texto que deja config.yml por un messages.yml traducido:
Configs.define(this, "config", Settings.class)
.version(3)
.migration(2, Configs.moveTo(this, "messages", Map.of(
"combat.action-bar", "combat.action-bar")))
.load();Los valores del dueño llegan a las rutas nuevas cargue primero el archivo que cargue; una sección se mueve con todo lo que tiene debajo. Un valor aún en su defecto en inglés no se lleva, así que un archivo traducido conserva su traducción.
transform es la herramienta correcta cuando lo que cambió es el significado de un valor y no su
sitio — un token renombrado, un número que estaba en ticks y ahora va en segundos. Reescribe lo que hay
en vez de reemplazarlo con el valor por defecto, así que las palabras y los colores del dueño
sobreviven.
Idiomas#
Un archivo declarado translated() vive en la carpeta de idioma del plugin en vez de en su raíz:
Configs.define(this, "config", Settings.class) // tiene un String language, por defecto "default"
.version(4).migration(3, Languages.ADOPT_EXISTING).load();
Configs.define(this, "messages", Messages.class).translated().load();
Languages.refresh(this, MyPlugin.class, "menus");
File main = Languages.file(this, "menus/main.yml");| Llamada | Qué hace |
|---|---|
translated() | El archivo es lang/<código>/<nombre>.yml para el idioma del plugin, y lo sigue al recargar. El record guarda los defectos en inglés; un lang/<código>/<nombre>.yml empaquetado en el jar reemplaza las líneas que traduce. |
Languages.code(plugin) | El idioma del plugin: su propia clave language, o la de ExyliaLib si es default, o en. |
Languages.use(plugin, código) | Fija el idioma desde código, para un plugin que guarda sus ajustes en otro sitio, como una base de datos. Gana sobre config.yml; null o default vuelven a él. Recarga después los archivos del plugin. |
Languages.refresh(plugin, anchor, recurso) | Instala y actualiza un archivo o carpeta traducido que edita el dueño, como hace BundledFiles.refresh. |
Languages.replace(plugin, anchor, recurso) | Reescribe una carpeta traducida desde el jar en cada arranque, descartando ediciones — para pantallas de administración que son del plugin. |
Languages.file(plugin, recurso) / path(…) | Dónde vive en disco un archivo traducido. |
Languages.ADOPT_EXISTING | La migración de la versión que introduce language: un servidor que ya usaba el plugin recibe language: custom, y su messages.yml y menus/ se mueven a lang/custom/. |
Los archivos empaquetados van bajo lang/<código>/ en el jar. El inglés es la base sobre la que se pone
cualquier otro idioma, así que una línea aún sin traducir llega igual, en inglés. config.yml tiene que
cargarse antes que los archivos que lo siguen.
Textos en el idioma del servidor#
Configs.define(...).localizedDefaults() (1.571.0) sirve para un archivo de ajustes que contiene texto visible para
los jugadores (nombres de botones, lore, mensajes de entrada): el archivo conserva su sitio y sus pantallas de
configuración, y toma los valores por defecto de esos textos del idioma del servidor.
- El archivo de idioma va en el jar en
lang/<código>/<nombre>.ymly solo contiene las claves que traduce; toda clave que omite conserva el valor por defecto del record, también la de un mapa. Una lista es un solo valor. - Un archivo nuevo se escribe en el idioma del servidor. Uno existente nunca se reescribe: sus textos aún en el
valor antiguo esperan en
/exylialib updates, y un texto que el dueño editó es suyo. - Cambiar
languagecon el servidor en marcha reconstruye los valores por defecto en el siguiente reload;apply allen/exylialib updatescambia los textos que seguían en el valor antiguo. - Para saber si el jar incluye un archivo o carpeta, usa
BundledFiles.packaged(MyPlugin.class, "menus")(1.544.0), nuncagetResource: el cargador de licencias mantiene el jar en memoria.
Un catálogo por idioma#
El texto que un jugador lee en un catálogo (el lore de un objeto, las ventajas de un trabajo) se traduce como un menú:
un archivo real por idioma en plugins/<Plugin>/lang/<código>/, que el dueño puede editar.
Languages.refresh(plugin, anchor, "items") instala el items/<id>.yml base del jar combinado con
lang/<código>/items/<id>.yml; Languages.file(plugin, "items") dice dónde está, y todo lo que escribe (editores,
importadores, editor web) pasa por ahí.
- Clave a clave gana el idioma y se añade la clave que solo tiene la base. Una lista traducida reemplaza la de la base entera.
- Cada idioma es su propia copia: cambiar instala los archivos de ese idioma y las ediciones no se trasladan.
- Un archivo incluido que el dueño borró se escribe de nuevo en el siguiente refresh.
- Mover un catálogo existente: sin clave
languageaún, usa la migraciónLanguages.ADOPT_EXISTING; con ella, llama aLanguages.adoptCatalogueantes del primer refresh. CatalogueCheck.problems(...)(1.534.0) comprueba cada archivo de idioma: solo claves de la base, todo texto traducido, todos los placeholders, tokens y etiquetas de la línea base conservados, y ninguna línea más ancha de lo permitido.- Las palabras que el código escribe en inglés y que un servidor puede conservar tal como vienen pasan por
Phrases.tr; las que un plugin siembra en su base de datos se incluyen comolang/<código>/seeded.ymly se leen conPhrases.seeded(plugin, MyPlugin.class)(1.542.0).
Valores por defecto cambiados#
Cada config recuerda los defectos que su dueño revisó por última vez, en .defaults/configs/, y los compara
en cada carga. Una clave nueva se añade. Un defecto cambiado o eliminado en una clave que sigue en su
valor revisado se deja en paz y se lista en
/exylialib updates, donde el dueño lo
aplica o lo conserva. Un valor que cambió el dueño nunca se lista. El plugin no tiene que hacer nada.
Archivos empaquetados#
Los archivos que un plugin trae para que los edite el dueño, en vez de generarlos desde un record — menús, catálogos de efectos o items — siguen las mismas reglas:
BundledFiles.refresh(this, MyPlugin.class, "menus"); // una carpeta
BundledFiles.refresh(this, MyPlugin.class, "effects.yml"); // un archivoLlámalo antes de leer los archivos, al activar y al recargar.
- Un archivo que falta se escribe, cada vez que falta.
- Una clave nueva se añade al archivo del dueño, con sus comentarios.
- Un defecto cambiado o eliminado en una clave aún en su valor revisado espera en
/exylialib updates. - Lo que el dueño cambió o borró nunca se toca. Los defectos revisados viven en
.defaults/files/. - Un archivo cuya estructura cambió demasiado para fusionarse lo declara con un
menu-version(odefaults-version) más alto en su raíz. Un archivo sin tocar se reemplaza al momento; uno editado espera como un solo cambio, y aplicarlo guarda el archivo viejo como<nombre>.v<versión antigua>. - Un archivo en disco que no se puede leer se deja intacto y se informa. Un archivo que no es YAML solo se escribe cuando falta.
Bloques que nombra el dueño#
Un componente declarado Map<String, V> es una sección cuyas claves elige el dueño del servidor —
mundos, regiones, materiales — en vez de claves que decidió el código:
public record Limits(
@Comment("Multiplicador por mundo. Añade los mundos que tenga este servidor.")
Map<String, Double> worlds,
Map<String, Item> items) {
public Limits() {
this(Map.of("world", 7.0), Map.of("ender-pearl", new Item()));
}
public record Item(double cooldown, int maxUses) {
public Item() { this(14.0, 1); }
}
}worlds:
arena: 2.5
survival: 9.0
items:
ender-pearl:
cooldown: 14.0
max-uses: 1V puede ser una hoja — texto, número, booleano, enum, lista — o un record, que se convierte en un
bloque por entrada. La clave tiene que ser String; un Map de Map se rechaza, así que anida un
record y el bloque interior tendrá nombre, comentarios y valores por defecto propios.
| Nada de dentro se poda | Las claves son del dueño. Las claves dentro de un record siguen siendo del código y se podan normal. |
| Las entradas del constructor son ejemplos | Se escriben una vez, al generar el archivo. Una entrada que el dueño borró se queda borrada, y un bloque vaciado se queda vacío. |
| Una entrada inventada hereda los defaults del record | Para lo que no haya escrito. |
| Una entrada ilegible cuesta esa entrada | Se avisa en su propia ruta; el resto carga. |
| Se conserva el orden de inserción | El archivo no se reordena en cada guardado. |
Secciones que no hacen nada#
Un record que implementa Sparse decide por sí mismo si tiene algo que decir. Mientras isEmpty()
responda true, la sección no se escribe en el archivo, leerla de vuelta no dice nada y no vuelve
a aparecer en la siguiente carga; un bloque vacío que escribió una versión anterior se elimina en el
siguiente guardado.
Eso es lo que evita que un efecto con una sola boss bar escriba además un título, una action bar, un sonido, una partícula y un firework vacíos, cada uno con un comentario por clave. Solo vale para secciones cuyos valores por defecto están vacíos por naturaleza — una con valores reales tiene que quedarse en el archivo, o nadie se entera de que existe.
Claves desconocidas#
Cualquier clave que ningún record declare se elimina al cargar y se reporta una vez como
UNKNOWN_KEY. Es una operación de un solo sentido, así que una sección que se está retirando a
propósito merece una nota en el código diciéndolo.
Recargar todo lo de un plugin#
List<ConfigIssue> issues = Configs.reloadAll(this);Cada ConfigIssue dice qué archivo, qué ruta y qué estaba mal. Un valor malo cuesta ese valor, no el
archivo: el resto carga y el valor por defecto rellena el hueco.
¿Falta algo en esta página? Dínoslo en Discord