Tutorial Creating and managing custom YAML files

So far, in my Bukkit coding experience, making a custom yaml file was one of the hardest things I was attempting to figure out how to do, and there were not any tutorials explaining how can I really make one, write to it, load it or save it. I have made this tutorial so that other people don't suffer the horrible fate I did.

Part I: Creating the file and its contents
​

1) Creating the yaml file
So, just like creating the config.yml, we need to create it in the project directory root. Say, we want to create
messages.yml.



Taken in IntelliJ, shouldn't be different if you're using Eclipse, though
(If you're using maven, you'll have to put it in the "resources" directory along with plugin.yml.)

2) Writing its contents
Just like writing any text file (concerning the YAML syntax), and writing the config.yml file content, do the same with messages.yml.


Taken in IntelliJ, shouldn't be different if you're using Eclipse, though

Part II: Adding the file upon plugin startup
​

Assuming you have knowledge in Bukkit coding and bare-boned knowledge with file management
1) Creating the File object


This File object isn't being used, but we will use it to load our messages.yml file.

2) Creating the FileConfiguration object
The class YamlConfiguration provides a handy static method to load it. Using YamlConfiguration#loadConfiguration(File) will be the method used to retrieve our file.



Now, that we have loaded our file instance, we now need to actually add it to the plugin directory. Fortunately, the JavaPlugin class provides a very nice method which saves ANY file type to the plugin directory, JavaPlugin#saveResource(String resourceName, boolean replace). We will be using this to add the file config to our directory. Definitely, we will use it in our onEnable method, AKA on start up.



So here, we are making sure that the messages.yml file doesn't exist, because if it already does then we don't need to create it. After checking if it does not exist, we will create it.

Congratulations if you have made it this far through this tutorial, we have now covered the hardest part which consists of creating it. Now, it will be as easy as a pie.

After loading and starting the plugin up, you should now have messages.yml in your plugin directory, with the contents we wrote in it previously.

Part III: Getting values from the YAML file​

1) Accessing the file configuration
First, we're going to make a way to access our custom configuration and file from the main class. We will be using simple getters.



For now, this is unused, but we will be using it in the next part

2) Getting data and using it in a practical way
So, as you clearly saw while writing the messages.yml content, that it sends a message on join. We will create our listener which does that.
First, we will create our main class instance and use a constructor for that, and create the event handler



Now, to get the string, we will be using FileConfiguration#getString(path). It can be getInt, getBoolean, etc. depending on what you want to get.



Now, we have successfully retrieved our message in the config, so now we can do whatever we want with it. We will be using it to send it to the player.



Finally, registering the event


So, if I join, I'll be getting this:



That's it for getting data. As for setting...

Part IV: Setting data in the YAML file
​

Setting data isn't that much different from getting it, expect that you need to know a few things:
1) If the path entered didn't exist, it will be created with the value you have entered.
2) The file won't update unless you save it
3) If you save/change data too often, it's recommended to save the file either in a repeating task (which is more preferred), or when the plugin shutdowns (in onDisable()), but it's recommended to use a repeating task as server crashes may not call the onDisable method, thus data is unsaved.

So, we will be using a command to set the value of the join message. Create a command class. To access the config, we will also need to create a constructor to set the instance (same process in the listener class)



Back to the command: Now we will do some normal checks before actually setting the data



Our code will be put in the else statement. We will be using a StringBuilder to get all the arguments as a single string, then setting it in the config.

You most likely want to do permission checks, but since this is a tutorial I'll be skipping those details



Now, the message string is the message the sender has put. We will be using it to set our message to.
To set data, we will be using FileConfiguration#set(path, value) to set the message.

Again, make sure not to forget to save!

To set the value, we will be using the method mentioned above, like this:

Now, we've successfully set it. However, we need to save it. Using FileConfiguration#save(file) the file can be saved and updated, however, this method throws an IOException (generally all file-related methods
or constructors do), which can be handled using try { ... } catch (IOException e) { ... }.



We're done! Now all we need to do is register our command in the main class and in our plugin.yml file.

...and in plugin.yml: https://i.imgur.com/EBATe7b.png (image removed due to exceeding 20 images in 1 thread)

Now, in game:


In our messages.yml file:



When joining:


Congratulations if you have made it this far in the tutorial. Not gonna lie this actually was a long one. Hope it helps and hope people don't suffer managing files anymore as I really did.

 

You contradicted yourself so hard...

 

@PhantomUnicorns oof, I hardly noticed that, I fixed this