文件系统

Sometimes in case of teamwork development, an invalid guids.db file may be committed to the repository (due to an incorrect merge or otherwise) causing errors when working with UnigineEditor. You can make the Engine ignore the guids.db file via the -skip_guidsdb startup command line option. In this case, the Engine searches for GUIDs among all .meta files inside the data folder and all mounted external directories and packages. UnigineEditor uses this argument by default to avoid errors, and always re-generates the guids.db file to ensure its validity.有时在团队合作开发的情况下，由于与 UnigineEditor 一起使用，可能将无效的guids.db文件提交到存储库（由于合并错误或其他原因），从而导致错误。您可以通过 -skip_guidsdb 启动命令行选项使Engine忽略guids.db文件。在这种情况下，引擎将在data文件夹内的所有.meta文件以及所有已安装外部目录和程序包中搜索GUID。默认情况下，UnigineEditor使用此参数来避免错误，并始终重新生成guids.db文件以确保其有效性。

Dynamic scanning allows the Engine to form a virtual file system for all files within the data folder (including the ones inside mount points). Dynamic scanning is performed on the Engine start-up. For files physically stored inside the data folder, file changes tracking is enabled in real time using relative paths to address files. 动态扫描允许引擎为data文件夹中的所有文件（包括装载点中的文件）形成一个虚拟文件系统。动态扫描在引擎启动时执行。对于物理存储在data文件夹中的文件，使用指向地址文件的相对路径实时启用文件更改跟踪。

If changes to the file system are made not by means of UnigineScript, you may need to call the filesystem_reload console command.如果不是通过UnigineScript对文件系统进行更改，则可能需要调用 filesystem_reload 控制台命令。

When UnigineEditor is loaded, it tracks changes made in files at run time: it checks the time of the last modification of such files and updates them in the memory. If UnigineEditor isn't loaded, the changed files are reloaded after reloading the world.加载UnigineEditor时，引擎会在运行时跟踪文件中所做的更改：它会检查上次修改文件的时间并在内存中进行更新。如果未加载UnigineEditor，则在重新加载世界后重新加载已更改的文件。

注意

However, it is possible only if files are added to the virtual file system (dynamic scanning has been performed on the start-up).但是，只有将文件添加到虚拟文件系统中时，才有可能（在启动时已执行动态扫描）。

If you add new files at run time, the Engine won't know anything about such files (as the virtual file system has been formed on the start-up). Re-scanning the file system is resource-consuming, therefore, you can add new files to the virtual file system via API by using addVirtualFile().如果您在运行时添加新文件，则引擎将不了解有关此类文件的任何信息（因为虚拟文件系统已在启动时形成）。重新扫描文件系统会占用大量资源，因此，您可以使用 addVirtualFile（） 通过API将新文件添加到虚拟文件系统。

When the specified -data_path is absolute, the current working directory may differ from the directory with the binary executable. However, when the path to the data directory is relative, the Engine switches the current directory to the one with the binary executable.如果指定的 -data_path 是绝对的，则当前工作目录可能与具有二进制可执行文件的目录不同。但是，当数据目录的路径是相对路径时，引擎会将当前目录切换为带有二进制可执行文件的目录。

When accessing a file outside the data directory via API, the path to such file should be specified relative to the current directory. For example:通过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");

The building block of the virtual file system is a mount: the file system is created as a root mount and can be easily extended by using additional mount points. This approach allows extending the virtual file system of your project by adding any external folders and packages to the data directory.虚拟文件系统的构建块是装载：文件系统创建为根装载，并且可以通过使用其他装载点轻松扩展。这种方法允许通过将任何外部文件夹和软件包添加到数据目录来扩展项目的虚拟文件系统。

At project creation, the root_mount.umount file is created in the data folder. This is a file in the JSON format that represents the root mount point. It stores the version of UNIGINE SDK, in which the root mount has been created, and ignore filters (i.e., indication to folders that should be ignored):在创建项目时，将在data文件夹中创建root_mount.umount文件。这是JSON格式的文件，代表根安装点。它存储已在其中创建根挂载的UNIGINE SDK版本，并忽略过滤器（即，指示应忽略的文件夹）：

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

The root_mount.umount file already contains default ignore filters and the list can be extended as necessary using wildcards. root_mount.umount文件已经包含默认的忽略过滤器，并且可以根据需要使用通配符扩展该列表。

The path is set relative to the data folder. If a folder that should be ignored is located inside any other folder (for example data/folder_1/.svn), the relative path to that folder should be set as an ignore filter (folder_1/.svn).相对于data文件夹设置路径。如果应该忽略的文件夹位于其他任何文件夹内（例如data/folder_1/.svn），则该文件夹的相对路径应设置为忽略过滤器（folder_1/.svn）。

