Configuration
YAML files declared as Java records, generated from them, and migrated when they change shape.
The record is the source of truth. The YAML file is output, not input: it is generated from the record's no-argument constructor, comments included, and read back into the same shape.
ConfigFile<Settings> settings = Configs.define(this, "config", Settings.class).load();
int pool = settings.get().database().poolSize();Declaring a file#
public record Storage(
@Comment("Connections kept open. Rule of thumb: cores × 2.")
@Key("pool-size")
int poolSize,
@Comment("Where player data lives.")
String host) {
/** The defaults the file is generated from. */
public Storage() {
this(10, "localhost");
}
}| Annotation | What it does |
|---|---|
@Key("other-name") | The YAML key differs from the record component's name. |
@Comment("…") | Written above the value in the file. Repeatable — several lines, in order. |
Nested records become nested sections, so a file's structure is the record tree.
They are what a server owner reads instead of your documentation. Say what the value changes, in what
unit and in what range — Seconds a player stays tagged after being hit, not tag duration.
Reading and writing#
| Call | What it does |
|---|---|
get() | The current snapshot. A field access, never a re-parse. |
reload() | Re-reads the file. Returns the problems found; an empty list means clean. |
onReload(consumer) | Runs after each successful reload. |
save() | Writes the current snapshot to disk. |
update(operator) | Change and persist in one step, on the caller's thread. |
updateAsync(operator) | The same, with the write off the caller's thread. |
set(key, value) | Writes one value by its dotted key, then reloads so it is checked like anything the owner typed. null removes the key. Returns the problems found. |
issues() | Problems from the last load. |
schema() | A read-only description of the record type. |
settings.update(current -> current.withHost("10.0.0.5"));
config.set("forced-flags.pvp", "DENY"); // for an in-game editor that knows only the keyupdateAsync is for a file an in-game editor saves on every click. The new values are visible to get()
before it returns; only the write waits. Writes of one file run one at a time, and a burst of changes made
before the write starts is written once, with the latest values. save, update, set and reload
write a pending change first, and whatever is pending is written when the plugin disables.
Lengths of time#
public record Settings(
Duration lasts, // the shape for anything new
@Time int timeoutSeconds, // a number that was already there
@Time(Time.Unit.TICKS) long interval) { }lasts: 1m30s
timeout-seconds: 5m # 300, as far as the record is concerned
interval: 1s # 20, because this key is written in ticksThe owner may write 30s, 1m30s, 500ms, 40t, 2h, 2d, 1w, 1mo or 2.5h. A bare number
never changes meaning: @Time declares the unit the key has always been written in, which is both what
a unitless number means and the unit the record is handed (SECONDS unless said otherwise; MILLIS,
TICKS, MINUTES, HOURS, DAYS). A Duration needs no annotation, reads a bare number as seconds, and
is written back as 1m30s; an annotated number is written back as a number. Prefer Duration for anything
new.
Versions and migrations#
A file gets a config-version marker once you declare one, and migrations carry an older file
forward on the first boot after an update:
config = Configs.define(this, "config", Settings.class)
.version(3)
.migration(1, MIGRATION_FROM_1)
.migration(2, MIGRATION_FROM_2)
.load();Steps run in order, however far behind the file is. A migration is built from four operations:
| Operation | What it does |
|---|---|
Migration.rename(from, to) | Moves a value to a new path. A missing source is left alone. |
Migration.remove(path) | Deletes a key. |
Migration.transform(path, rewrite) | Rewrites the value in place. Skipped when the key is absent. |
Migration.all(steps…) | Several of the above as one migration. |
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"));A key no record declares is pruned on load. That is what keeps files clean across updates — and it is exactly why reshaping a section without a migration silently throws away whatever a server owner had written there. Rename in the record and migrate in the same commit.
Moving keys to another file#
Configs.moveTo is a migration that carries keys out of this file and into another file of the same
plugin — usually text leaving config.yml for a translated messages.yml:
Configs.define(this, "config", Settings.class)
.version(3)
.migration(2, Configs.moveTo(this, "messages", Map.of(
"combat.action-bar", "combat.action-bar")))
.load();The owner's values arrive at the new paths whichever file loads first; a section moves with everything under it. A value still at its English default is not carried, so a translated file keeps its translation.
transform is the right tool when a value's meaning changed rather than its place — a token that
was renamed, a number that was in ticks and is now in seconds. It rewrites what is there instead of
replacing it with the shipped default, so an owner's wording and colours survive.
Languages#
A file declared translated() lives in the plugin's language folder rather than at its root:
Configs.define(this, "config", Settings.class) // has a String language, default "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");| Call | What it does |
|---|---|
translated() | The file is lang/<code>/<name>.yml for the plugin's language, and follows it on reload. The record holds the English defaults; a lang/<code>/<name>.yml packaged in the jar replaces the lines it translates. |
Languages.code(plugin) | The plugin's language: its own language key, or ExyliaLib's when that is default, or en. |
Languages.use(plugin, code) | Sets the language from code, for a plugin that keeps its settings elsewhere, such as a database. Wins over config.yml; null or default goes back to it. Reload the plugin's files afterwards. |
Languages.refresh(plugin, anchor, resource) | Installs and updates a translated file or folder the owner edits, as BundledFiles.refresh does. |
Languages.replace(plugin, anchor, resource) | Rewrites a translated folder from the jar on every start, dropping edits — for admin screens the plugin owns. |
Languages.file(plugin, resource) / path(…) | Where a translated file lives on disk. |
Languages.ADOPT_EXISTING | The migration for the version that introduces language: a server that already ran the plugin gets language: custom, and its existing messages.yml and menus/ move into lang/custom/. |
Packaged files go under lang/<code>/ in the jar. English is the base every other language is laid over,
so a line not translated yet still arrives, in English. config.yml must be loaded before the files that
follow it.
Texts in the server's language#
Configs.define(...).localizedDefaults() (1.571.0) is for a settings file that holds some player-visible text
(button names, lore, join messages): the file keeps its place and its config screens, and takes the defaults of
those texts from the server's language.
- The language file goes in the jar at
lang/<code>/<name>.ymland holds only the keys it translates; every key it leaves out keeps the record's default, a map entry included. A list is one value. - A new file is written in the server's language. An existing one is never rewritten: its texts still at the old
default wait in
/exylialib updates, and a text the owner edited is theirs. - Changing
languageon a running server rebuilds the defaults on the next reload;apply allin/exylialib updatesswitches the texts still at the old default. - To ask whether the jar ships a file or folder, use
BundledFiles.packaged(MyPlugin.class, "menus")(1.544.0), nevergetResource: the licence loader keeps the jar in memory.
A catalogue per language#
Text a player reads in a catalogue (an item's lore, a job's perks) is translated like a menu: one real file per
language under plugins/<Plugin>/lang/<code>/, the owner's to edit. Languages.refresh(plugin, anchor, "items")
installs the jar's base items/<id>.yml laid under lang/<code>/items/<id>.yml; Languages.file(plugin, "items")
is where it lives, and everything that writes (editors, importers, the web editor) goes through it.
- Key by key the language wins and a key only the base has is added. A translated list replaces the base's whole.
- Each language is its own copy: switching installs that language's files and edits do not carry over.
- A shipped file the owner deleted is written again on the next refresh.
- Moving an existing catalogue: with no
languagekey yet, use theLanguages.ADOPT_EXISTINGmigration; with one, callLanguages.adoptCataloguebefore the first refresh. CatalogueCheck.problems(...)(1.534.0) tests each language file: only keys the base has, every text translated, every placeholder, token and tag of the base line kept, and no line wider than allowed.- Words the code writes in English that a server may keep as they ship go through
Phrases.tr; words a plugin seeds into its database ship aslang/<code>/seeded.ymland are read withPhrases.seeded(plugin, MyPlugin.class)(1.542.0).
Default changes#
Every config remembers the defaults its owner last reviewed, in .defaults/configs/, and compares them on
each load. A new key is added. A changed or removed default on a key still at its reviewed value is
left alone and listed in /exylialib updates, where the
owner applies or keeps it. A value the owner changed is never listed. Nothing for the plugin to do.
Bundled files#
Files a plugin ships for the owner to edit, rather than generates from a record — menus, catalogues of effects or items — follow the same rules:
BundledFiles.refresh(this, MyPlugin.class, "menus"); // a directory
BundledFiles.refresh(this, MyPlugin.class, "effects.yml"); // one fileCall it before reading the files, on enable and on reload.
- A missing file is written, every time it is missing.
- A new key is added to the owner's file, comments included.
- A changed or removed default on a key still at its reviewed value waits in
/exylialib updates. - Anything the owner changed or deleted is never touched. Reviewed defaults live in
.defaults/files/. - A file whose layout changed too much to merge declares it with a higher
menu-version(ordefaults-version) at its root. An untouched file is replaced at once; an edited one waits as a single change, and applying it keeps the old file as<name>.v<old version>. - A file on disk that does not parse is left untouched and reported. A file that is not YAML is only written when missing.
Blocks the owner names#
A component declared Map<String, V> is a section whose keys the server owner chooses — worlds,
regions, materials — rather than keys the code decided on:
public record Limits(
@Comment("Per-world multiplier. Add the worlds this server has.")
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 may be a leaf — text, a number, a boolean, an enum, a list — or a record, which becomes a block
per entry. The key type must be String; a Map of Map is rejected, so nest a record instead and
the inner block gets a name, comments and defaults of its own.
| Nothing inside is pruned | The keys belong to the owner. Keys within a record entry are still the code's, and are pruned normally. |
| The constructor's entries are examples | Written once, when the file is generated. An entry the owner deleted stays deleted, and an emptied block stays empty. |
| An invented entry gets the record's defaults | For whatever it left out. |
| One unreadable entry costs that entry | Reported at its own path; the rest load. |
| Insertion order is kept | The file does not reshuffle on every save. |
Sections that do nothing#
A record implementing Sparse decides for itself whether it has anything to say. While isEmpty()
answers true the section is left out of the file, reading it back is silent, and it does not
grow back on the next load; an empty block a previous version wrote is removed the next time the file
is saved.
That is what stops an effect with one boss bar from also writing an empty title, action bar, sound, particle and firework, each with a comment per key. It is only for sections whose defaults are empty by nature — one with real defaults must stay in the file, or nobody can find out it exists.
Unknown keys#
Any key no record declares is removed on load and reported once as UNKNOWN_KEY. It is a one-way
operation, so a section that is being dropped deliberately deserves a note in the code saying so.
Reloading everything a plugin owns#
List<ConfigIssue> issues = Configs.reloadAll(this);Each ConfigIssue says which file, which path and what was wrong. A bad value costs that value, not
the file: the rest loads and the default fills the gap.
Something missing on this page? Tell us on Discord