# .folder.blk

## .blk 文件类型

['.blk' 文件](../../dagor-tools/blk/blk.md#blk-file-format)与 *assets* 交互（Dagor Engine 中的所有类型资源）可以分为：

- 资源  `.<className>.blk` 文件类型 – 处理资产本身（提取碰撞、动画、创建破坏等）以创建特定类的游戏资源的`.blk`文件。项目中支持的资源列表可以在 `application.blk` 中找到。
- `composit.blk` – 描述最终游戏资源（合成）处理的 `.blk` 文件。

我们将重点关注 `.<className>.blk`文件。

```{seealso}
有关复合文件的更多信息，请参阅 [.composit.blk](./composit_blk.md)。
```

从 *3ds Max* 导出后，我们通常会获得`.dag`文件或`.tif`文件（如果是纹理）。这些文件是惰性的，如果没有引擎的工具就无法使用，引擎需要有关如何处理它们的说明。

这就是 `.<className>.blk`文件开始发挥作用。它们定义资产的处理参数，将其转换为“虚拟”资源。从单个 `.dag` 文件，我们可以生成细节级别 （LOD）、碰撞、骨架等，前提是包含必要的对象和属性。

`.<className>.blk` 文件必须根据游戏中的最终资源名称命名（在 [*Asset Viewer*](../../dagor-tools/asset-viewer/asset-viewer/asset_viewer.md)），并且必须在文件名中包含资产类型(`<className>`) ，因为它包含稍后在配置解释中使用的语义。

例如

- `hangar_watch_tower_d.rendinst.blk` – 游戏资源`hangar_watch_tower_d`  (rendinst),
- `hangar_watch_tower_d.blk` – 同上，但可以是 rendinst 或 prefab（在文件中定义），
- `hangar_watch_tower_d_collision.collision.blk` – 游戏资源
  `hangar_watch_tower_d_collision` (collision),
- `airfield_workshop_a_overlay.tex.blk` – 游戏资源
  `airfield_workshop_a_overlay` (texture).

为避免为每个简单资产（例如 '`.dag`'、纹理、骨架、动画、动态模型等）手动创建 '`.blk`' 文件，*Dagor* 支持高度灵活的系统来创建虚拟资产。

`.folder.blk` 是一种资源`.<className>.blk`文件，这些文件批量处理资产。

`.folder.blk`文件位于 assets 目录中，在大多数情况下，只需将纹理和模型放在适当的目录中就足够了。
所有众多规则，例如 LOD 切换距离、纹理转换规则等，都将自动创建。

```{note}
资源必须具有唯一名称。在大多数情况下，如果资源在其类型中是唯一命名的，则一切正常，但最好具有完全唯一的名称。
```

## .folder.blk的语法

### 一般原则

`.folder.blk`文件定义了资产的导出方式和位置、找到资产的方式以及创建虚拟资源`.<className>.blk`文件的规则。

对于资产，如果存在 `.<className>.blk` 规则，则始终首先应用 `.<className>.blk` 规则（即，如果 `my_asset.dynmodel.blk` 存在，则不会执行创建名为 `my_asset`  的规则）。之后，将应用资产旁边`.folder.blk`文件中的规则，然后应用目录层次结构中较高位置的`.folder.blk`文件中的规则，直到`stopProcessing:b=true`指令。

要了解哪些规则适用于您的文件（例如，`my_texture.tif`或`my_model.dag`），请从资源所在的目录开始，然后在层次结构中查找最近的`.folder.blk`文件。

```{seealso}
有关更多信息，请参阅[.blk 文件格式](../../dagor-tools/blk/blk.md#blk-file-format).
```

## 资产扫描和导出规则

### 基本参数

- `inherit_rules:b=true\false` – 将`.folder.blk` 中的规则应用于层次结构的较高位置。
- `scan_assets:b=true\false` – 扫描此目录中的资源。
- `scan_folders:b=true\false` – 扫描此目录中的子目录。
- `exported:b=true\false` – 是否将内容导出到游戏中。

  ```{important}
  如果要制作要提交并传递给其他人的测试资产，但不要为所有人包含测试资产，强烈建议使用带有复选框的特殊目录。
  ```

#### Export{} 模块

导出参数可以直接通过 names 或 [特殊关键字](#special-keywords) 指定.

##### 基本参数

- `ddsxTexPack:t=""` – 定义当前目录和所有嵌套目录的名称或纹理包，除非被另一个规则覆盖，可能的值：<pack_name>， special 关键字。

- `gameResPack:t=""` – 定义当前目录和所有嵌套目录的资源包名称，除非被另一个规则覆盖，可能的值是： <pack_name>， special 关键字。

   **示例：**

   ```
   ddsxTexPack:t="combat_suits.dxp.bin"
   gameResPack:t="combat_suits.grp"
   ```

   ```
   ddsxTexPack:t="*name_src"
   gameResPack:t="*name_src"
   ```

##### 可选参数

- `ddsxTexPackPrefix:t=""` 或 `gameResPackPrefix:t=""` – 定义包名称之前的前缀，可能的值为：prefix。

  **示例：**

   ```
   ddsxTexPackPrefix:t="aircrafts/"
   ```

- `package:t=""` – 定义其他资源包的名称，可能的值： <pack_name> 或 `*` – 表示放入根包（默认值）。

  **示例：**

   ```
   package:t="outer_space"
   ```

   ```
   package:t="*"
   ```

##### 特殊关键字

- `*name_src` – 包含 **asset** 的目录名称将用作包名称。
- `*path_src` – 包含 **asset** 的目录的路径将用作包名称。
- `*name` – 包含 `.folder.blk` 文件的目录名称将用作包名称。
- `*path` – 包含 `.folder.blk` 文件的目录的路径将用作包名称。
- `*parent` – 父目录的名称将用作包名称。

##### 说明

1. 例如，对于此文件结构：

```
  dir_1
  ├── .folder.blk
  └── dir_2
      └── asset
```

- `*name_src`, `*path_src`: “`dir_2`”名称（或“`dir_1/dir_2`”路径）将用作包名称。
- `*name`, `*path`: “`dir_1`”名称（或“`dir_1`”路径）将用作包名称。
- `*parent`: “`dir_1`”名称将用作包名称。

2. 这是 '`*parent`' 键的工作原理：

```cpp
    if (p[0] != '*')
    {
      if (p[0] == '/')
        return p + 1;
      if (!prefix[0])
        return p;
      buf.printf(260, "%s%s", prefix, p);
      return buf;
    }

    if (stricmp(p, "*parent") == 0)
    {
      fidx = mgr.getFolder(fidx).parentIdx;
      if (fidx != -1)
      {
        p = mgr.getFolder(fidx).exportProps.getStr(paramName, def_val);
        continue;
      }
      p = NULL;
      break;
    }
    else if (stricmp(p, "*name") == 0)
    {
      buf.printf(260, "%s%s%s", prefix, mgr.getFolder(fidx).folderName.str(), pack_suffix);
      return buf;
    }
    else if (stricmp(p, "*name_src") == 0)
    {
      buf.printf(260, "%s%s%s", prefix, mgr.getFolder(src_fidx).folderName.str(), pack_suffix);
      return buf;
    }
    else if (stricmp(p, "*path") == 0)
    {
      makeRelFolderPath(buf, mgr, fidx);
      buf2.printf(260, "%s%s%s", prefix, buf.str(), pack_suffix);
      return buf2;
    }
    else if (stricmp(p, "*path_src") == 0)
    {
      makeRelFolderPath(buf, mgr, src_fidx);
      buf2.printf(260, "%s%s%s", prefix, buf.str(), pack_suffix);
      return buf2;
    }
```

#### 虚拟资源块 (virtual_res{})

虚拟资源块 (`virtual_res{}`) 用于创建资产。它们在 `.folder.blk`文件中从上到下依次应用，然后从目录层次结构中较高的 `.folder.blk` 文件应用，直到遇到 `stopProcessing:b=true` 指令或处理层次结构中的所有 `.folder.blk` 文件。

```
virtual_res_blk{
  find:t="^(.*)\.dds$"
  exclude:t="^(.*_nm)\.dds$"
  className:t="tex"
  name:t="low_$1"
  stopProcessing:b=false
  contents{}
}
```

##### 关键参数

- **find**: 一个正则表达式，用于查找虚拟资源 `.<className>.blk` 的 URL 创建。
- **exclude**: 用于排除与 `find` 模式匹配的文件的正则表达式。
- **className**: Specifies the type of asset in your project.
- **name**: 资产的名称。默认情况下，这对应于 `find` 模式中的第一个捕获组(`name:t="$1"`). 您可以使用捕获组($1 ... $9)和其他字符中的值来构造名称。
- **stopProcessing**: 默认为 `true`，这意味着不会再将`virtual res blk`规则应用于匹配的文件。如果要从一个纹理/模型创建多个资源（例如，动态模型、渲染实例、预制件、骨架、角色），请设置为`false`。

所有其他参数都在 `contents{}` 块中指定，并且通常特定于资产类型。

#### 专用块: content{}, tag{}

在`contents{}` 块中，你可以包含基于 *tags* 的特化块。标记是根据文件完整路径（不包括基本资产路径）中的所有目录名称生成的。

例如，对于`develop/assets/test/warthunder/model/abc.tif`，标记将为`test`, `warthunder`, 和 `model`。专用化块名称遵循 `tag:TTT{}` 格式，例如：

```
contents{
  hqMip:i=1
  //...
  "tag:warthunder"{
    hqMip:i=0
  }
}
```

如果存在适用的专用化块（即完整路径包含指定的标记），则其内容将合并到资产的主 `contents{}` 中。如果应用多个专用化块，则其内容将按照它们在 `contents{}` 块中出现的顺序合并。

此方法允许为位于具有特定名称的不同目录中的类似资产设置不同的属性，而无需复制 `.folder.blk`。

#### 其他详细信息

通常，虚拟资源不需要为资源参数指定文件名（例如纹理名称或`.dag`文件）。默认情况下，这些值是传递的，并且等于从中创建资源的文件的名称。但是，如果需要，您可以指定不同的文件（例如，从 `my_dynmodel.txt` 创建动态模型并引用 `dag_my_dynmodel.lod00.dag`）。

#### 大多数资产的通用参数

- `ddsxTexPack:t`, `gameResPack:t`, `package:t=`: 有关详细信息，请参见 [上面](#basic-parameters-1)。
- `export_PC:b`: 是否导出指定平台的资源（将`PC`替换为任意 4 个字符的平台代码：`_PS4`, `_and`, `ios`,   `PS3`等）。

## 使用 Regexp 规则

[正则表达式](https://en.wikipedia.org/wiki/Regular_expression)在 `.folder.blk` 中用于资源生成，它从内部子目录开始，而不是外部子目录。

### 正则表达式模式

1. **LOD 文件**
   ```
   find:t="^(.*)\.lod00\.dag$"
   ```
2. **纹理和蒙版文件**
   ```
   find:t="^((.*_mask)|(.*_tex_m))\.tif$"
   ```

### 正则表达式符号解释

- `^` ：断言行首的位置。
- `.` ：匹配除行终止符之外的任何单个字符。
- `*` ：匹配前面的元素零次或多次。
- `\` ：转义以下字符，将其视为文本。
- `$` ：断言行尾的位置。

### 处理控制

- `stopProcessing:b=false` : 指示是继续处理还是重新处理已找到和已处理的项目。

### 示例

#### 渲染和预制件创建

要从`.lod00.dag`文件生成渲染并从中创建预制件，请使用：

```
find:t="^(.*)\.lod00\.dag$"
```

#### 纹理处理

要查找并处理所有匹配 `"^(.*_n\.tif$"` 的文件，并使用重排将它们转换为 `.dds` 格式，然后处理所有剩余的`.tif`文件：

```
virtual_res_blk{
  find:t="^(.*_n(_dmg|_expl|_inside)?)\.tif$"
  swizzleARGB:t="RAG0"
}

virtual_res_blk{
  find:t="^(.*)\.tif$"
  convert:b=yes; fmt:t="DXT1|DXT5"
}
```

这些示例演示了如何使用正则表达式查找特定文件类型，并在 `.folder.blk` 框架中对它们执行各种作。