.blk 文件格式

.blk (“block”)是一个 数据块，是 Dagor Engine 中的主要配置格式。它是一个配置文件，类似于.ini, .cfg以及您可能在其他系统中遇到的其他配置文件。

Dagor 引擎使用.blk文件来存储设置、参数和其他重要信息。

有两种类型的.blk文件：text 和 binary。

.blk 文件的文本格式

文本.blk文件是具有专有语法的常规文本文件。

文件语法

.blk文件由一个 块名 和用大括号括起来的可选 参数 组成。

<block_name>{
  <parameter_name>:<type>=<value>[;]
}

其中

• <block_name>: 块的名称，必须以拉丁字母或下划线开头，由拉丁字母、数字或下划线组成。

• <parameter_name>: 参数的名称，必须以拉丁字母或下划线开头，由拉丁字母、数字或下划线组成。

• <type>: 参数的类型，该类型是必需的，可以是以下之一：

  • t: string, <value>是带引号的文本字符串。如果字符串仅包含一个单词，则可以省略引号。字符串不应包含 LF, CR, 或 TAB 符号。相反，请使用符号组合：~r (CR 符号）、~n (LF 符号）、~t (TAB 符号）。

  • b: boolean, <value> 是以下字符串之一：yes, no, true, false, on, off, 1, 0.

  • c: 32-bit color (E3DCOLOR), <value>是一串逗号分隔的整数，表示颜色，格式为 R,G,B 或 R, G, B, A，分量范围为0 到 255。

  • r: floating-point number, <value>是一个浮点数，带有截断的尾随零。

  • m: matrix 3x4, <value>是一个字符串，格式是[[first line][second line][third line][fourth line]]. 这些行是 以逗号分隔的浮点数定义 x，y，z 向量 （p3 – 见下文）。

  • p2: Point2 vector, ‘’ 是定义 x，y 向量的逗号分隔浮点数。

  • p3: Point3 vector, <value> 是定义 x，y，z 向量的逗号分隔浮点数。

  • p4: Point4 vector, <value> 是定义 x、y、z、w 向量的逗号分隔浮点数。

  • ip2: IPoint2 vector, <value> 是定义 x，y 向量的逗号分隔整数。

  • ip3: IPoint3 vector, <value> 是定义 x，y，z 向量的逗号分隔的整数。

• <value>: 参数的值可以用引号括起来。

• [;]: 如果将分号放在参数之后，则下一个参数可能位于同一行。如果省略分号，则下一个参数应位于新行上。

在引号中使用波形符 （~） 来表示特殊字符，例如引号。要在字符串中写入波形符，请使用两个波形符 （~~）。

参数可以定义为数组：

```text
<parameter_name>:<type>[] = [<values>]

其中

• <parameter_name>: 参数的名称。

• <type>: 参数的类型。

• <values>: 由分号或换行符分隔的相应类型的值的列表。

示例:

param1:i[]=[42; 43; 44;]
param2:t[]=[
  "parameter1"
  "parameter2"
  "parameter3"
]

指令和注释

.blk 文件可能包含 parser directives 和 comments。

指令 @include

文件的所有参数都将包含在内，就像它们最初显示在当前文件中一样。包含的文件可能包含其他include文件。

包括另一个 .blk 文件：

include <file_name>

其中 <file_name>是相对于当前.blk文件路径的包含的.blk文件的路径。如果 <file_name>以斜杠(/)开头，则认为该路径来自引擎的根目录，否则从.blk文件所在的目录开始。在工具中，以#开头表示从develop/目录开始。

指令 @override

"@override:<name_of_block_or_parameter>"
"@override:block"{
  "@override:parameter"i=10`
}

当 overrideing 时，需要遵循以下规则：

• 覆盖之前未声明的值会导致日志错误。

• 如果不清楚之前是否声明过要覆盖的值，通常的做法是先将其删除。这可确保从该点开始没有此类变量，从而允许您正常添加变量。

示例:

@override:video{
  @delete:vsync:b=no
  vsync:b=yes
}

上面的代码确保首先删除 vsync。如果之前有 vsync，它将被删除;否则，则不执行任何作。之后，vsync 不需要被覆盖，可以正常添加，无论它之前是否存在vsync。

指令 @delete

"@delete:<name_of_block_or_parameter>"

指令 @clone-last

"@clone-last:<name_of_block_or_parameter>"

注释

• //: 单行注释

• /* ... */: 多行注释

区块类型

块可以有以下类型：顺序、嵌套 以及 顺序 和 嵌套 的组合。

顺序

block_name{
  param_name:type=value
}
block_name{
  param_name:type="value"
}

示例:

lod{
  range:r=70;
}
lod{
  range:r=10000; fname:t="billboard_octagon_impostor.lod01.dag";
}

嵌套

block_name{
  param_name:type=value
  block_name{
    param_name:type="value"
  }
}

示例:

contents{
  lod{
    range:r=70;
  }
}

顺序和嵌套的组合

block_name{
  param_name:type=value
  block_name{
    param_name:type="value"
  }
  block_name{
    param_name:type=value
  }
}

示例:

contents{
  lod{
    range:r=70;
  }
  lod{
    range:r=10000; fname:t="billboard_octagon_impostor.lod01.dag";
  }
}

.blk文件的二进制格式

二进制 .blk文件通过定义的结构进行性能优化，以实现高效的数据存储和检索。

文件结构

二进制 .blk文件中的数据由 header、name 和 string maps、parameters 和 blocks组成。数据排序如下：

• Header

• Name map: 参数和块名称

• String map: 字符串参数

• Root parameters: （可嵌套）

  • paramCnt

  • paramNameId_1

  • paramType_1

  • param_1

  • ...

  • paramNameId_Cnt

  • paramType_Cnt

  • param_Cnt

• Root blocks: （可嵌套）

  • blockCnt

  • Block1 parameters:

    • paramCnt

    • paramNameId_1

    • paramTypeCnt_1

    • param_1

    • ...

    • paramNameId_Cnt

    • paramType_Cnt

    • param_Cnt

  • Block1 blocks:

    • blockCnt

    • Block1_1

    • Block1_2

    • ...

    • Block1_Cnt

      • ...

  • Block_Cnt parameters

  • Block_Cnt blocks

有用的工具

dagor3_cdk有一些有用的工具来处理 .blk：

• binBlk.exe：将二进制和文本 .blk 文件相互转换。

• blkDiff.exe：在两个 .blk 文件之间执行语法差异。

• blkEditor-dev.exe：有助于为.blk文件创建具有动态视图的 GUI 编辑器。