Setting up Config API

The Config API is extremely opinionated. Developers are free to do whatever they want with their configuration files, but two files are required for the API to function.

config.yml – the primary configuration file for your plugin.
lang/en_US.yml – the default language file for your plugin. ByteLib supports any number of language files, but en_US is mandatory.

In addition to creating these files, several properties must exist in the configuration and language files.

file-version

A number representing the version of the default configuration. This value is used to automatically update configs on the server.

language

Determines which language file the Config API uses for translations. This should default to en_US.

bypass-language-check

A boolean controlling whether ByteLib validates that the selected language is officially supported.

This allows server administrators to provide their own language files. The default value should always be false.

language-version

A number representing the version of the language file. This allows ByteLib to automatically update translation files.

Setting up the files in your project

In your src/main/resources folder, create a config.yml file and a folder called lang.
Inside the lang folder, create the file en_US.yml.
Add the required properties to config.yml.
Add the required property to lang/en_US.yml.

Your files should resemble the following structure.

# config.yml
file-version: 1
language: en_US
bypass-language-check: false

# lang/en_US.yml
language-version: 1
        

To add additional translations, create another .yml file in the resources/lang folder. ByteLib automatically discovers language files, so no additional configuration is required.

Allowing custom translations

ByteLib allows server administrators to create their own translation files in order to crowdsource translations or customize chat messages.

After enabling this option, upload a .yml file named after the desired locale to the server directory:

plugins/[plugin]/lang/

Then update the language property in config.yml to match the filename (without the extension). The translation will load automatically.

Upgrading your config

As your plugin evolves, you may need to modify or add new configuration values.

Add new properties, comments, or defaults to the configuration file.
Increment the file-version value. Increasing it by 1 is the recommended approach.

Using config

To access configuration or language files, inject BytePluginConfig into your class.

The BytePluginConfig interface provides two primary methods:

config(): Returns the default configuration file.
lang(): Returns the currently active language file.

Both methods return a BoostedYAML YamlDocument. Refer to BoostedYAML documentation for working with YAML values and properties.

If you need to access a custom configuration file, use either yaml(String name) or require(String name).

yaml(String name): Returns the YamlDocument if it exists, otherwise null.
require(String name): Returns the document but throws an exception if the configuration is not loaded.

Use yaml() when the configuration file is optional and require() when the configuration is required for plugin functionality.

A utility method, locale(), returns the name of the active locale such as en_US.

Reloading config files

To reload a specific configuration file, call reload(String name), where name is the configuration key.

To reload all configuration files, call reload(). This reloads:

the default configuration
the active translation file
all registered custom configuration files

11 March 2026