How to format your YAML files - DW2MC/DW2ModLoader GitHub Wiki

(This was contributed by SharkMolester / BFHKitteh)

It may be confusing at first, and I as a professional cook may be the wrong person to instruct you on how to do this, but let's begin.

YAML threw me for a loop for a while, till I had a 'aha moment'. You will likely be familiar with languages that use () or some such to denote beginnings and endings of functions and such.

YAML does not use symbols for these things, it uses spaces.

ForExample = (
  ThisIsHowWeNormallyDoThingsRight?
)

Where the indents, tabs and what not are strictly for human readability, and the machine just ignores them because it is reading these () anyway, so to the machine, the spaces don't even exist for the most part.

In YAML, every two spaces is a (). Tabs are not allowed. The machine is reading the spaces for it's logic, so the must be treated as strictly as normal syntax- because they are syntax.

ForExample:
  ThisIsHowWeNormallyDoThingsNow

For lists this may be more confusing even than that.

ThisIsAList = (
  ThingOne = (
    Blah_1
  )
  ThingTwo = (
    Blah_2
  )
)

ThisIsAYAMLList:
  - ThingOne: Blah_1
  - ThingTwo: Blah_2

When it comes to multiple layers, things get even more dicey.

ThisThingHasTheseParts = (
  Taste = (
    No
  )
  Smell = (
    Maybe
  )
  DoTheyLikeIt = (
    People = (
      KarlFranz = (
        OnlyOnGeheimnisnacht
      )
      GreenKnight = (
        DoesNotEat
      )
      AuntieMae = (
        AuntieMaeHasNoNose = (
          True
        )
        SheOnlyEatsPeanuts = (
          False
        )
        SheIsAChaosCultist = (
          True
        )
      )
    )
  )
)

In YAML, we do things like this-

ThisThingHasTheseParts:
  Taste: No
  Smell: Maybe
  DoTheyLikeIt:
    - KarlFranz: OnlyOnGeheimnisnacht
    - GreenKnight: DoesNotEat
    - AuntieMae: 
        AuntieMaeHasNoNose: True
        SheOnlyEatsPeanuts: False
        SheIsAChaosCultist: True

So each entry in a list of items has a '-' to take the place of the "People = ()", but the factors affecting the object are not a list, and do not get the '-', because there is not intermediary definition that needs replacing.

This replacement of the 'list descriptor' with a '-' is confusing at first, but you get the hang of it.

As you can see, YAML saves tons of typing and screen space by turning simple spaces into a part of the syntax.

DW2 example-

ShipHull:
  - update:
      ShipHullId: 16 # Haakonish/escort 0/16/17
      ComponentBays:
        - ComponentBayId: 20
          Type: Weapon
          MaximumComponentSize: 19
          MeshName: 
          RotationHalfArcRange: 1
          DisplayEffectRescaleFactor:
            X: 0
            Y: 0
            Z: 0
          DisplayEffectOffset:
            X: 0
            Y: 0
            Z: 0
          Meshes:
            - BayType: Weapon
              BayTypeIndex: 0
              MeshName: #weapon1
              ModelComponentViewHierarchyNodeId: 0
              MeshIndex: 0
              SupportStructureMeshName:
              SupportStructureModelComponentViewHierarchyNodeId: 0
              SupportStructureMeshIndex: 0
              WeaponMeshType: ShortTurret
              IsLarge: false
              Position:
                X: 0
                Y: 0
                Z: 0
              Forward:
                X: 0
                Y: 0
                Z: 0
              Up:
                X: 0
                Y: 0
                Z: 0
              ForwardWorld:
                X: 0
                Y: 0
                Z: 0
              UpWorld:
                X: 0
                Y: 0
                Z: 0

Here we have a clip from a piece of code that adds a weapon bay to a ship.

• - update: is indented by two spaces, because it is in reference to the ShipHull header at the top of the file which tells the Mod Loader what it is editing.
• ShipHullId is reference to the entry in the vanilla game file, which everything after is in reference to.
• - ComponentBays is then indented by two spaces, signifying a (). It has a - because this is a list item, where each item is identified conveniently by ComponentBayId.
• DisplayEffectRescaleFactor, DisplayEffectOffset are both not lists, they are an item and corresponding values that make up that item.
• Meshes again is a list, which means it would support several meshes for a corresponding ComponentBay (which doesn't really make sense now that I think about it), hence the - at the start of it's item list.
• The Positional information at the bottom of the snippet are the same as the DisplayEffectOffset types earlier. Where it is an item and corresponding values, not a list.