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 (.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 save this resource 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 class TestPlugin extends JavaPlugin {

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

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

        // getConfig()...
    }
}

The FileConfiguration of the plugin can be fetched with JavaPlugin#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 Vectors. Here is an example of loading a value from the config for teleporting a player:

public class TestPlugin extends JavaPlugin {

    public void teleportPlayer(Player player) {
        Location to = 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 int chunkX;
    private int chunkZ;
    private String name;

    public TeleportOptions(int chunkX, int chunkZ, String name) {
        // Set the values
    }

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

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

        return data;
    }

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

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.yml");
YamlConfiguration config = YamlConfiguration.loadConfiguration(file);
// Work with config here
config.save(file);

This example reads the items.yml file from your plugin’s data directory. This file must exist, else an error will be thrown.

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.