Minecraft/Bukkit/Understanding YAML

From Multiplay Wiki
Jump to: navigation, search
Mpuk40editlock.png 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).

Defining Variables

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.

Categories

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

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

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

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.

Conclusion

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!