YAML 101

Cocos Effect 使用的是符合 YAML 1.2 标准的解析器,这意味着 Cocos Effect 与 JSON 是完全兼容的,直接使用 JSON 也完全不会有问题,例如:

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

当然这也意味着繁琐的语法,所以 YAML 提供了一些更简洁的数据表示方式:

  • 所有的引号和逗号都可以省略

    1. key1: 1
    2. key2: unquoted string

    注意:冒号后的空格不可省略

  • 行首的空格缩进数量代表数据的层级1

    1. object1:
    2. key1: false
    3. object2:
    4. key2: 3.14
    5. key3: 0xdeadbeef
    6. nestedObject:
    7. key4: 'quoted string'
  • 连字符 + 空格 开头,表示数组元素

    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' }

综合以上几点,本文开头的内容就可以简化成下面这样:

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

另一个非常有用的 YAML 特性是数据间的引用与继承。

  • 引用

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

    这个数据解析出来是这样的:

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

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

    这个数据解析出来是这样的:

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

对应到 Cocos Effect 中,比如多个 Pass 拥有相同的 properties 内容时(或更多其他需要复用数据的情况),可以很方便地复用数据,例如:

  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

最后需要注意的是:在 Cocos Effect 文件中使用 YAML 声明的所有流程,都要确保是在 CCEffect 语法块内:

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

若有疑问可复制代码示例到任何 在线 YAML JSON 转换器 观察生成的数据。

参考链接

  1. 标准 YAML 并不支持制表符,但在解析 Cocos Effect 内容时,我们会先尝试把其中所有的制表符替换为 2 个空格,以避免偶然插入制表符带来的麻烦。但请尽量避免插入制表符以确保编译无误。