文件系统

有时在团队合作开发的情况下，由于与 UnigineEditor 一起使用，可能将无效的guids.db文件提交到存储库（由于合并错误或其他原因），从而导致错误。您可以通过 -skip_guidsdb 启动命令行选项使Engine忽略guids.db文件。在这种情况下，引擎将在data文件夹内的所有.meta文件以及所有已安装外部目录和程序包中搜索GUID。默认情况下，UnigineEditor使用此参数来避免错误，并始终重新生成guids.db文件以确保其有效性。

动态扫描允许引擎为data文件夹中的所有文件（包括装载点中的文件）形成一个虚拟文件系统。动态扫描在引擎启动时执行。对于物理存储在data文件夹中的文件，使用指向地址文件的相对路径实时启用文件更改跟踪。

如果不是通过UnigineScript对文件系统进行更改，则可能需要调用 filesystem_reload 控制台命令。

加载UnigineEditor时，引擎会在运行时跟踪文件中所做的更改：它会检查上次修改文件的时间并在内存中进行更新。如果未加载UnigineEditor，则在重新加载世界后重新加载已更改的文件。

注意

但是，只有将文件添加到虚拟文件系统中时，才有可能（在启动时已执行动态扫描）。

加载UnigineEditor时，安装点无法自动跟踪更改。每个安装点均根据需要手动更新。

如果您在运行时添加新文件，则引擎将不了解有关此类文件的任何信息（因为虚拟文件系统已在启动时形成）。重新扫描文件系统会占用大量资源，因此，您可以使用 addVirtualFile（） 通过API将新文件添加到虚拟文件系统。

如果指定的 -data_path 是绝对的，则当前工作目录可能与具有二进制可执行文件的目录不同。但是，当数据目录的路径是相对路径时，引擎会将当前目录切换为带有二进制可执行文件的目录。

通过API访问data目录之外的文件时，应相对于当前目录指定该文件的路径。例如：

// cbox.mesh is stored outside the data directory, so the path is specified relative to the current directory
ObjectMeshStatic cbox = new ObjectMeshStatic("../../data/cbox.mesh");

虚拟文件系统的构建块是装载：文件系统创建为根装载，并且可以通过使用其他装载点轻松扩展。这种方法允许通过将任何外部文件夹和软件包添加到数据目录来扩展项目的虚拟文件系统。

在创建项目时，将在data文件夹中创建root_mount.umount文件。这是JSON格式的文件，代表根安装点。它存储已在其中创建根挂载的UNIGINE SDK版本，并忽略过滤器（即，指示应忽略的文件夹）：

{
    "version": "2.9.0.0"
	"ignore_filters": [
		".svn",
		".git",
		".teamcity",
		".thumbnails"
	]
}

root_mount.umount文件已经包含默认的忽略过滤器，并且可以根据需要使用通配符扩展该列表。

相对于data文件夹设置路径。如果应该忽略的文件夹位于其他任何文件夹内（例如data/folder_1/.svn），则该文件夹的相对路径应设置为忽略过滤器（folder_1/.svn）。

如果一个项目不包含root_mount.umount文件（该项目是使用UNIGINE SDK的先前版本创建的，或者该文件已被删除），则该项目将运行而不会忽略data中的任何文件夹。

可以手动创建root_mount.umount文件，也可以使用 API 通过代码创建。

UNIGINE支持以下类型的文件归档以节省空间或打包生产版本的资源：

• UNG （使用以下命令创建的存档的UNIGINE本地格式：Archiver工具）
  注意

  UNG存档中文件的最大大小限制为2 GB。
• ZIP
• 通过UNIGINE API创建的自定义 C ++软件包

除了节省空间外，归档文件还可以加速资源加载，因为可以线性读取归档文件中的文件。

UNG和ZIP归档文件如果位于data文件夹中，则会自动加载。文件与未归档文件的添加方法一样，被添加到虚拟文件系统。

注意

软件包不能存储另一个软件包。另外，不能打包安装点。但是，它可以引用程序包。

