目录结构概述

通用目录结构

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

主源代码. 包含引擎核心和关联的工具。
项目. 包含特定于单个游戏项目的文件。
示例. 包括示例项目以供参考。
文档. 提供全面的指南和参考。

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

<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 工具的源代码。

`scripts/`

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

`gameLibs/`

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

`daNetGame/`

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

`daNetGameLibs/`

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

`samples/`

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

库开发原则

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

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

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

项目

项目的一般架构

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

<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 扫描、创建资产树，并允许查看基础 daEditor 扫描并允许使用基础中的资源来编辑位置）。

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

显式资产. 由一个<asset_name>.<asset_type>.blk文件定义，包含资产的属性。
虚拟资产. 根据.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 个分散的文件。

See also

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

See also

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

See also

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

See also

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

`application.blk`

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

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

See also

有关更多信息，请参阅 application.blk.

示例

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

文档

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

目录结构概述

通用目录结构

主源代码

_jBuild/

1stPartyLibs/

3rdPartyLibs/

dagorInclude/

engine/

tools/

scripts/

gameLibs/

daNetGame/

daNetGameLibs/

samples/

项目

项目的一般架构

prog/

ui/

scripts/

gameBase/

develop/

assets/

levels/

gui(ui)/

game/

tools/

application.blk

示例

文档

`_jBuild/`

`1stPartyLibs/`

`3rdPartyLibs/`

`dagorInclude/`

`engine/`

`tools/`

`scripts/`

`gameLibs/`

`daNetGame/`

`daNetGameLibs/`

`samples/`

`prog/`

`ui/`

`scripts/`

`gameBase/`

`develop/`

`assets/`

`levels/`

`gui(ui)/`

`game/`

`tools/`

`application.blk`