Bukkit

Reading and writing YAML

Introduction

YAML is a language configuration files are written in that is being used by Bukkit and most of the plugins running on it. Running a Bukkit server means knowing how to configure it and their plugins, so reading and writing YAML configuration files is an essential skill.

Editor

To open YAML (.yml) files you can use any text editor. We recommend Notepad++ for this, as it adds useful syntax highlighting. The default text editor that shipped with your operating system is fine too.

Format

YAML is based off a format consisting of nodes and key:value pairs. A node stores other nodes and key:value pairs and a key:value pair is just that: a key and a value belonging to that key. For example:

node1:
  key1: value1
  key2: value2
  node2:
    key3: value3
    key4: value4

As you can see indentation is very important. Without a proper indentation after each node of 2 or 4 spaces it would not know what the nodes and what the key:value pairs are. Be sure to always double-check that your indentation is correct.

Tabs are not recognized as valid indentation by the YAML interpreter! In case your text editor automatically creates tabbed indentation when pressing enter, be sure to turn this off or change this to spaces instead.

Key and Node names (for developers)

When coming up with a format for names, stay persistent. Do not make some keys starting with an upper-case character and some others with a lower-case character. In general, the Java format is preferred: each word starting with an upper-case character except the first word. For example: allowWeatherChanges: true

Values

Paths

A file consisting of multiple nodes, with nodes in turn containing key:value pairs, it is possible to represent each key using a path and value. In the first YAML example, key3 would become node1.node2.key3. In case the YAML file represents something like permissions or localization it is good to be aware of this.

Headers

It is not part of the official YAML standard, but some plugins support it: adding headers. A header gives further information about the entire configuration or a single configuration option. Header lines start with # - signs. For example:

# Sets how often a player can use the /back command (in seconds)
backInterval: 60.0

Making mistakes

Making mistakes is human, but with plugins using it and possibly failing because of it, it is best to avoid making mistakes as much as possible. Since a lot of plugins regenerate the configuration after loading it, an error that would cause loading to fail would wipe everything you just wrote. Be sure to keep backups of the configuration, especially if you just made a large amount of changes.

Common formatting mistakes

In all cases the mistake will result in a YAML format error with the line and column numbers indicated.

• Invalid indentation (such as a tab or just one space)
• A key without a value
• Using = or ; instead of :
• Forgetting a quotation mark somewhere
• Using $ in a value without surrounding it with ' - signs (reserved formatting character)