存档对引擎完全透明。无需显式解压缩归档文件，因为它们的内容会自动处理为未打包。存档文件的处理就像未存档一样。例如，如果您有data/project/archive.ung并想在其中寻址directory/file.txt，则只需指定以下路径：project/directory/file.txt。

在存档中，可以以任何方式组织文件。但是，应仅在档案的根目录中放置具有唯一名称的文件。否则，文件搜索将返回错误的结果。

注意

使用GUID使您避免在处理存档文件时控制名称的唯一性。

以下是存档的不正确文件树的示例：

• my_archive.ung
  • my_folder
    • file_2.txt
  • file_1.txt
  • file_2.txt

在这种情况下，file_1.txt没问题，因为它的名称是唯一的。另一方面，file_2.txt会引起问题：它不能保证将返回非根文件。

可以如下指定正确的存档结构：

• my_archive.ung
  • my_folder
    • file_2.txt
  • another_folder
    • file_2.txt
  • file_1.txt

在这种情况下，具有相同名称的文件存储在不同目录中，因此文件搜索将完全正确。

如果已存档文件与未存档文件之间发生名称冲突，则返回第一个匹配文件。搜索按以下顺序进行：

1. 未存档的文件
2. UNG档案中的文件
3. ZIP存档中的文件

通过UNIGINE API，也可以使用FilesSystem函数处理存档。

UNIGINE的文件系统为 strict 。这意味着虚拟文件系统始终检查确切的文件位置，而不是在data目录中的某个位置进行搜索。这种方法使处理项目文件清晰透明。

虚拟文件系统使用虚拟路径来操作文件。虚拟路径是data文件夹中文件的路径（包括装载点中的文件）。引擎始终尝试将任何路径转换为虚拟路径。虚拟路径有几种类型：

• 完整的虚拟路径-data文件夹中文件的路径
• 部分虚拟路径
• 指定为绝对一个的虚拟路径

在挂载点内指定文件的虚拟路径时，它始终包含挂载点的名称。例如，如果您有一个指向D:\external_content的data/external_images.umount挂载点，则应按以下方式访问此文件夹中的任何文件：

external_images/1.tga

部分的#

使用部分路径意味着文件系统执行非严格文件搜索。在这种情况下，只能提供没有路径的文件名。在用户可以手动输入路径的情况下，允许使用部分路径，例如：

• 世界装载作业。您只能指定一个世界名称，它将被找到并加载。
• 在源代码中包含路径。
• UI文件中的路径.
• 手动材料文件中的路径。
• 基础材料文件中的纹理路径。
• 字体文件的路径。

注意

如果名称不是唯一的，则将加载第一个使用该名称的文件。

也可以提供唯一指定文件的子路径。例如，要加载data/project/my_world/my_world.world，可以使用my_world.world（如果名称是唯一的）或my_world/my_world.world。

您还可以通过 GUID 引用文件以唯一地指定文件。

注意

可以通过FileSystem类的resolvePartialVirtualPath()方法解析部分路径。它将给定的部分虚拟路径转换为完整的虚拟路径，然后可以根据需要进行处理。

虚拟路径被指定为绝对路径#

getVirtualPath("D:/projects/unigine_project/test/1.tga"); // returned: test/1.tga

getAbsolutePath("D:/projects/unigine_project/test/1.tga"); // returned D:/content/test/1.tga

项目中使用的大量内容通常存储在网络驱动器上。要访问此类内容，应使用以下格式指定网络路径：

//share/content/1.tga

文件系统成功解析了网络路径。

您可以创建引用网络文件夹的安装点。它使您避免不必要地将资产复制到本地计算机，从而节省了磁盘空间。

相对路径是相对于当前目录指定的路径。例如，当您需要使用二进制可执行文件将文件写入同一文件夹时，应使用该文件。如果指定虚拟路径，则默认情况下会将其写入data目录。

使用相对路径时，您可以重新定位基于UNIGINE的应用程序或将其复制到另一台计算机上，所有资源将被正确加载。加载速度也没有任何损失：由于虚拟文件系统，它的加载速度与通过绝对路径加载文件一样快。可以使用绝对路径将资源加载到data文件夹之外，但此类项目将不可移植。

