Working with Configuration Files

What Configuration Files Are For(top)

As you develop, you will come across many instances where you will have to store data. A lot of the time, you can store this data in an object such as a HashMap or an ArrayList. So why use configuration files? The reason for this is that when the server is closed or restarts, it recreates everything and all the data you stored would have been lost. This is because objects such as those are stored in virtual memory. In other words, just as easily as they were created, they are also destroyed.

Now, this is where files come in handy. Files are a way of saving data in a form that won't get deleted after your program is terminated. This is because files are no longer stored in virtual memory, but rather, on your actual storage disk. You can use this for storing information such as player balances, nicknames, and all sorts of data that you want to keep even after the server restarts.

Let's get started.

Using Default Configuration Files(top)

The creation of the configuration file:
saveDefaultConfig() will write the config.yml file from your plugin's jar file to the plugin's data folder. (If that folder doesn't exist it will be created) It will not overwrite an existing config file.

This is essentially all you need to create a quick configuration file, but remember to call it in your onEnable() method to make sure that you have a configuration ready before anything else happens.

Using the Configuration File(top)

To read and write to the config using the above method, we call the getConfig() method. However, if you will be calling getConfig() outside of your main class, you should use the main class's instance. If you do not know how to get instances from other classes, I suggest you check some of the other short guides on how to use constructors (the most commonly used). Once you have an instance, simply use that instance and call getConfig() from it.

Now that you have the config, you can read and write to it using its different getter and setter methods. An example would be:
What is it exactly? The "player-name" is your path in the config. If you've seen other YAML configuration files, you'll notice that they take the format of "label: value". To access the value of a particular path, you can use its name. However, you'll also notice that there are sometimes "sub-paths" wherein there are labels that belong under another label.

To access the value of something that's a sub-path, you can simply use '.' to indicate a lower level like so:
The plugin will read the '.' as an indicator that "Oh! I should check the sub-path."

Note that although I used a String in the getting and setting examples, you can use all sorts of different types as well. For the getters, there exists getInt(), getBoolean(), getList(), and many more. For the setters, it simply takes in the path as the first parameter and an Object as the second. This means that you can set basically any Object.

An important thing to note, however, is that after you write to a configuration file, you should always remember to call saveConfig() if you want the data to be saved to the file. (Warning: saveConfig() will remove all your comments that aren't at the top before the first key)
Configuration has all sorts of fun tricks and tools that you can use to make the best plugin you can make. Use it properly and it can be one of your most powerful assets.

Using Custom Configurations(top)

Creating the File(top)

First of all, you'll want to be able to make your File and FileConfiguration objects available to other classes in your plugin so that you can readily read and write to your different configuration files. How do you do this?

In your main class, create field variables. These are variables that are not contained within a method so that they can be accessed externally.
What does this do? It's a snapshot of how a basic plugin class would look like. What else it does is that it creates a configuration file, namely, "custom.yml". When the plugin is enabled, it calls the createCustomConfig() method. It checks if the File object of the custom config exists and if it doesn't it creates the parent directory and the file.

What about the saveResource(String, boolean) part? You can actually store files inside your jar aside from just classes. To do this, depending on your IDE, you should create a new file in the folder that has your plugin.yml file. Now in your main class, you can call saveResource("name of file in jar here", replaceIfAlreadyExists). This will save the file stored in your jar to the file <data folder>/<name of file in jar> if it doesn't already exist (or if the boolean was true). Now, you've created the custom configuration files!

Reading and Writing to Custom Files(top)

We can do this:
Basically, you can access the configuration the same way as you would do getConfig() from Using Single Configuration Files. If you want to see more on how to manipulate and access configurations, read that section. As for saving, for custom configurations, you need to call FileConfiguration#save(File) (which saveConfig() does under the hood for config.yml) to write the data to the disk.