YAML Primer

YAML (YAML Ain't Markup) is a human friendly data serialization language. Trine uses YAML because it's as close to plain English as data serialization and configuration formats get. It has no curly braces, it allows you to omit quotation marks for strings in most cases, and it relies on indentation for structure, which makes it incredibly readable compared to other languages, such as JSON and XML.

This brief guide should get you familiarized with most, if not all of the YAML constructs and syntax considerations you'll need to get started with using Trine.

For a more comprehensive guide to YAML syntax and functionality, refer to the official specification, or the YAML Cookbook.

Basic Structures

Mappings

faction_A: FRIENDLY
faction_H: FRIENDLY
minlevel: 80
maxlevel: 80

Mappings are synonymous with map in C++, associative arrays in PHP, and dict in Python. In Trine, every model is a sequence of mappings in which column names are mapped to values.

Block Sequences

- Cloak of Displacement
- Cloak of the Untamed Predator

Block sequences are simply lists or arrays of scalars or other structures.

Inline Sequences

npcflag: [GOSSIP, VENDOR]

Inline sequences share similar syntax for inline arrays/lists in other languages, but do not require scalars to be quoted unless they include characters that need escaping.

Using Anchors

item:
  - method: UPDATE
    where: &FREE_ITEMS
      - Portable Hole
      - Light Feather
    SellPrice: 0
    BuyPrice: 0

npc:
  - method: MERGE
    merge-from: {name: General Goods Vendor}
    items: *FREE_ITEMS

Any YAML node can be anchored and referenced elsewhere as an alias node. To anchor a particular value or set of values, use &name of anchor. To reference an anchor, use *name of anchor.

Merging Mappings

_FreeItemProps: &FREE
    SellPrice: 1
    BuyPrice: 0

item:
  - method: UPDATE
    where: {name: !include "itemlists/pve_weapons.yml"}
    <<: *FREE

Merge keys (<<) allow you to merge all keys and values from one or more mappings (multiple mappings can be referenced in a sequence, like [*FREE_TO_BUY, *FREE_TO_SELL]) into the current mapping.