在将文件名添加到虚拟文件系统中时，使用FileSystem函数从源代码访问文件时，通常应使用相同的名称和路径来加载和删除文件：

• 对于默认资源，函数返回相对于data文件夹的完整路径。
• 如果加载文件并指定相对路径，请使用相对路径删除资源。
• 如果使用绝对路径加载文件，请使用绝对路径删除资源。

注意

使用GUID使您避免在处理文件时控制路径。

您可以通过isAbsolute()函数检查路径是绝对路径还是相对路径。

文件系统还允许您使用getVirtualPath()函数获取相对于data文件夹的文件路径。

通过路径访问特定资产的方式取决于其类型：

• 本地资产 只需按其名称即可访问：
  源代码 (C++)

  ImagePtr image = Image::create("image.dds");

• 所有 非本地资产 都有一个主要运行时文件。因此，当您通过资产名称引用资产时，将实际使用该主运行时文件。例如，如果您指定：
  源代码 (C++)

  ImagePtr image = Image::create("image.png");

  实际将使用image.dds生成的主运行时文件。

  您也可以直接访问任何资产源文件（而不是运行时文件）。例如，如果需要指定.png纹理，则应编写以下内容：

  源代码 (C++)

  ImagePtr image = Image::create("asset://image.png");

  在这种情况下，运行时.dds文件将被忽略，而.png源文件将被使用。

• 每个 容器资产 也具有主运行时，对于FBX资产，它是一个生成的.node文件。因此，您可以使用以下引用：
  源代码 (C++)

  NodeReferencePtr node = NodeReference::create("teapot.fbx");

  在这种情况下将使用teapot.node生成的运行时文件。
  
  

  您可以访问容器资产的每个运行时文件。例如，FBX文件具有为其生成的.node和.mesh运行时文件。您可以通过以下方式访问生成的.mesh文件：

  源代码 (C++)

  MeshPtr mesh = Mesh::create("teapot.fbx/teapot.mesh");

您还可以使用 GUID 访问项目中的任何运行时或资产。如果指定了文件的GUID，则使用与此GUID对应的确切路径：

UGUID asset_guid; // GUID of the asset named "1.tga"
const char *asset_path = "1.tga";

ImagePtr image = Image::create(asset_guid); // -> 1.tga
ImagePtr image = Image::create(asset_path); // -> 1.dds

例如，项目中支持三种本地化语言：英语（默认），德语和法语。根据语言，应在启动时加载不同的启动纹理。

要组织资源，请使用以下文件修饰符对其进行命名：

• data
  • splashes
    • splash.png （这是纹理的默认版本。在我们的例子中，是带有英文标题的纹理）
    • splash.de.png （德语标题）
    • splash.fr.png （法文标题）

之后，您需要在代码中通过addModifier()指定要使用的修饰符。在系统脚本中调用此函数，因为需要在世界及其资源开始加载之前注册修饰符。例如，要加载德国初始屏幕和低分辨率纹理界面：

// unigine.cpp

int init() {
	...
	
	// Register modifier
	engine.filesystem.addModifier("de");
	
	// Set a splash texture
	engine.splash.setWorld("textures/splash.png");   // splash.de.png will be automatically used
	...
	
	return 1;
}

您也可以使用-extern_define CLI选项传递语言（例如，如果用户在启动器中选择一种语言）。

bin\main_x64d.exe -extern_define "LANG_DE"

这是如何在代码中处理定义的传递。

// unigine.cpp
string lang = "";

int init() {
	...
	
	// Parse EXTERN_DEFINE
	#ifdef LANG_DE
		lang = "de";
	#elif LANG_FR
		lang = "fr";
	#endif
	
	if(lang != "") {
		engine.filesystem.addModifier(lang);
	}
	
	// Set a splash texture: splash.de.png or splash.fr.png will be used if the language is passed
	engine.splash.setWorld("textures/splash.png");	// otherwise, splash.png
	...

	return 1;
}