YAML 101

Cocos Creator 3.0 uses a parser that conforms to the YAML 1.2 standard, which means that Creator is fully compatible with JSON, and use JSON directly without any problems.

"techniques":
  [{
    "passes":
    [{
      "vert": "skybox-vs",
      "frag": "skybox-fs",
      "rasterizerState":
      {
        "cullMode": "none"
      }
      # ... hash sign for comments
    }]
  }]

But of course it would be cumbersome and error-prone, so what YAML provides is a much simpler representation of the same data:

• All quotation marks and commas can be omitted

  key1: 1
  key2: unquoted string
  

  Note: never omit the space after colon

• Like Python, indentation is part of the syntax, representing hierarchy of the data¹

  object1:
    key1: false
  object2:
    key2: 3.14
    key3: 0xdeadbeef
    nestedObject:
      key4: 'quoted string'
  

• Array elements are represented by dash+space prefix

  - 42
  - "double-quoted string"
  - arrayElement3:
      key1: punctuations? sure.
      key2: you can even have {}s as long as they are not the first character
      key3: { nested1: 'but no unquoted string allowed inside brackets', nested2: 'also notice the comma is back too' }
  

With these in mind, the effect manifest at the beginning of this document can be re-write as follows:

techniques:
- passes:
  - vert: skybox-vs
    frag: skybox-fs
    rasterizerState:
      cullMode: none
    # ...

Another YAML feature that comes in handy is referencing and inheriting between data.

• Reference

  object1: &o1
    key1: value1
  object2:
    key2: value2
    key3: *o1
  

  This is its corresponding JSON:

  {
    "object1": {
      "key1": "value1"
    },
    "object2": {
      "key2": "value2",
      "key3": {
        "key1": "value1"
      }
    }
  }
  

• Inheritance

  object1: &o1
    key1: value1
    key2: value2
  object2:
    <<: *o1
    key3: value3
  

  The corresponding JSON:

  {
    "object1": {
      "key1": "value1",
      "key2": "value2"
    },
    "object2": {
      "key1": "value1",
      "key2": "value2",
      "key3": "value3"
    }
  }
  

For our purposes, like when multiple pass has the same properties, etc. it could be really helpful:

techniques:
- passes:
  - # pass 1 specifications...
    properties: &props # declare once...
      p1: { value: [ 1, 1, 1, 1 ] }
      p2: { sampler: { mipFilter: linear } }
      p3: { inspector: { type: color } }
  - # pass 2 specifications...
    properties: *props # reference anywhere

Finally, before writing any YAML, wrap it in a CCEffect block first:

CCEffect %{
  # YAML starts here
}%

You can always refer to any online YAML JSON converter to play around ideas.

Reference Link

• YAML on Wikipedia
• YAML.org Spec

[1] The YAML standard doesn't support tabs, so the effect compiler will try to replace all the tabs in file with 2 spaces first, to avoid the trivial yet annoying trouble of accidentally inserting tabs somewhere. But overall, please try to avoid doing that completely to make sure the compilation goes smoothly. ↩