|This article is in a finalised state, please do not make any major edits to it and instead discuss any changes you wish to make on the talk page.|
YAML is the data interchange format (in most cases for Bukkit a filetype) of choice for the Bukkit server mod, and is utilized both by the core server files and plugins. While the files may appear difficult to understand at first, there are only a few things you need to learn about before you'll be a master at this simple configuration method.
YAML is broken into different hierarchies by indentation -- the number of spaces between each section. We're going to look at the Groups section of the default configuration file for PermissionsBukkit as an example. Please pay attention to the spacing in this guide. Each indentation is composed of four spaces, a normal "tab" insert will NOT parse properly.
Additionally, please bear in mind that all YAML is case-sensitive.
Indentations and Structure
Below is the default groups setting structure.
groups: default: permissions: permissions.build: false admin: permissions: permissions.*: true inheritance: - user user: permissions: permissions.build: true worlds: creative: coolplugin.item: true inheritance: - default
YAML will read this file by each set of indentations it has. The first line is noted as groups, which indicates that everything indented at least once until the next non-indented segment will be a sub-element of groups (in this case individual groups with their settings).
There are three groups in this file: default, user and admin. However, each of these groups can also specify different categories and settings! In each group we can see that there is a permissions category, and inside of it are various nodes.
Within the groups section there are two kinds of categories, one that has listed items with dashes (the inheritance category) and one that has individual nodes, the different ways to set values (in this case permissions for plugins and commands as true and false).
The categories with dashes are used to indicate that you can have multiple items all as part of one category, in this example you can have multiple groups or a single group of inheritance. For example, if admins were set to inherit default and normal users, you would just add another dash and name because users are not set to inherit any groups -- the inheritance line has been removed as well. This kind of category acts as list with each dash as an item, which is why you don't need any colons.
groups: default: permissions: permissions.build: false admin: permissions: permissions.*: true inheritance: - user - default user: permissions: permissions.build: true worlds: creative: coolplugin.item: true
The next kind of category used in YAML is one that simply recurses down into more individual categories until you reach the nodes. This is most obvious in the section for worlds in the user group, as we can see that the coolplugin.item node is assigned as true only within the creative world, but set to false in the survival world.
user: permissions: permissions.build: true worlds: creative: coolplugin.item: true survival: coolplugin.item: false
You can have multiple nodes within each category, which is how you specify long lists of permissions and settings. Some plugins will require you to fill out individual nodes for many different commands so that users don't access things they aren't supposed to. The important thing to remember is that if you do not specify a node for each setting you would like to use, it will default to what the plugin author has specified or crash your server entirely. Please make sure you specify proper settings as noted by the author for each and every plugin you run for best results.
Nodes are how settings are defined within categories. They can be boolean (true or false), string (text), or integer (number) values. Nodes have their own structure depending on their use. In this guide we'll be looking at the differences in how nodes are generally used within plugin configurations versus permissions configurations.
Plugin configurations will use nodes for settings generally in a way that seems the most user friendly, so the nodes will sometimes include capitals. The default configuration for the mcMMO plugin can be viewed on Pastebin with YAML highlighting - click the Raw button for a copy-friendly version. We'll be dissecting this to look at the different ways nodes are handled within it.
The Commands category has a category for each command, and then a node for both what that command's alias should be and whether it is enabled or not. the Name node takes a string while the Enabled node takes a boolean true or false.
Commands: invite: Name: invite Enabled: true mctop: Name: mctop Enabled: true xplock: Name: xplock Enabled: true
The Skills category has a category for each skill, then sub-categories for both abilities and items. The nodes within them use both strings and integers.
Skills: Woodcutting: Requires_Axe: true Herbalism: Green_Thumb: Cobble_To_Mossy: true Mining: Requires_Pickaxe: true Archery: Fire_Rate_Limiter: Enabled: true Interval: 1000 Repair: Stone: Name: Cobblestone ID: 4 Wood: Name: Wood Planks ID: 5 Gold: Name: Gold Bars ID: 266 Anvil_Messages: true Diamond: Name: Diamond Level_Required: 50 ID: 264 Iron: Name: Iron Bars ID: 265
Permissions nodes use nodes with a different sort of style that is based more upon hierarchies and are set to only boolean values, true or false. The most current version of Wahrheit's personal plugins/PermissionsBukkit/config.yml can be viewed on Pastebin with YAML highlighting - click the Raw button for a copy-friendly version. We'll be dissecting this to look at the different ways nodes are handled within it. Please see PermissionsBukkit for more information on configuring Permissions files.
Within each specific group's permissions, individual nodes must be assigned for each plugin in order to have the functionality that you specifically want. Failure to properly assign nodes will result in default configuration and undesirable outcomes.
Nodes are broken down between each plugin and its functions. For example, in the file linked (and further the permissions.yml file associated with it) the Youngling group has had nodes assigned for the Factions and Multiverse plugins.
Youngling: permissions: permissions.build: true server.youngling: true group.youngling: true multiverse.access.nether: false multiverse.access.heavens: false multiverse.access.infinitus: false factions.create: false factions.participate: false
The nodes to look at here are the multiverse.access.nether/heavens/infinitus and factions.create/participate nodes. The Multiverse nodes are broken down into a subgroup of access (in this case for the worlds heavens, nether and infinitus while the Factions plugin has only the root plugin group and the create and access nodes. Because they have been explicitly specified as false, this group will not be able to use those sections of functionality from the plugins even if the plugins would default them to true.
The most important thing to keep in mind is that even though the nodes are stored in categories, each individual node and plugin have their own methods of defining which functions can be used on a server.
It's thoroughly important to understand the way YAML works with formatting indentations, hierarchies and nodes. Properly writing a YAML configuration file is a skill that will set you apart from other server administrators and greatly improve your ability to fix things without having to rely on technical support (though we are always available and happy to help if you submit a ticket).
Good luck, and happy configuring!