# 目录结构概述

## 通用目录结构

在 Dagor Engine 目录结构的顶层，根目录分为四个主要部分：

- [主源代码](#main-sources). 包含引擎核心和关联的工具。
- [项目](#projects). 包含特定于单个游戏项目的文件。
- [示例](#samples-1). 包括示例项目以供参考。
- [文档](#documentation). 提供全面的指南和参考。

下面是常规目录结构的树：

```text
<engine_root>/
├── <project_name>/
│   ├── prog/
│   │   ├── ui/
│   │   ├── scripts/
│   │   └── gameBase/
│   ├── develop/
│   │   ├── assets/
│   │   ├── levels/
│   │   ├── gui(ui)/
│   │   └── gameBase/
│   ├── game/
│   ├── tools/
│   └── application.blk
├── prog/
│   ├── _jBuild/
│   ├── 1stPartyLibs/
│   ├── 3rdPartyLibs/
│   ├── dagorInclude/
│   ├── engine/
│   ├── tools/
│   ├── scripts/
│   ├── gameLibs/
│   ├── daNetGame/
│   ├── daNetGameLibs/
│   └── samples/
├── samples/
└── _docs/
```

## 主源代码

主源代码目录 `prog/` 包含几个关键部分，每个部分都有特定的用途：

### `_jBuild/`

包含用于为不同平台构建代码的常见 `.jam` 文件设置。

### `1stPartyLibs/`

包含内部库。这些库不依赖于引擎或其他内部项目，除了`3rdPartyLibs/`之外，这使得它们可以在 Dagor 引擎项目之外使用。

### `3rdPartyLibs/`

包含不依赖于 Gaijin 代码的外部库。`3rdPartyLibs/` 中的代码是完全独立的。

### `dagorInclude/`

包含构成核心功能的基本组件和模块，包括 3D 渲染、动画系统、调试工具、设备驱动程序、特殊效果、资源管理等等。可能依赖于 `1stPartyLibs/` 和 `3rdPartyLibs/`。

### `engine/`

包含 Dagor 引擎的核心组件，包含对游戏开发至关重要的广泛功能。此目录包括用于控制台处理的系统、设备驱动程序、游戏资源、基本 GUI 组件、输入/输出系统等。大多数部件可选择用于各种应用。它们可能依赖于`1stPartyLibs/` 和 `3rdPartyLibs/`。

### `tools/`

包含各种 [Dagor 工具](../dagor-tools/index.rst) 的源代码。

### `scripts/`

包含常用脚本，主要是 Quirrel，它是 Dagor 引擎中使用的主要动态脚本语言。

### `gameLibs/`

包含用于游戏开发的库。这些库中的大多数都是跨平台的。依赖项仅限于`1stPartyLibs/`, `3rdPartyLibs/`, `engine/`, 和其它 `gameLibs/`。

### `daNetGame/`

包含正在进行的工作 （WIP） [实体组件系统 （ECS）](../api-references/dagor-ecs/dagor_ecs.md) 框架来构建跨平台网络游戏。此代码库可能会发生变化，AI、武器、玩家自定义和地形等特定组件预计将移至`daNetGameLibs/`，并可能使用 dascript 和 ECS 原则进行重写。依赖项应仅包含`1stPartyLibs/`, `3rdPartyLibs/`, `engine/`, `daECS/`, 和 一些`gameLibs/`。目标是支持任何物理游戏的通用网络解决方案，包括专用服务器和玩家托管服务器（不包括对等服务器）。

### `daNetGameLibs/`

包含有助于使用 daNetGame 框架开发游戏的库。依赖项可以包括 `1stPartyLibs/`, `3rdPartyLibs/`, `engine/`, `daNetGame/`, `daECS/`, 和一些 `gameLibs/`。

### `samples/`

包含核心引擎和游戏库的示例项目都存储在此处。

**库开发原则**

图书馆应遵守 **FIRS（T）** 原则：

- **专注**：每个库都应该有一个责任。
- **独立**：库应尽量减少依赖项。
- **可重用**：代码应设计为可重用。
- **小**：保持库简洁易管理。
- **可测试**：确保库可以轻松测试。

鼓励开发人员根据依赖项将满足这些原则的代码移动到`1stPartyLibs/` 或 `gameLibs/`中，而不是将其保留在单个项目中。这种做法有助于避免代码重复，并增加代码审查和改进的可能性。

## 项目

### 项目的一般架构

我们的游戏项目遵循标准的目录结构，并向开发人员推荐使用：

```text
<project_name>/
 ├── prog/
 │   ├── ui/
 │   ├── scripts/
 │   └── gameBase/
 ├── develop/
 │   ├── assets/
 │   ├── levels/
 │   ├── gui(ui)/
 │   └── gameBase/
 ├── game/
 ├── tools/
 └── application.blk
```

### `prog/`

包含游戏的源代码、C++ 文件、着色器以及游戏直接使用的配置文件。

### `ui/`

包含游戏用户界面的脚本和配置，侧重于控件、布局和组件等元素。

### `scripts/`

包含定义和管理各种游戏行为、事件和逻辑的脚本文件和相关资源。

### `gameBase/`

包含与游戏内容和项目的虚拟文件系统管理相关的基本元素。该目录包括：

- `content/`: 存储游戏资源和内容文件的子目录。
  这通常包括各种游戏资源，例如纹理、模型、音频文件和游戏所需的其他数据。
- `create_vfsroms.bat`: 用于创建虚拟文件系统 （VFS） ROM 的批处理脚本，该 ROM 是打包的文件存档，可优化游戏资源的加载和管理。
- `mk.vromfs.blk`: VFS ROM 创建过程的配置文件，指定如何在虚拟文件系统中打包和组织文件。

### `develop/`

包含原始数据，包括界面的资产库、位置、图像和字体。

### `assets/`

Assets 是项目的构建块，用于创建位置和游戏对象。资产的主要特征包括：*name*、*type* 和
*性能*。这些属性指定要使用的原始数据以及如何将其编译为最终游戏数据。

资产类型的示例包括 `tex`, `dynModel`, `rendInst`, `composit`, 和 `fx`。例如，纹理 (`tex`) 属性可能包括对源图像文件（通常为 `.tif`, `.tga` 或其他标准格式）、纹理格式（例如 `DXT1`, `DXT5`）的引用，以及具有从源图像生成设置的 mipmap 的数量。同样，其他资产类型具有编译所需的唯一属性。

**资产基础**

资产库是通过扫描资产目录创建的。此过程由我们所有处理资产的工具（daBuild 扫描然后执行构建）执行，[Asset Viewer](../dagor-tools/asset-viewer/asset-viewer/asset_viewer.md) 扫描、创建资产树，并允许查看基础 [daEditor](../dagor-tools/daeditor/daeditor/daeditor.md) 扫描并允许使用基础中的资源来编辑位置）。

在扫描期间，使用两种方法定义资产：

1. **显式资产**. 由一个`<asset_name>.<asset_type>.blk`文件定义，包含资产的属性。
2. **虚拟资产**. 根据`.folder.blk` 文件中描述的扫描规则生成。

扫描以递归方式执行，遍历所有子目录。每个目录可能包含一个`.folder.blk`文件，该文件指定：

- 是否扫描子目录（默认为 scan）。
- 是否扫描当前目录下的资产（默认为 scan）。
- 从当前子目录和嵌套子目录编译资源的位置和名称，以及是否这样做。
- `virtual_res_blk{}`是用于为目录中找到的任意文件生成虚拟资产的块。

### `levels/`

包含各种游戏关卡及其相应的资源。每个子目录代表一个不同的关卡，其中包含有效渲染和管理该关卡所需的所有资源和配置。

### `gui(ui)/`

包含用于构建和管理图形用户界面 （GUI） 的资源和脚本。此目录的组织用于处理字体生成、UI 外观、输入配置和整体 UI 结构。

### `game/`

生成输出目录，包括编译的代码和资产。这本质上是交付给玩家的。

### `tools/`

包含工具的数据，包括用于资产构建和运行编辑器的着色器。

- `dsc2-*`: 适用于不同平台的着色器编译器，将以我们的脚本格式 + HLSL 编写的着色器代码转换为可在各种系统上使用的二进制格式（例如，DX11、DX12、适用于 Windows 的 SpirV、适用于 macOS 和 iOS 的 Metal、适用于 Linux 和 Android 的 SpirV）。
- `vromfsPacker-dev.exe`: vromfs Packer（带有只读文件的虚拟容器，用于快速加载和游戏使用，结构类似于`.zip`档案）。我们打包 vromfs 以向播放器提供 3-4 个文件，而不是 3000-4000 个分散的文件。

  ```{seealso}
  有关更多信息，请参阅
  [vromfs](../dagor-tools/resource-building/vromfs.md).
  ```

- `daBuild-dev.exe`: 用于将原始资产数据构建到游戏资源中的工具。它从资产库（`develop/` 目录）获取数据，并在验证后将其编译为适合游戏在 `game/` 目录中加载的格式。
- `impostorBaker-dev.exe`: 用于准备特殊树视图纹理的工具，与 daBuild 结合使用，以优化游戏中的树渲染（当复杂的树模型替换为从一定距离看起来相同的简单纹理时）。

  ```{seealso}
  有关更多信息，请参阅
  [Impostor Baker](../dagor-tools/impostor-baker/impostor_baker.md).
  ```

- `assetViewer2-dev.exe`: Asset Viewer（有时是编辑器）。读取资源库，将其呈现为树（其中 branches 是资源目录，叶子是资源本身），并允许选择资源以在视区窗口中查看它，并在属性面板中查看其属性。某些资产类型(`fx`, `fastPhys`, `composit`) 可以在退出查看器时进行编辑和保存，而其他资产类型(`animChar`, `physObj`) 可以动态可视化和调试。

  ```{seealso}
  有关更多信息，请参阅
  [Asset Viewer](../dagor-tools/asset-viewer/asset-viewer/asset_viewer.md).
  ```

- `daEditor3x-dev.exe`: 位置编辑器。允许编辑地形、水域以及沿样条线（线）和跨区域（多边形）手动放置资产。它可以将编辑后的位置编译/导出为适合游戏加载的格式（在 `game/` 目录中）。

  ```{seealso}
  有关更多信息，请参阅
  [daEditor](../dagor-tools/daeditor/daeditor/daeditor.md).
  ```

- `csvUtil2-dev.exe`: 用于将原始数据（例如，来自 Crowdin 的 CSV）的语言本地化准备为游戏可读格式的实用程序。它执行各种检查（是否存在所有语言的翻译等）。

### `application.blk`

该文件设置资产库的配置和编辑器的数据目录位置。在 `application.blk` 中，可以定义：

- 项目中使用的资产类型的列表。
- 可以使用特殊导出器插件编译为游戏资源的资源类型列表。
- 从中扫描资产的根目录（资产库）的列表。
- 一组设置，用于将资源编译到游戏中的位置和方式（`game/` 目录）。

  ```{seealso}
  有关更多信息，请参阅
  [application.blk](../assets/all-about-blk/application_blk.md).
  ```

## 示例

`samples` 目录包含演示核心引擎和各种游戏库用法的示例项目。这些示例项目可作为实际参考，展示了使用 Dagor 引擎进行游戏开发的不同方面。它们旨在说明最佳实践，并为开发人员构建自己的项目提供起点。每个示例都经过精心设计，以突出特定的特性和功能，使开发人员更容易在自己的工作中学习和应用这些概念。

## 文档

文档目录`_docs` 包含使用 Dagor Engine 和开发的综合指南、参考资料和资源。它包括详细的手册、API 文档和教程，旨在帮助开发人员了解引擎的功能和最佳实践。本节对于新手和有经验的开发人员都是必不可少的，它提供了对 Dagor 引擎的架构、特性和功能的宝贵见解。