Custom Configurations

ByteLib supports registering custom configurations alongside the standard plugin configuration and language files. Custom configurations can be registered as optional or external-only, and they do not require versioning, though they can be versioned when needed.

Registering New Configurations

To register custom configurations, inject BytePluginConfig and call register().

public void register(String name, YamlSpec spec);

The name parameter is an internal identifier for the configuration. The spec parameter is a BoostedYamlPluginConfig.YamlSpec record containing the configuration metadata for that file.

Required Configurations

public static YamlSpec of(Path outFile, String resourcePath);

public static YamlSpec of(Path outFile, String resourcePath, String versionKey);

public static YamlSpec of(Path outFile, String resourcePath, String versionKey, boolean useDefaults);

BoostedYamlPluginConfig.YamlSpec.of defines a required configuration file. These files are bundled in the plugin JAR and copied to the server when needed.

outFile

The full output path of the file on the server. This path is not relative to the plugin data folder.

resourcePath

The path to the file inside the plugin JAR, relative to the resources directory.

versionKey

An optional key that identifies the configuration version value used by BoostedYAML to determine whether the file should be updated. Auto-update is enabled if a version key is provided, which will automatically update the file to the latest version without requiring a manual call to update() in your plugin's lifecycle.

In the default config.yml, this is file-version.

useDefaults

An optional key that allows you to determine if your configuration's default values will be used by bulk-getter methods and/or the updater. If a value does not exist on disk, its default will be provided from the defaults only when this is true.

Defaults are required if you are using versioning. This setting is mainly useful if you want to allow for your plugin to create required configuration files on the server and only populate them if they have defaults provided. If a resource is not required and no defaults are provided, useDefaults is automatically set to false and ByteLib will write placeholder YAML in the file instead.

Optional Configurations

If you need a configuration file that is not bundled with the plugin and is instead provided by the server administrator, register it as an external-only file using externalOnly().

public static YamlSpec externalOnly(Path outFile);

// Not really useful since an external file means there is no source of truth.
// Versioning external-only files is generally pointless.
public static YamlSpec externalOnly(Path outFile, String versionKey);
            

Unlike of(), externalOnly() does not take a resourcePath because there is no bundled resource to copy from.

Reading Custom Configurations

To read a custom configuration, use either require(String name) or yaml(String name).

Both methods return the registered YamlDocument when the configuration is available.

require(String name): Returns the configuration and throws an IllegalStateException if it is not registered.
yaml(String name): Returns the configuration if it exists, otherwise null.

Use require() when missing configuration should fail loudly, and use yaml() when the configuration is optional.

Example

The example below registers a custom configuration file. ByteLibPlugin is injected to access the plugin data folder, and a PluginLifecycle is used to register the file during the plugin's onEnable lifecycle stage.

public class MyLifecycleClass implements PluginLifecycle {

    private final BytePluginConfig config;
    private final ByteLibPlugin plugin;

    @Inject
    public MyLifecycleClass(
            BytePluginConfig config,
            ByteLibPlugin plugin
    ) {
        this.config = config;
        this.plugin = plugin;
    }

    @Override
    public void onEnable() {
        config.register(
                "customConfig",
                BoostedYamlPluginConfig.YamlSpec.of(
                        plugin.getDataFolder()
                                .toPath()
                                .resolve("customConfig.yml"),
                        "customConfig.yml"
                )
        );
    }
}
        

23 April 2026