If a project does not contain the root_mount.umount file (the project was created with a previous version of UNIGINE SDK or the file has been deleted), the project would run without ignoring any folders in data.如果一个项目不包含root_mount.umount文件（该项目是使用UNIGINE SDK的先前版本创建的，或者该文件已被删除），则该项目将运行而不会忽略data中的任何文件夹。

The root_mount.umount file can be created manually or via code using API.可以手动创建root_mount.umount文件，也可以使用 API 通过代码创建。

UNIGINE supports the following types of file archives to save space or pack the production version of resources: UNIGINE支持以下类型的文件归档以节省空间或打包生产版本的资源：

• UNG (a UNIGINE-native format for archives created with Archiver tool)
  注意

  The maximum size for a file inside a UNG archive is limited to 2 GB.The maximum size for a file inside a UNG archive is limited to 2 GB.
  The maximum size for a file inside a UNG archive is limited to 2 GB. UNG （使用以下命令创建的存档的UNIGINE本地格式：Archiver工具）
  注意

  The maximum size for a file inside a UNG archive is limited to 2 GB. UNG存档中文件的最大大小限制为2 GB。
• ZIP ZIP
• Custom C++ packages created via UNIGINE API通过UNIGINE API创建的自定义 C ++软件包

Besides saving space, archives also speed up resource loading, as files in an archive are read linearly.除了节省空间外，归档文件还可以加速资源加载，因为可以线性读取归档文件中的文件。

UNG and ZIP archives are loaded automatically if they are located within the data folder. Files are added to the virtual file system the same way as non-archived files. UNG和ZIP归档文件如果位于data文件夹中，则会自动加载。文件与未归档文件的添加方法一样，被添加到虚拟文件系统。

注意

A package cannot store another package. Also a mount point cannot be packed. However, it can refer to a package.软件包不能存储另一个软件包。另外，不能打包安装点。但是，它可以引用程序包。

Archives are completely transparent to the Engine. There is no need to explicitly unpack the archives, as their content is automatically handled as not packed. Archived files are addressed as if they are non-archived. For example, if you have data/project/archive.ung and want to address directory/file.txt within it, simply specify the following path: project/directory/file.txt.存档对引擎完全透明。无需显式解压缩归档文件，因为它们的内容会自动处理为未打包。存档文件的处理就像未存档一样。例如，如果您有data/project/archive.ung并想在其中寻址directory/file.txt，则只需指定以下路径：project/directory/file.txt。

Inside the archive, files can be organized in any way. However, in the root of the archive only files with unique names should be placed. Otherwise, the file search will return incorrect results.在存档中，可以以任何方式组织文件。但是，应仅在档案的根目录中放置具有唯一名称的文件。否则，文件搜索将返回错误的结果。

注意

Using GUIDs allows you to avoid the need to control uniqueness of names when working with archived files.使用GUID使您避免在处理存档文件时控制名称的唯一性。

Here is an example of an incorrect file tree for an archive:以下是存档的不正确文件树的示例：

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

In this case, there is no problem with file_1.txt, since its name is unique. file_2.txt, on the other hand, will cause problems: it does not guarantee that a non-root file will be returned.在这种情况下，file_1.txt没问题，因为它的名称是唯一的。另一方面，file_2.txt会引起问题：它不能保证将返回非根文件。

The correct archive structure can be specified as follows:可以如下指定正确的存档结构：

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

In this case, the files with the same names are stored in different directories, so the file search will be perfectly correct.在这种情况下，具有相同名称的文件存储在不同目录中，因此文件搜索将完全正确。

If there is a name collision between an archived file and a non-archived one, the first matching file is returned. The search is performed in the following order:如果已存档文件与未存档文件之间发生名称冲突，则返回第一个匹配文件。搜索按以下顺序进行：

1. Non-archived files 未存档的文件
2. Files in UNG archives UNG档案中的文件
3. Files in ZIP archives ZIP存档中的文件

From UNIGINE API, archives are handled using the FileSystem functions as well.通过UNIGINE API，也可以使用FilesSystem函数处理存档。

UNIGINE's file system is strict. It means that the virtual file system always checks the exact file location instead of searching somewhere inside the data directory. Such approach makes working with project files clear and transparent. UNIGINE的文件系统为 strict 。这意味着虚拟文件系统始终检查确切的文件位置，而不是在data目录中的某个位置进行搜索。这种方法使处理项目文件清晰透明。

The virtual file system operates with virtual paths to files. A virtual path is a path to a file inside the data folder (including files in mount points). The Engine always tries to convert any path to a virtual one. There are several types of virtual paths:虚拟文件系统使用虚拟路径来操作文件。虚拟路径是data文件夹中文件的路径（包括装载点中的文件）。引擎始终尝试将任何路径转换为虚拟路径。虚拟路径有几种类型：

