# `.blk` 文件格式

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

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

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

## `.blk` 文件的文本格式

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

### 文件语法

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

```text
<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*, '<value>' 是定义 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>`: 参数的值可以用引号括起来。
- `[;]`: 如果将分号放在参数之后，则下一个参数可能位于同一行。如果省略分号，则下一个参数应位于新行上。

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

参数可以定义为数组：

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

其中

- `<parameter_name>`: 参数的名称。
- `<type>`: 参数的类型。
- `<values>`: 由分号或换行符分隔的相应类型的值的列表。

**示例:**

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

### 指令和注释

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

#### 指令 `@include`

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

包括另一个 `.blk` 文件：

```text
include <file_name>
```

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

#### 指令 `@override`

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

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

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

**示例:**

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

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

#### 指令 `@delete`

```text
"@delete:<name_of_block_or_parameter>"
```

#### 指令 `@clone-last`

```text
"@clone-last:<name_of_block_or_parameter>"
```

#### 注释

- `//`: 单行注释
- `/* ... */`: 多行注释

### 区块类型

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

#### 顺序

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

**示例:**

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

#### 嵌套

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

**示例:**

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

#### 顺序和嵌套的组合

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

**示例:**

```text
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 编辑器。