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.

  1. "techniques":
  2.   [{
  3.     "passes":
  4.     [{
  5.       "vert": "skybox-vs",
  6.       "frag": "skybox-fs",
  7.       "rasterizerState":
  8.       {
  9.         "cullMode": "none"
  10.       }
  11.       # ... hash sign for comments
  12.     }]
  13.   }]

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

    1. key1: 1
    2. key2: unquoted string

    Note: never omit the space after colon

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

    1. object1:
    2.   key1: false
    3. object2:
    4.   key2: 3.14
    5.   key3: 0xdeadbeef
    6.   nestedObject:
    7.     key4: 'quoted string'

  • Array elements are represented by dash+space prefix

    1. - 42
    2. - "double-quoted string"
    3. - arrayElement3:
    4.     key1: punctuations? sure.
    5.     key2: you can even have {}s as long as they are not the first character
    6.     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:

  1. techniques:
  2. - passes:
  3.   - vert: skybox-vs
  4.     frag: skybox-fs
  5.     rasterizerState:
  6.       cullMode: none
  7.     # ...

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

  • Reference

    1. object1: &o1
    2.   key1: value1
    3. object2:
    4.   key2: value2
    5.   key3: *o1

    This is its corresponding JSON:

    1. {
    2.   "object1": {
    3.     "key1": "value1"
    4.   },
    5.   "object2": {
    6.     "key2": "value2",
    7.     "key3": {
    8.       "key1": "value1"
    9.     }
    10.   }
    11. }

  • Inheritance

    1. object1: &o1
    2.   key1: value1
    3.   key2: value2
    4. object2:
    5.   <<: *o1
    6.   key3: value3

    The corresponding JSON:

    1. {
    2.   "object1": {
    3.     "key1": "value1",
    4.     "key2": "value2"
    5.   },
    6.   "object2": {
    7.     "key1": "value1",
    8.     "key2": "value2",
    9.     "key3": "value3"
    10.   }
    11. }

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

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

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

  1. CCEffect %{
  2.   # YAML starts here
  3. }%

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

Reference Link

[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. ↩