Plugin configuration

Configuration files allow users to change certain behavior and functionality of plugins. This guide will outline how to use them.

By default, plugins use a YAML configuration format (.yaml/.yml file). Other formats, such as JSON or TOML, can be used; however, these are not natively supported by Paper, so they will not be covered in this guide.

YAML works by having a tree-like key: value pair structure, as you would have seen in your plugin.yml. An example would look like this:

root:
  one-key: 10
  another-key: David

When accessing indented values, you separate the levels with dots (.). For example, the key for the David string would be root.another-key.

By placing a config.yml file inside your plugin, you can specify the default values for certain settings. This will be located in the resources directory:

When your plugin is initialized, you must copy this file into the plugin’s data directory, so that a user can edit the values. Here is an example of how you would do this in your plugin’s onEnable:

public final class ExamplePlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        this.saveResource("config.yml", /* replace */ false);

        // You can also use this shorthand for the default configuration file (config.yml):
        // this.saveDefaultConfig();
        // the file will be saved if it does not already exist

        // this.getConfig()...
    }
}

The FileConfiguration of the plugin can be fetched with Plugin#getConfig() once it has been saved. This will allow data to be fetched and set with the respective get...(key) and set(key, value). By default, most basic data types are supported by YAML. These can be fetched simply with getString(key) or getBoolean(key).

However, some more complex Bukkit data types are also supported. A few of these include: ItemStack, Location and Vector. Here is an example of loading a value from the config for teleporting a player:

public final class ExamplePlugin extends JavaPlugin {

    public void teleportPlayer(Player player) {
        Location to = this.getConfig().getLocation("target-location");
        player.teleport(to);
    }
}

This is possible as they implement ConfigurationSerializable. You can use this yourself, by implementing and registering a custom class.

public class TeleportOptions implements ConfigurationSerializable {

    private final String name;
    private final int chunkX;
    private final int chunkZ;

    public TeleportOptions(String name, int chunkX, int chunkZ) {
        this.name = name;
        // ...
    }

    public Map<String, Object> serialize() {
        Map<String, Object> data = new HashMap<>(3);

        data.put("name", this.name);
        data.put("chunk-x", this.chunkX);
        data.put("chunk-z", this.chunkZ);

        return data;
    }

    public static TeleportOptions deserialize(Map<String, Object> args) {
        return new TeleportOptions(
                (String) args.get("name"),
                (int) args.get("chunk-x"),
                (int) args.get("chunk-z")
        );
    }
}

Here we can see that we have an instance-based serialize method, which returns a map, and then a static deserialize method that takes a Map as a parameter and returns an instance of the TeleportOptions class. Finally, for this to work, we must call: ConfigurationSerialization.registerClass(TeleportOptions.class);

It is highly likely that you will have many different things to configure in your plugin. If you choose to split these across multiple different files, you can still use the Bukkit FileConfiguration API to read the data from these. It is as simple as:

File file = new File(plugin.getDataFolder(), "items.yaml");
YamlConfiguration config = YamlConfiguration.loadConfiguration(file);
// Work with config here
config.save(file);

This example reads the items.yaml file from your plugin’s data directory. If the file does not exist or an error occurs during reading, an empty configuration will be returned.

Configurate is a third-party library for working with configurations, maintained by the Sponge project. This project is used internally by Paper for its configuration and offers many features that the FileConfiguration API doesn’t have. See their project here for more information.