MiniYaml Syntax Basics

  • MiniYaml is a textual, line-oriented, indentation-driven format comprised of related nodes

  • Each line is a node

  • Nodes can be:

    • key-only
    • key, value, and optionally a comment
    • comment-only
    • empty

  • Node indentation is either 1-tab-per-level or 4-spaces-per-level

    • Mixed indentation in a file is not permitted

  • Comments start with # and span the remainder of the line

    • There is currently no support for escaping # characters

Example

a-key

b-key:
    c-key: c-value
        d-key: # d-comment
    e-key: e-value # e-comment

All of these lines/nodes are completely valid.

  • a-key is key-only without a key-terminator (:)
  • b-key: is key-only with a key-terminator
  • c-key: c-value is indented 1 level (4 spaces) with a key and a value
  • d-key: # d-comment is indented 2 levels (8 spaces) with a key and a comment
  • e-key: e-value # e-comment is indented 1 level (4 spaces) with a key, value, and comment

Node Relationships

The first 2 (non-empty) nodes are top-level (not indented).

Top-level nodes do not have parents.

The c node is a child of b since it is after b and indented 1 level further than b.

The d node is a child of c since it is after c and indented 1 level further than c.

The e node is a child of b, making it a sibling of c, since it is after b and indented 1 level further than b.

Invalid Example

    a-key

b-key:
        c-key:

d-key
                # e-comment

A few things are invalid here!

  • The a node is indented so it must be a child of some node, but there is no node above it with 1-less level of indentation so we can not determine the parent

  • The b node is perfectly valid, when a node is not indented that indicates the end of the previous node tree

  • The c node is too-far indented (8 spaces vs the expected 4) so the parent cannot be determined

  • The d node is perfectly valid

  • The e node is perfectly valid as comment-only nodes are always valid

Now that you understand the basics of MiniYaml syntax and relationships you can move on to a real-world example.

A Real-World MiniYaml Example

We'll use part of RA's E1 definition in infantry.yaml as an example:

E1:
	Inherits: ^Soldier
	Inherits@AUTOTARGET: ^AutoTargetGroundAssaultMove
	Buildable:
		Queue: Infantry
	Valued:
		Cost: 100
	Tooltip:
		Name: Rifle Infantry

Immediately, woah! There is a lot going on here!

Let's break this down line-by-line.

This is going to be long but is important to understand.

Line-By-Line

E1:

This node is top-level so it does not have a parent.

Since this node does not have a parent it is defining a new MiniYaml tree with an id of E1.

	Inherits: ^Soldier

This node is indented 1 level more than E1 so it is a child of the E1 node.

Inherits is a special key that indicates that ^Soldier's MiniYaml tree should be inserted right where this node is (so this Inherits: ^Solder node would be replaced with ^Soldier's tree), effectively merging the two trees.

Also note that ^ indicates the referenced definition is a template/partial/abstract, meaning it can only be inherited from, not used in any other way.

If that doesn't make sense now that is fine! We will come back to this in a future chapter.

	Inherits@AUTOTARGET: ^AutoTargetGroundAssaultMove

Again we have an Inherits node but this key is a little different, it has:

  • an @ symbol
  • an identifier after the @

The key (pun intended) bit of information here is that MiniYaml trees must not have the exact same key at the same indentation level.

The reason for that restriction is that MiniYaml keys are also hashmap (typically called Dictionary in .NET) keys, so they must be unique.

The @ allows us to have multiple of the same child node with a postfixed identifier.

Later on you will see an example of this suffix being used.

	Buildable:

Nothing new is happening with this node.

It too is indented 1 level more than E1 so is a child of E1 and a sibling of the two previous Inherits nodes.

		Queue: Infantry

Can you guess this node?

I'm sure you figured it out before you even got here!

It is a child of Buildable, not E1, since it is indented 1 level further than Buildable.

At this point the remaining nodes from the example ought to be obvious.

tip If anything is confusing please reach out on Discord!

Make A Change & Test It

Change the Cost node's value (currently 100) and see what effect that has in-game.

You've just officially become a modder!