Editing Plugin Configs

## YAML Tutorial

YAML (a recursive acronym for "YAML Ain't Markup Language") is a human-readable data-serialization language commonly used for configuration files. In Minecraft it's used for plugin configs and settings because it allows owners to change default settings of a plugin without needing to modify a plugin's Java code. A YAML file must follow a syntax, also known as a set of rules, in order for the server to properly read the file and obtain important information from it without errors.

```
#Set the max fly speed, values range from 0.1 to 1.0
max-fly-speed: 0.6

#Set the max walk speed, values range from 0.1 to 1.0
max-walk-speed: 0.8

#Set the maximum amount of mail that can be sent within a minute.
mails-per-minute: 100

# Set to -1 to disable, and essentials.tempban.unlimited can be used to override.
max-tempban-time: 604800

```

### Feature: Comments

* The plugin will read all of the lines of the config to determine what the settings of the plugin should be. For example, if you have "startingBalance: 600" in an economy plugin's config, each player's starting balance when they first join the server would be $600. You can change the value 600 to something else if you want and either reload the plugin or restart the server for it to take effect.
* However, plugin developers often like to provide notes for server owners within their plugin configuration files. Furthermore, you may wish to add reminders for yourself directly within a configuration file. In order to do this we can take advantage of YAML's feature to create a note within the file. When the program tries to read the file to determine what settings to use it will ignore all lines that start with the '#' symbol.
* ```
# to read the file.
startingBalance: 600 # I can also put comments after actual "code" portions.

```

* Please keep in mind that not all YAML configuration files support comments. The developer must add support for comments. Most do, but there are a few rare exceptions. The file "spigot.yml" for example does not support comments. So if you were to try typing comments into the spigot.yml file then restart the server, it would remove all of your comments.
* Furthermore, some developers will allow for comments at the top of a config file. It's rare but noteworthy.

### Preventing Errors

#### Tabs vs Spaces

* YAML files do not support tabs, only spaces. You know how when you click the "Tab" button on your keyboard and it makes that large indent like 4 spaces? Yeah, it will show an error in console if you try to do that in a YAML file and the relevant plugin won't work until that's removed. These issues can be very hard to find if you're new to it and the error message may be misleading so try not to do it from the start.
* Some text editors will allow you to have tabs insert "X" spaces instead of Tab-spaces in order to avoid these sort of problems. To configure this in Notepad++ see this solution.
* If a file isn't working, try copying the entire thing and running it through a YAML parser like the one linked. It will scan for errors in your syntax (the rules of formatting you must follow for the programming language).
	+ If your program has a syntax error, it will try to tell you which line is causing the problem. Click the image to enlarge.
	+ In the example from the image the first line has a tab before the letters (bad). And the second line has spaces before the letters (good). Removing the tab and replacing it with spaces fixes the issue.

#### Quotation Marks (" " and ' ')

Plugins allow you to configure chat output when certain commands or situations occur. For instance, some plugins allow you to configure a join/leave message when a player joins or leaves the server. In these cases you may use either single quotation marks (' ') or double quotation marks (" ") around the contents you wish to provide on each line in the chat as long as the quotation mark type you use remains consistent for the line of text you are encasing in quotation marks. While it is technically allowed to not have any quotation marks you may run into problems when using apostrophes or special symbols.

I.e. EssentialsX offers the config options:

```
# You may use color codes, use {USERNAME} the player's name or {PLAYER} for the player's displayname.
custom-join-message: "&e{USERNAME} has joined the game."

# You may use color codes, use {USERNAME} the player's name or {PLAYER} for the player's displayname.
custom-quit-message: "&e{USERNAME} has left the game."

```

Adding onto the above example, if you want players to see quotation marks in the message you are showing them you must provide a set of single quotation marks for YAML to recognize the line as a string (AKA a line of text) and then the double quotation marks in the message where you want them.

I.e.

```
# You may use color codes, use {USERNAME} the player's name or {PLAYER} for the player's displayname.
custom-join-message: '&e{USERNAME} has joined the "game".'

# You may use color codes, use {USERNAME} the player's name or {PLAYER} for the player's displayname.
custom-quit-message: '&e{USERNAME} has left the "game".'

```
The example above would show players in chat whenever someone joined: **TheirUsername has joined the "game".**

#### Using Apostrophes (')

When using apostrophes in a line of text you must usually enclose the line in double quotation marks like so:

```
custom-join-message: "&eIt's a beautiful day now that {USERNAME} has joined the game."

```
This ensures the program does not think you're trying to start a string of text (I.e. 'It is a beautiful day now'). Otherwise it will think the apostrophe is a single quotation mark and will throw an error in console for there only being one.
Alternatively, you may provide a line of text without quotation marks and use two single quotation marks to tell YAML you are posting an apostrophe instead of quotation marks. For instance,

```
custom-join-message: &eIt''s a beautiful day now that {USERNAME} has joined the game.

```
This will show players in chat using yellow text: **It's a beautiful day now that TheirUsername has joined the game.**

#### Know What is Safe to Edit

```
currency-symbol: '$'

# Minimum acceptable amount to be used in /pay.
minimum-pay-amount: 0.01

```
When editing YAML files it is important to understand what you can edit and what you should leave alone.

* For starters, any comments you can edit. These are the lines that start with `'#'`. You could either edit those lines or remove them entirely.
* If an option says `true` or `false` you may change it to the opposite (so if it's true, you may change it to false without any syntax problems).
* Notice the line at the top: "`currency-symbol:`". If you changed that to say "`pizza:`" then the config file would stop working and show an error in console after reloading the plugin or restarting the server.
* Don't edit stuff that has a colon (`:`) **after** it. But you *may* edit the stuff *after* the colon, if there is a setting afterwards that can be changed.
* Also be sure to keep the indentation the same (and only use spaces not tabs).

#### Summary

YAML files are used to edit configuration files and settings. In order for the file to work you must follow YAML's syntax (also known as rules). A few of these rules are listed below.

1. Don't use tabs in a YAML file. Only use spaces. Using tabs will break the file and you'll have to run it through a Yaml-parser website to determine the issue.
2. If you want to write a comment in the YAML file use a '`#'` symbol before your comment. For example:
	* ```
	# This is a comment.

	```
3. Let's say you have:
	* ```
	teleportUsers: true

	```
	To change this setting you can change the true or false part. Don't modify anything before the `:` symbol.
4. To send strings (AKA one or more words) use quotation marks around the text. Example:
	* ```
	broadcast-messages:
	 - "hello world, I am broadcasting this message!"
	 - "This is another message!"

	```
5. You can also use single quotes on either side of the message but if you want to use an apostrophe in the message that will cause problems unless you put two apostrophes where you want an apostrophe. For example:
	* ```
	broadcast-messages:
	 - 'hello world, I''m sending this!'

	```
	This would show: `**hello world, I'm sending this!**`
6. If you don't want any messages in the example above, do this:
	* ```
	broadcast-messages: []

	```