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

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.

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

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

10 March 2026