Configuration API

The Config API provides a fluent, strongly-typed wrapper around Bukkit's standard YamlConfiguration. It simplifies file management, supports custom multi-line comments on any path, natively integrates with the Codec system to automatically serialize complex Java objects, and includes built-in schema migration support.

Creating a Configuration File

To create or load a configuration file, instantiate the Config class. The file will be automatically generated inside your plugin's plugins/<plugin_name>/ directory.

// Creates or loads: plugins/abyssallib_example/settings.yml
Config config = new Config("abyssallib_example", "settings");

// Creates or loads inside a subfolder: plugins/abyssallib_example/data/users.yml
Config dataConfig = new Config("abyssallib_example", "users", "data");

Defining Configuration Values

Instead of repeatedly typing out string paths across your codebase, the API uses a Value<T> wrapper. This allows you to define your configuration keys, their default values, and their comments in one centralized location.

If a path does not exist when value() is called, the default value is automatically written to memory.

public final class Settings {
    
    public static final Config CONFIG = new Config("abyssallib_example", "settings");

    // A standard primitive value
    public static final Config.Value<Boolean> DEBUG_MODE = CONFIG.value("general.debug", false)
        .withComment("Enable verbose console logging.", "Do not use in production!");

    // A complex object that uses a Codec for serialization
    public static final Config.Value<ItemStack> STARTER_ITEM = CONFIG.value("items.starter", new ItemStack(Material.APPLE), Codecs.ITEM_STACK)
        .withComment("The item given to players on first join.");

    public static void load() {
        // Automatically creates the file, writes missing default values, and injects comments
        CONFIG.save();
    }
}

Migrating Configurations (Schemas)

As your plugin updates, your configuration files will need to change. The Config API natively integrates with the DataFixer system, allowing you to seamlessly upgrade old YAML files without resetting user data.

Use .schema(targetVersion) to start a MigrationChain, apply your DataFixer steps, and call .apply(). Do this before calling .save() in your load sequence.

public static void load() {
    // Upgrade the config to version 2
    CONFIG.schema(2)
        // From V0 -> V1: Rename a key
        .fix(0, DataFixer.renameKey("general.logging", "general.debug"))
        // From V1 -> V2: Group some values together
        .fix(1, DataFixer.nestKeys("general", "debug", "language"))
        .apply();

    // Save missing defaults and comments for the newly updated layout
    CONFIG.save();
}

Note: This will automatically add a config_version integer to the root of your YAML file to track the current state.

Reading and Writing Data

Once your Value<T> fields are defined, you can easily read or update them from anywhere in your code. If your value uses a Codec, the API handles the decoding and encoding automatically behind the scenes.

// Reading a value
boolean isDebug = Settings.DEBUG_MODE.get();
ItemStack item = Settings.STARTER_ITEM.get();

// Updating a value dynamically
Settings.DEBUG_MODE.set(true);

// You must call save() on the parent Config object to write changes to disk!
Settings.CONFIG.save();

Method Reference

Config Methods

Method	Description
`value(path, defaultValue)`	Defines a standard configuration value (e.g., String, Int, Boolean, Double).
`value(path, defaultValue, codec)`	Defines a complex configuration value that requires encoding/decoding.
`schema(targetVersion)`	Initiates a migration chain to upgrade legacy configuration layouts.
`addComment(path, comments...)`	Associates multi-line comments with a specific YAML path.
`save()`	Writes the current configuration state to disk and safely injects custom comments.
`reload()`	Reloads the configuration data directly from the physical file.

MigrationChain Methods

Method	Description
`fix(fromVersion, dataFixer)`	Registers a `DataFixer` transformation step to execute when migrating from the specified version.
`apply()`	Evaluates the current `config_version` and applies all necessary fixers sequentially, saving the results.

Value Methods

Method	Description
`get()`	Retrieves the strongly-typed value. Throws a `RuntimeException` if decoding fails.
`set(value)`	Updates the value in memory. Will encode the object if a codec was provided.
`withComment(comments...)`	A chainable method that adds comments above this specific value's path in the file.

05 June 2026