A configurable plugin can be very powerful. A single plugin will be able to function in different ways, depending on user preferences. Essentially, your plugin's configuration file will be similar to the bukkit.yml file for your server. It will allow you to change settings for the plugin without modifying the Java code. This means that you need not rebuild the plugin JAR file every time you wish to change a small detail. If your plugin is public or used by someone else, adding a config file may reduce the time spent on modifying code in the future. The users of your plugin can change the settings that are in the config file by themselves and do not require any additional assistance from you as a developer.
To fully understand why we would want a variable to be configurable, let's look at one of the plugins that we previously talked about. In MobEnhancer, we set the health of zombies to 40 instead of 20. Someone else may wish to use your plugin, but they want to set the zombies' health to 60. You can create two versions of the plugin, which may become very confusing, or you can have one version that is configurable. In the config file on your server, you will have the health of zombies set to 40. But on another server, the health will be set to 60. Even if your plugin will be used on only one server, configuration will allow for a quick and easy method of changing the amount of health.
There are five steps to making your plugin configurable, which are as follows:
- Decide exactly which aspects of your plugin will be configurable
- Create a
config.ymlfile that includes each setting and its default value - Add code to save the default
configfile as well as load/reload the file - Read the configured values and store them in your plugin as class variables
- Ensure that your code references the class variables that the configuration settings are loaded into
The steps need not be performed in this order, but we will discuss them in the following order in this chapter:
- Configurable data types
- Writing a
config.ymlfile - Saving, loading, and reloading your plugin's configuration
- Reading values from the configuration
- Using the configured settings in your plugin
- Writing an
ItemStackvalue in the YAML format - Understanding the YAML structure and hierarchy
- Storing configuration values locally
- Splitting one class into multiple classes and accessing variables and methods from another class
You can easily make most variables in your plugin configurable. The following table comprises various data types and examples of why you may want them to be configurable:
|
Data Type |
How It Can Be Used |
|---|---|
|
|
To define the number of times an event should occur |
|
|
To set the health of a mob when it spawns |
|
|
To turn a specific feature on or off |
|
|
To change a message that is sent to a player |
|
|
To make a customized item appear |
We are going to make MobEnhancer configurable. We want to give the players a choice of setting the value of the zombies' health. This will simply be one double value. Let's expand the plugin to support additional creature types. We will create the config file first and then adapt the program to be able to modify different types of mobs. Therefore, we have decided that the config file will include a single double data type value for each type of mob. This double value will be the mob's health.