Configuración

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");
    }
}

Los records anidados se convierten en secciones anidadas, así que la estructura del archivo es el árbol de records.

Leer y escribir

settings.update(actual -> actual.withHost("10.0.0.5"));

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:

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"));

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.

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

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.