YAML

This page describes more specific details of how configs work in general. Kingdoms uses YAML (Yet Another Markup Language) for its configs. The most used config format for Minecraft configs in general and the easiest to read in all config formats that exist in general as well.
Kingdoms configs aren't completely compliant with YAML standard specifications.

Removed YAML Features

• Manual tags aren't supported. The plugin will automatically determine the tag in the background and assign it to each option.
• A single file can only have one YAML document attached to it. Multiple documents --- aren't allowed in a single file.

What is a config entry and section?

Sometimes you'll see a text mentioning config entries in the wiki or the developers in general. This is the address that helps you find an option in a YAML file. Sometimes it's written like one.two.three and other times one -> two -> three

In both cases, the words being separated are the option names. So for example, if an option is said to be at one -> two three it means you have to look for something like this:

one:
  two:
    three: 'im the option!'

However in most cases, it's not that easy as the option is surrounded by multiple other options, so in a more complicated examples, we can find our path in the following YAML file like this:

some-option: 3

one: # <--- first option, lets look inside here only
  where-is-zero: idk
  
  two: # <--- Found the second path
    three: 'IM HERE!' # <--- Third path

hello-world:
  a: bye

Note

Usually a good way to know how many levels a certain option has, is to look at the spaces before the option. Kingdoms uses two spaces for each level of config options, (but not all configs are like this in general, but 2 is a pretty standard number.)
So if we look at our previous example:

one:
␣␣where-is-zero: idk
 
␣␣two:
␣␣␣␣three:

Each ␣ here represents a space.

Now let's see a real practical example that's complicated. Usually the language file is the most crowded config file to find an option's address. So if you're told that the message for changing /k help header is commands -> help -> header, first look for commands then help then header (the entire section is marked because there are two options for it)

Tip

The word section for configs refers to a config option that holds other config options:

hello: # <-- A config section named "hello" that holds two options named "one" and "two"
  one: 1
  two: 2

Advanced YAML

In this section we will take a look at the main configuration system used for the plugin.
This is by no means a complete tutorial for YAML, however it gives you practical examples and also features that are not present in standard YAML.

Variables

In YAML files you can define variables using two things called anchor and alias.
Variables are obviously used to write something just once without writing it over and over again. Image you have this option:

# Lets say this option is for a turret that gives you the ability to configure which entities it targets for each level.
# Most leveling systems in the config already inherit their values from previous levels, but just for the sake of example.
targets:
  1: [ZOMBIE, SKELETON, ENDERMAN, PLAYER, WITHER_SKELETON, COW, PIG]
  2: [ZOMBIE, SKELETON, ENDERMAN, PLAYER, WITHER_SKELETON, COW, PIG]
  3: [ZOMBIE, SKELETON, ENDERMAN, PLAYER, WITHER_SKELETON, COW, PIG]

# This list might even become a lot longer and every time you want to add something, you have to do it 3 times
# So instead we can do this:

common-entites: &common-entities [ZOMBIE, SKELETON, ENDERMAN, PLAYER, WITHER_SKELETON, COW, PIG]
targets:
  1: *common-entites
  2: *common-entites
  3: *common-entites

&common-entities is called an anchor, which defines a variable. The option name and the anchor name can be different, they have nothing to do with each other. That's just there because some people like to define their variables like this:

targets:
  1: &common-entities [ZOMBIE, SKELETON, ENDERMAN, PLAYER, WITHER_SKELETON, COW, PIG]
  2: *common-entites
  3: *common-entites

*common-entities is called an alias. You use this when you want to refer to a variable defined before, not when defining a new variable. Note that before accessing a variable it must be defined before using an alias, for example, this won't work:

name: *zombie-name
zombie-name: &zombie-name "My name is zombie"

This of course works with config sections:

common-settings: &common-settings
  enabled:
    condition: true
    glow: true
    name: "Enabled"
  else:
    name: "Disabled"

first-option: *common-settings
second-option: *common-settings

is transferred to:

first-option: 
  enabled:
    condition: true
    glow: true
    name: "Enabled"
  else:
    name: "Disabled"
second-option:
  enabled:
    condition: true
    glow: true
    name: "Enabled"
  else:
    name: "Disabled"

Sometimes you want to change certain options from a section alias, you can do what's called merging:

common-settings: &common-settings
  condition: true
  glow: true
  name: "Enabled"

first-option:
  enabled:
    <<: *common-settings
    name: "&2Open"

# ->

first-option:
  enabled:
    condition: true
    glow: true
    name: "&2Open"

This puts all the options from common-settings but uses name: "&2Open" instead of name: "Enabled"

This also works with lists but with a slightly different format:

list1: &list
 - 1
 - 2

list2:
 - 0
 - <: *list
 - 3

# Gives you
list2:
 - 0
 - 1
 - 2
 - 3

Extra Exclusive Features

Kingdoms configs aren't 100% YAML compliant. Features such as explicit tags, directives, explicit document start and ends, and a few others. 99% of the time, people don't even bother which these features when dealing with configuration files, so there's no issue.

Kingdoms adds support for sequence merging. We discussed mapping merging above, however the standard YAML doesn't allow you to do the following while Kingdoms does:

sequence: &seq [ how, are ]
other-sequence:
  - hello
  - <<: *seq
  - you

other-sequence gets converted into:

other-sequence:
  - hello
  - how
  - are
  - you

As for practical use cases, this would be useful for adding multiple lines to lore of items inside GUIs that share the same description, but are different in some parts. (Example in nexus.yml)

YAML Functions

Kingdoms also adds a special syntax called alias functions. It's a more advanced form of aliases which allows you to build your own options.
A great practical example can be found in the default misc-upgrades GUI. Again to be clear the name [fn-misc] isn't important at all, but this format is chosen to avoid conflict. However the name fn-misc is important since all yaml functions should start with fn- prefix. This option takes 3 arguments of any type which can later be used inside the returned value. It's kinda similar to how Haskell works. The only important note here is that list parameters can be used inside of lists here without needing to do the - <: *argument thing. They automatically expand the list (Note that this only works with list-like lores, not when using the | format lores).

You can see how the function is called here. Just like section merging but with a normal yaml list after it.

Another way of calling functions which is compliant with YAML spec, is writing them this way:

'[style]': &fn-style
  args: [ "{content}" ]
  return: ...

option:
  '[fn]': *fn-style
  '{content}': |
    Hello how are you doing?
    Is everything alright?

As you can see, this style of calling functions is cleaner when there are two many arguments as it supports named parameters and lets you use all YAML features for each parameter in a compliant way such as using string literals.
The plugin is mostly distancing itself from the first format and starting to use the second format more often, because the most important thing about them is being YAML compliant which helps with external services like Crowdin.