• Full virtual path - a path to a file inside the data folder完整的虚拟路径-data文件夹中文件的路径
• Partial virtual path 部分虚拟路径
• Virtual path specified as an absolute one指定为绝对一个的虚拟路径

When specifying a virtual path to a file inside the mount point, it always includes the name of the mount point. For example, if you have a data/external_images.umount mount point, that refers to D:\external_content, you should access any file in this folder as follows:在挂载点内指定文件的虚拟路径时，它始终包含挂载点的名称。例如，如果您有一个指向D:\external_content的data/external_images.umount挂载点，则应按以下方式访问此文件夹中的任何文件：

external_images/1.tga

Partial部分的#

Using partial paths means that the file system performs a non-strict file search. In this case, only a file name can be provided without a path. Partial paths are allowed for cases where the user can enter a path manually, such as:使用部分路径意味着文件系统执行非严格文件搜索。在这种情况下，只能提供没有路径的文件名。在用户可以手动输入路径的情况下，允许使用部分路径，例如：

• World loading operations. You can specify only a world name and it will be found and loaded.世界装载作业。您只能指定一个世界名称，它将被找到并加载。
• Including paths in the source code.在源代码中包含路径。
• Paths in UI files. UI文件中的路径.
• Paths in manual material files. 手动材料文件中的路径。
• Paths to textures in base material files. 基础材料文件中的纹理路径。
• Paths to font files.字体文件的路径。

注意

If a name is not unique, the first found file with such name is loaded.如果名称不是唯一的，则将加载第一个使用该名称的文件。

It is also possible to provide a sub-path that uniquely specifies a file. For example, to load data/project/my_world/my_world.world, you can use my_world.world (if a name is unique) or my_world/my_world.world.也可以提供唯一指定文件的子路径。例如，要加载data/project/my_world/my_world.world，可以使用my_world.world（如果名称是唯一的）或my_world/my_world.world。

Also you can refer files by GUIDs to uniquely specify a file.您还可以通过 GUID 引用文件以唯一地指定文件。

注意

A partial path can be resolved via the resolvePartialVirtualPath() method of the FileSystem class. It converts the given partial virtual path to the full virtual one, and then it can be processed as required.可以通过FileSystem类的resolvePartialVirtualPath()方法解析部分路径。它将给定的部分虚拟路径转换为完整的虚拟路径，然后可以根据需要进行处理。

Virtual Path Specified as Absolute虚拟路径被指定为绝对路径#

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

A lot of heavy content used in a project is usually stored on a network drive. To access such content, a network path should be specified in the following format:项目中使用的大量内容通常存储在网络驱动器上。要访问此类内容，应使用以下格式指定网络路径：

//share/content/1.tga

The network paths are successfully resolved by the file system.文件系统成功解析了网络路径。

You can create a mount point that refers to a network folder. It allows you to avoid unnecessary copying of assets to a local computer and, therefore, saves the disk space.您可以创建引用网络文件夹的安装点。它使您避免不必要地将资产复制到本地计算机，从而节省了磁盘空间。

A relative path is a path specified relative to the current directory. It should be used when, for example, you need to write some file in the same folder with the binary executable. If you specify a virtual path, it will be written into the data directory by default. 相对路径是相对于当前目录指定的路径。例如，当您需要使用二进制可执行文件将文件写入同一文件夹时，应使用该文件。如果指定虚拟路径，则默认情况下会将其写入data目录。

When relative paths are used, you can relocate your UNIGINE-based application or copy it onto another machine, and all resources will be properly loaded. There is no loading speed penalty as well: it is as fast as loading files by an absolute path due to the virtual file system. It is possible to use absolute paths to load resources outside the data folder, but such project will not be portable.使用相对路径时，您可以重新定位基于UNIGINE的应用程序或将其复制到另一台计算机上，所有资源将被正确加载。加载速度也没有任何损失：由于虚拟文件系统，它的加载速度与通过绝对路径加载文件一样快。可以使用绝对路径将资源加载到data文件夹之外，但此类项目将不可移植。

As file names are added to the virtual file system, usually the same name and path should be used to load and remove the file when accessing from your source code by using FileSystem functions:在将文件名添加到虚拟文件系统中时，使用FileSystem函数从源代码访问文件时，通常应使用相同的名称和路径来加载和删除文件：

• For default resources, functions return full paths relative to the data folder.对于默认资源，函数返回相对于data文件夹的完整路径。
• If you load a file and specify a relative path, use a relative path to delete the resource.如果加载文件并指定相对路径，请使用相对路径删除资源。
• If you load a file using an absolute path, use an absolute path to delete the resource.如果使用绝对路径加载文件，请使用绝对路径删除资源。

