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.

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