Contenido generado con IA — puede contener errores.

ExyliaLib/Fundamentos

Configuración

Archivos YAML declarados como records de Java, generados a partir de ellos, y migrados cuando cambian de forma.

Página 12 de 5412 min de lectura

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.

java
ConfigFile<Settings> settings = Configs.define(this, "config", Settings.class).load();
int pool = settings.get().database().poolSize();

Declarar un archivo#

java
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ónQué 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.

Los comentarios son el manual

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#

LlamadaQué 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.
java
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 clave

updateAsync 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#

java
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) { }
yaml
lasts: 1m30s
timeout-seconds: 5m     # 300, para el record
interval: 1s            # 20, porque esta clave se escribe en ticks

El 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:

java
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ónQué 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.
java
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"));
Un renombrado sin migración borra las ediciones del dueño

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:

java
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:

java
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");
LlamadaQué 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_EXISTINGLa 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>.yml y 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 language con el servidor en marcha reconstruye los valores por defecto en el siguiente reload; apply all en /exylialib updates cambia 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), nunca getResource: 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 language aún, usa la migración Languages.ADOPT_EXISTING; con ella, llama a Languages.adoptCatalogue antes 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 como lang/<código>/seeded.yml y se leen con Phrases.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:

java
BundledFiles.refresh(this, MyPlugin.class, "menus");        // una carpeta
BundledFiles.refresh(this, MyPlugin.class, "effects.yml");  // un archivo

Llá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 (o defaults-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:

java
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); }
    }
}
yaml
worlds:
  arena: 2.5
  survival: 9.0
items:
  ender-pearl:
    cooldown: 14.0
    max-uses: 1

V 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 podaLas 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 ejemplosSe 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 recordPara lo que no haya escrito.
Una entrada ilegible cuesta esa entradaSe avisa en su propia ruta; el resto carga.
Se conserva el orden de inserciónEl 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#

java
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