注意

Using GUIDs allows you to avoid the necessity to control paths when working with files.使用GUID使您避免在处理文件时控制路径。

You can check whether a path is absolute or relative via the isAbsolute() function.您可以通过isAbsolute()函数检查路径是绝对路径还是相对路径。

The file system also allows you to get a path to a file relative to the data folder by using the getVirtualPath() function.文件系统还允许您使用getVirtualPath()函数获取相对于data文件夹的文件路径。

The way of accessing a certain asset by path is determined by its type:通过路径访问特定资产的方式取决于其类型：

• Native assets are accessed simply by their name:
  源代码 (C++)

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

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

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

• All non-native assets have a primary runtime file. So, when you refer to the asset by its name, this primary runtime file will be actually used. For example, if you specify:
  源代码 (C++)

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

  The image.dds generated primary runtime file will actually be used.The image.dds generated primary runtime file will actually be used.

  You can also directly access any asset source file (not a runtime file). For example, if you need to specify a .png texture, you should write the following:You can also directly access any asset source file (not a runtime file). For example, if you need to specify a .png texture, you should write the following:

  源代码 (C++)

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

  In this case, the runtime .dds file will be ignored, .png source file will be used.In this case, the runtime .dds file will be ignored, .png source file will be used.

  The image.dds generated primary runtime file will actually be used.You can also directly access any asset source file (not a runtime file). For example, if you need to specify a .png texture, you should write the following:In this case, the runtime .dds file will be ignored, .png source file will be used. 所有 非本地资产 都有一个主要运行时文件。因此，当您通过资产名称引用资产时，将实际使用该主运行时文件。例如，如果您指定：
  源代码 (C++)

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

  The image.dds generated primary runtime file will actually be used.实际将使用image.dds生成的主运行时文件。

  You can also directly access any asset source file (not a runtime file). For example, if you need to specify a .png texture, you should write the following:您也可以直接访问任何资产源文件（而不是运行时文件）。例如，如果需要指定.png纹理，则应编写以下内容：

  源代码 (C++)

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

  In this case, the runtime .dds file will be ignored, .png source file will be used.在这种情况下，运行时.dds文件将被忽略，而.png源文件将被使用。

• Each container asset also has a primary runtime, in case of an FBX asset it is a generated .node file. So, you can use the following reference:
  源代码 (C++)

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

  The teapot.node generated runtime file will be used in this case.
  
  The teapot.node generated runtime file will be used in this case.
  
  

  You can access each runtime file of a container asset. For example, an FBX file has .node and .mesh runtime files generated for it. You can access the generated .mesh file in the following way:You can access each runtime file of a container asset. For example, an FBX file has .node and .mesh runtime files generated for it. You can access the generated .mesh file in the following way:

  源代码 (C++)

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

  The teapot.node generated runtime file will be used in this case.
  
  You can access each runtime file of a container asset. For example, an FBX file has .node and .mesh runtime files generated for it. You can access the generated .mesh file in the following way: 每个 容器资产 也具有主运行时，对于FBX资产，它是一个生成的.node文件。因此，您可以使用以下引用：
  源代码 (C++)

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

  The teapot.node generated runtime file will be used in this case.
  
  在这种情况下将使用teapot.node生成的运行时文件。
  
  

  You can access each runtime file of a container asset. For example, an FBX file has .node and .mesh runtime files generated for it. You can access the generated .mesh file in the following way:您可以访问容器资产的每个运行时文件。例如，FBX文件具有为其生成的.node和.mesh运行时文件。您可以通过以下方式访问生成的.mesh文件：

  源代码 (C++)

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

You can also access any runtime or asset in your project using GUIDs. If a GUID of a file is specified, the exact path corresponding to this GUID is used:您还可以使用 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

For example, three localization languages are supported in the project: English (by default), German and French. Depending on the language, different splash textures should be loaded on the start-up.例如，项目中支持三种本地化语言：英语（默认），德语和法语。根据语言，应在启动时加载不同的启动纹理。

To organize your resources, name them using the following file modifiers:要组织资源，请使用以下文件修饰符对其进行命名：

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

After that, you need to specify in code which modifier to use via addModifier(). This function is called in the system script since a modifier needs to be registered before the world and its resources start to be loaded. For example, to load a German splash screen and the low resolution textures interface:之后，您需要在代码中通过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;
}

Also you can use -extern_define CLI option to pass the language (for example, if a user chooses a language in the launcher).

bin\main_x64d.exe -extern_define "LANG_DE"

bin\main_x64d.exe -extern_define "LANG_DE"

And here is how passed defines can be handled in the code.这是如何在代码中处理定义的传递。

// 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;
}