UnigineEditor
界面概述
资产工作流程
设置和首选项
项目开发
调整节点参数
Setting Up Materials
Setting Up Properties
照明
Landscape Tool
Sandworm (Experimental)
使用编辑器工具执行特定任务
Extending Editor Functionality
编程
基本原理
搭建开发环境
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine Tools
GUI
双精度坐标
应用程序接口
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes

文件系统

UNIGINE has its own file system module used to access files and folders. It has a few peculiarities you should be aware of, when loading resources or organizing the structure of your UNIGINE-based project. UNIGINE具有其自己的文件系统模块,该模块用于访问文件和文件夹。在加载资源或组织基于UNIGINE的项目的结构时,应该注意一些特殊之处。

GUIDs图形用户界面#

In UNIGINE's file system, each file has a GUID (Globally Unique Identifier), which defines a virtual path to this file (not a file on a disk). Using GUIDs provides more flexible file management: you can abstract from file names (which can be the same in different folders of the project). For example, you can change a path to the file while keeping the same GUID.在UNIGINE的文件系统中,每个文件都有一个 GUID (全局唯一标识符),该文件定义了此文件(不是磁盘上的文件)的虚拟路径。使用GUID提供了更灵活的文件管理:您可以从文件名中提取文件名(在项目的不同文件夹中可以相同)。例如,您可以在保留相同GUID的情况下更改文件的路径。

The Engine generates GUIDs for all files of the virtual file system.引擎为虚拟文件系统的所有文件生成GUID。

Files of UNIGINE's file system can be accessed by using both names or GUIDs: you can obtain a GUID for the specific file, change the file GUID, add/remove the file with the certain name or GUID to/from a blob or a cached file, and so on.可以使用名称GUID来访问UNIGINE文件系统的文件:您可以获取特定文件的GUID,更改文件GUID,以及添加文件 具有特定名称或GUID的Blob或缓存文件,依此类推或从中删除

注意
To manage GUIDs via API use the UGUID class.要通过API管理GUID,请使用 UGUID 类。

If UnigineEditor is loaded, it saves generated GUIDs to the data/guids.db file automatically. Otherwise, you can implement the logic of updating guids.db via code. The guids.db file stores a pair: a GUID of a file and a path to this file relative to the data folder.如果加载了UnigineEditor,它将自动将生成的GUID保存到data/guids.db文件。否则,您可以通过代码实现更新 guids.db的逻辑。 guids.db文件存储一对:文件的GUID和该文件相对于data文件夹的路径。

As UNIGINE's file system provides mount points to extend the project, there can be several guids.db files within a single project. Each mount point can store its own guids.db: GUIDs for external files aren't written to data/guids.db.由于UNIGINE的文件系统提供了 装载点 来扩展项目,因此单个项目中可以有多个guids.db文件。每个安装点都可以存储自己的guids.db:外部文件的GUID不会写入data/guids.db

Deleting the guids.db file won't cause any issues: if there is no guids.db file, the Engine will search among .meta files. However, guids.db might be necessary for the final release build of the project, if you aren't going to include the .meta files.删除guids.db文件不会引起任何问题:如果没有guids.db文件,引擎将在.meta文件中搜索。但是,如果您不打算包含.meta文件,则最终版本的项目可能需要使用guids.db

Ignore Option for guids.db忽略guids.db的选项#

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文件以确保其有效性。

File System Update文件系统更新#

Dynamic Scanning动态扫描#

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 控制台命令。

Automatic Resource Reloading自动资源重装#

When UnigineEditor is loaded, the Engine 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).但是,只有将文件添加到虚拟文件系统中时,才有可能(在启动时已执行动态扫描)。

When UnigineEditor is loaded, automatic tracking of changes isn't available for the mount points. Each mount point is updated manually on demand.加载UnigineEditor时,安装点无法自动跟踪更改。每个安装点均根据需要手动更新。

Known vs Unknown Files已知文件与未知文件#

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将新文件添加到虚拟文件系统。

Data Directory资料目录#

All files used by the Engine at run time are stored in the data folder specified via the -data_path start-up option. By default, this is the data folder created automatically on project creation via UNIGINE SDK Browser.引擎在运行时使用的所有文件都存储在通过 -data_path 启动选项指定的data文件夹中。默认情况下,这是通过UNIGINE SDK Browser创建项目时自动创建的data文件夹。

注意
The path to the data folder can be specified relatively to the binary executable or as an absolute path.可以相对于二进制可执行文件指定数据文件夹的路径,也可以将其指定为绝对路径。

When the file system resolves paths, it tries to concatenate data paths with the specified path and perform a lookup. In case of absolute paths, the file system will use them "as is" without any checks.文件系统解析路径时,它将尝试将数据路径与指定的路径连接起来并执行查找。对于绝对路径,文件系统将按原样使用它们,而无需进行任何检查。

注意
When the path to the data folder is relative, the engine switches the current folder to the folder with the binary executable.data文件夹的路径是相对路径时,引擎会将当前文件夹切换到具有二进制可执行文件的文件夹。

For example, if the project folder has the following structure:例如,如果项目文件夹具有以下结构:

  • unigine_project
    • assets
    • bin
    • data

The data path will be unigine_project/data after the application start-up:应用程序启动后,数据路径将为unigine_project/data

命令行
bin\main_x64d.exe -data_path "../"
注意
A path specified in the -data_path option won't be written into the configuration file. -data_path 选项中指定的路径不会写入配置文件。

Current Directory当前目录#

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目录之外的文件时,应相对于当前目录指定该文件的路径。例如:

源代码 (C++)
// 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");

Root Mount File根挂载文件#

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 通过代码创建。

File Packages文件包#

Types种类#

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.软件包不能存储另一个软件包。另外,不能打包安装点。但是,它可以引用程序包。

Content Access内容访问#

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函数处理存档。

Extending File System扩展文件系统#

The virtual file system can be easily extended by using the mount point feature. It allows you to extend the virtual file system of your project by adding any external folders and packages to the data directory.通过使用安装点功能可以轻松扩展虚拟文件系统。它允许您通过将任何外部文件夹和软件包添加到数据目录来扩展项目的虚拟文件系统。

Using the mount points in your project allows you to use content stored:使用项目中的挂载点可以使用存储的内容:

  • In a single folder or repository for several projects.在用于多个项目的单个文件夹或存储库中。
  • In several folders for one project. You can create as many mount points as required for the project.在一个项目的多个文件夹中。您可以根据项目需要创建任意数量的装载点。

A UNIGINE-based project has a single data directory. Here all project assets and runtime files are stored. In addition, the data folder can store mount points created via the Asset Browser (Create -> Create Mount Point) or API.基于UNIGINE的项目只有一个data目录。此处存储了所有项目资产和运行时文件。另外,data文件夹可以存储通过资源浏览器(Create -> Create Mount Point)或 API 创建的安装点。

A mount point is represented on the disk as a *.umount file: a file in the JSON format that stores a reference to an external directory or package as an absolute path or a path relative to the current directory. Also the *.umount file stores version of UNIGINE SDK, in which the mount has been created, and information on whether the mount is read-only or not. You can also specify exclusive_filters (whitelist) or ignore_filters (blacklist) as a list of wildcards (e.g., "*.jpg", "some_folder_*") to selectively add files of certain types or contents of folders with certain names, or on the contrary, to ignore the ones specified). For example:挂载点在磁盘上表示为*.umount文件:JSON格式的文件,用于存储对外部目录或程序包的引用作为绝对路径或相对于当前目录的路径。 *.umount文件还存储已在其中创建安装的UNIGINE SDK的版本,以及有关安装是否为只读的信息。您还可以将exclusive_filters(白名单)或ignore_filters(黑名单)指定为通配符列表(例如"*.jpg", "some_folder_*"),以有选择地添加某些类型的文件或具有某些名称的文件夹内容,或者相反地忽略指定的文件。例如:

输出
{
    "data_path": "D:/mount_test",
    "readonly": false,
	"ignore_filters": ["*.jpg","*.prop"],
    "version": "2.9.0.0"
}
注意
Use only forward slashes for paths (Unix convention) as backslashes in JSON files are used as escape characters.仅将正斜杠用作路径(Unix约定),因为JSON文件中的反斜杠用作转义字符。

All folders inside the mount point are treated by the file system as usual folders with assets inside the data directory.文件系统将挂载点内的所有文件夹视为具有资源在data目录内的常规文件夹。

Inside each mount point, there is a .runtimes folder that stores runtime files generated for assets of the external directory. Note that they aren’t added to the runtimes stored inside the data/.runtimes folder. If you move an asset from one mount point to another, its runtime will be moved as well.在每个安装点内部,都有一个.runtimes文件夹,用于存储为外部目录的资产生成的运行时文件。请注意,它们不会添加到data/.runtimes文件夹中存储的运行时中。如果将资产从一个挂载点移动到另一个挂载点,其运行时间也会随之移动。

As well as runtime files are stored per mount point, the guids.db file is also generated and stored per mount point by default: GUIDs for external files aren't written to data/guids.db.和运行时文件分别按安装点存储 一样,默认情况下,还将按安装点生成并存储guids.db文件:外部文件的GUID不会写入data/guids.db

If several team members work with a single mount point, it should be read-only to avoid issues.如果多个团队成员使用一个安装点,则应该为只读,以避免出现问题。

The read-only mount point doesn’t allow any changes in the folder or package it is referenced to. It means that such folder must store assets with already generated .meta files and runtimes. Otherwise, they won’t be available in the Asset Browser. The workflow here should be as follows: 只读安装点不允许对其引用的文件夹或软件包进行任何更改。这意味着该文件夹必须存储具有已生成的.meta文件和运行时的资产。否则,它们将不会在资源浏览器中提供。此处的工作流程应如下:

  1. The .meta and runtime files for assets are generated once and saved/committed to the folder/repository (if any).资产的.meta和运行时文件生成一次,然后保存/提交到文件夹/存储库(如果有)。
  2. In each project that uses the assets from this folder/repository, the read-only mount point is created. The assets are used "as is", without opportunity to somehow modify them.在使用该文件夹/存储库中资产的每个项目中,将创建只读安装点。资产按“原样”使用,没有机会以某种方式进行修改。
注意
All .meta files and runtimes in the mounted directory/package must be valid and up-to-date. All assets that were not properly migrated, as well as the ones having outdated .meta or runtime files will be unavailable and won't be displayed.挂载的目录/软件包中的所有.meta文件和运行时必须有效且最新。所有未正确迁移的资产以及过期的.meta或运行时文件将不可用,并且不会显示。

When working with mount points, there are rules to be followed:使用安装点时,需要遵循以下规则:

  • Mount points can be embedded: a folder referenced by a *.umount file can store another *.umount file, etc. However, looped mount points are not allowed: you cannot create the 2.umount inside the 1.umount that refers to 1.umount.可以嵌入挂载点:*.umount文件引用的文件夹可以存储另一个*.umount文件,依此类推。但是,不允许循环挂载点:您不能在引用1.umount1.umount内创建2.umount
  • *.umount files cannot be packed, as well as packages cannot store another packages. However, the *.umount file can refer to a package. *.umount文件无法打包,并且程序包无法存储其他程序包。但是,*.umount文件可以引用一个包。
  • *.umount file should have a unique name. If the data folder contains a folder with the same name as the mount point, this mount point will be ignored. *.umount文件应具有唯一的名称。如果data文件夹包含与挂载点名称相同的文件夹,则将忽略此挂载点。

When UnigineEditor is loaded, automatic resource reloading isn’t available for mount points. Each mount point is updated manually on demand: in the Asset Browser, right-click the mount point and choose Refresh Mount Point. When UnigineEditor isn't loaded, the Engine reloads all resources, including mount points, after reloading the world if resources are added to the virtual file system.加载UnigineEditor时,自动资源重新加载对安装点不可用。每个安装点均根据需要手动更新:在资源浏览器中,右键单击安装点,然后选择Refresh Mount Point。如果未将UnigineEditor加载到虚拟文件系统中,则在重新加载世界后,引擎将重新加载所有资源,包括安装点。

Paths路径#

The Engine accepts the relative, absolute, network, and virtual paths.引擎接受相对,绝对网络虚拟路径。

注意
UNIGINE's file system features path normalization: it automatically converts Windows paths to UNIX paths. UNIGINE的文件系统具有路径归一化功能:它将Windows路径自动转换为UNIX路径。

Virtual Paths虚拟路径#

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_contentdata/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:使用部分路径意味着文件系统执行非严格文件搜索。在这种情况下,只能提供没有路径的文件名。在用户可以手动输入路径的情况下,允许使用部分路径,例如:

注意
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虚拟路径被指定为绝对路径#

The Engine can resolve paths that are specified as absolute, but actually are virtual. It means that the path to a file can look like absolute, but physically there is no such file by this path.引擎可以解析指定为绝对路径,但实际上是虚拟路径。这意味着文件的路径看起来像是绝对路径,但实际上该路径没有该文件。

For example, there is a project stored in the D:/projects/unigine_project/ folder. In the data folder of this project, there is a test.umount that refers to a D:/content/test/ folder with the 1.tga texture. You can specify the path to this texture as absolute as follows and the Engine will be able to return a virtual path for it.例如,有一个项目存储在D:/projects/unigine_project/文件夹中。在该项目的数据文件夹中,有一个test.umount引用了具有1.tga纹理的D:/content/test/文件夹。您可以按如下所示将此纹理的路径指定为绝对路径,然后引擎将能够为其返回虚拟路径。

源代码 (C++)
getVirtualPath("D:/projects/unigine_project/test/1.tga"); // returned: test/1.tga

If you try to get an absolute path, the absolute path D:/content/test/1.tga will be returned.如果尝试获取绝对路径,则将返回绝对路径D:/content/test/1.tga

源代码 (C++)
getAbsolutePath("D:/projects/unigine_project/test/1.tga"); // returned D:/content/test/1.tga

To get more usage examples on the getVirtualPath() / getAbsolutePath() methods, check the article on the FileSystem class.要获取有关getVirtualPath() / getAbsolutePath()方法的更多用法示例,请查看有关FileSystem类的文章。

Network Paths网络路径#

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 disc space.您可以创建引用网络文件夹的安装点。它使您避免不必要地将资产复制到本地计算机,从而节省了磁盘空间。

Relative vs Absolute相对vs绝对#

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文件夹的文件路径。

Loading Priorities加载优先级#

The Engine resolves any path as follows:引擎按以下方式解析任何路径:

  1. It tries to convert the path to a full virtual one.尝试将路径转换为完整的虚拟路径。
  2. It tries to get the current mount point by this path.尝试通过此路径获取当前安装点。

By using the obtained information on the path, the Engine can get a real path to the file on the disk (or blob/package/cache).使用获得的路径信息,引擎可以获取磁盘(或blob / package / cache)上文件的真实路径。

A virtual path can represent up to four entities at the same time: it can be a file on the disk, a file stored in a package, a file added to a cache and to a blob.虚拟路径最多可以同时表示四个实体:它可以是磁盘上的文件,存储在 package 中的文件,添加到 cache 并链接到 blob

注意
A GUID is generated for a virtual path: neither a file on the disk, a package file, a cached or a blobbed file can have a GUID.为虚拟路径生成 GUID :磁盘上的文件,程序包文件,缓存文件或blobled文件都不能具有GUID。

For example, the textures/white.dds path has only one GUID, however, it can represent the following at the same time:例如,textures/white.dds路径只有一个GUID,但是它可以同时表示以下内容:

  • Within the project folder, you can have both core/textures/white.dds and core.ung/textures/white.dds.在项目文件夹中,您可以同时拥有core/textures/white.ddscore.ung/textures/white.dds
  • In addition, in code, you can have both:
    源代码 (C++)
    // the file loaded into a cache
    FileSystem::addCacheFile("core/textures/white.dds");
    // the file loaded into a blob
    FileSystem::addBlobFile("core/textures/white.dds");
    此外,在代码中,您可以同时拥有:
    源代码 (C++)
    // the file loaded into a cache
    FileSystem::addCacheFile("core/textures/white.dds");
    // the file loaded into a blob
    FileSystem::addBlobFile("core/textures/white.dds");
注意
You can check whether a virtual path or a GUID represents a certain entity via the corresponding API methods.您可以通过相应的API方法检查虚拟路径或GUID是否表示某个实体。

During read / write operations, the Engine will load the first found entity for such virtual path. The entities are checked in the following order:读/写操作期间,引擎将为该虚拟路径加载第一个找到的实体。按照以下顺序检查实体:

  • For read operations:
    1. The file loaded into a blob.The file loaded into a blob.
    2. The file added into a cache.The file added into a cache.
    3. The read-only file stored on the disk.The read-only file stored on the disk.
    4. The file stored in a package.The file stored in a package.
    The file loaded into a blob.The file added into a cache.The read-only file stored on the disk.The file stored in a package.
    对于读取操作:
    1. The file loaded into a blob.加载到Blob中的文件。
    2. The file added into a cache.已将文件添加到缓存中。
    3. The read-only file stored on the disk.存储在磁盘上的只读文件。
    4. The file stored in a package.文件存储在包中。
  • For write operations:
    1. The file loaded into a blob.The file loaded into a blob.
    2. The file stored on the disk.The file stored on the disk.
    注意
    Cached and packed files aren't checked as write operations aren't allowed for them.Cached and packed files aren't checked as write operations aren't allowed for them.
    The file loaded into a blob.The file stored on the disk.Cached and packed files aren't checked as write operations aren't allowed for them.
    对于写入操作:
    1. The file loaded into a blob.加载到Blob中的文件。
    2. The file stored on the disk.存储在磁盘上的文件。
    注意
    Cached and packed files aren't checked as write operations aren't allowed for them.不允许检查缓存和打包的文件,因为不允许对其执行 write 操作。

Accessing Assets and Runtime Files访问资产和运行时文件#

Working with assets via UnigineEditor is clear and simple, but in order to access your project files properly you should have a clear understanding of the concept of asset and runtime files.通过UnigineEditor处理资产非常简单明了,但是要正确访问项目文件,您应该对资产和运行时文件的概念有清楚的了解。

Generated runtime files have constant GUIDs and are named as follows:
<GUID>.<extension> (e.g., ab23be4cd7832478edaaab23be4cd7832478edaa.dds).
生成的运行时文件具有恒定的GUID,其名称如下:
<GUID>.<extension>(例如ab23be4cd7832478edaaab23be4cd7832478edaa.dds)。

These files are stored in sub-folders of the data/.runtimes folder. The structure or this folder is optimized for the file system.这些文件存储在 data/.runtimes 文件夹的子文件夹中。结构或此文件夹针对文件系统进行了优化。

注意
Inside each mount point, there is also a .runtimes folder that stores runtime files generated for assets of the external directory. These runtimes aren’t added to the runtimes stored inside the data/.runtimes folder. If you move an asset from one mount point to another, its runtime will be moved as well.每个装载点内,还有一个.runtimes文件夹,用于存储为外部目录的资产生成的运行时文件。这些运行时不会添加到data/.runtimes文件夹中存储的运行时中。如果将资产从一个挂载点移动到另一个挂载点,其运行时间也会随之移动。

A runtime file generated for a non-native asset with a certain GUID is placed in a folder that has a name equal to the first two bytes of this GUID.为具有特定 GUID 的非本地资产生成的运行时文件放置在一个名称等于该GUID的前两个字节的文件夹中。

注意
A sub-folder of the data/.runtimes folder may contain runtime files generated for different assets (if these assets have matching first two bytes in their GUIDs). data/.runtimes文件夹的子文件夹可能包含为不同资产生成的运行时文件(如果这些资产在其GUID中具有匹配的前两个字节)。

E.g., your non-native asset data/my_textures/1.tga will have runtime file (with a name corresponding to runtime's GUID) generated for it in a folder: ./runtimes/ae/aeb53b44cdbbbbbbbbaaabccc1c1c1c1c1c1c1c1.dds例如,您的非本地资产data/my_textures/1.tga将在文件夹./runtimes/ae/aeb53b44cdbbbbbbbbaaabccc1c1c1c1c1c1c1c1.dds中为其生成运行时文件(名称与运行时的GUID相对应)

Therefore each runtime file has an alias - a human-readable form of a path used to refer to this file. 因此,每个运行时文件都有一个 alias (别名)-用于引用该文件的路径的可读形式。

Full aliases are constructed as follows: <source_asset_path>/<runtime_alias>完整别名的构造如下:<source_asset_path>/<runtime_alias>

E.g.:

  • 1.tga/1.dds
  • 1.fbx/material/1.mat
例如:

  • 1.tga/1.dds
  • 1.fbx/material/1.mat

In order to simplify access to runtime files, we also use a concept of the primary runtime - a runtime file uniquely assoсiated with the asset. It acts like an implied reference to a runtime file: when we say "model.fbx", we actually mean "model.node". So, that we could write: 为了简化对运行时文件的访问,我们还使用了主要运行时的概念-与资产唯一关联的运行时文件。它就像对运行时文件的隐式引用:当我们说“ model.fbx”时,实际上是指“ model.node” 。因此,我们可以这样写:

源代码 (C++)
NodeReferencePtr node = NodeReference::create("model.fbx");
注意
Primary runtime is actually used instead of a non-native asset, when you refer to it by path.当您通过路径引用它时,实际上使用的是主要运行时环境,而不是非本地资源。

There are two ways you can access your assets and runtime files:您可以通过两种方式访问​​资产和运行时文件:

The file system includes a subsystem for managing assets and runtime files. This subsystem is implemented as a separate class named FileSystemAssets.文件系统包括一个用于管理资产和运行时文件的子系统。该子系统被实现为一个单独的类,名为FileSystemAssets

You can use assets_info and assets_list console commands to view information on non-native assets and runtimes generated for them.可以使用assets_infoassets_list控制台命令来查看有关非本地资产和为其生成的运行时的信息。

Accessing by Path按路径访问#

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");

Accessing by GUID通过GUID访问#

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对应的确切路径:

源代码 (C++)
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

Modifiers修饰符#

File modifiers serve to automatically choose which resources to load when a UNIGINE project is run on different platforms or with different localizations. Instead of keeping multiple versions of the same project and copying shared data between them, you can add a custom postfix to file or folder names, and load only required resources on demand.文件修改器用于在UNIGINE项目在不同平台或具有不同本地化版本上运行时自动选择要加载的资源。您可以在文件或文件夹名称中添加自定义后缀,然后仅按需加载所需的资源,而不必保留同一项目的多个版本并在它们之间复制共享数据。

警告
This feature is run-time only, and is not supported by UnigineEditor.此功能仅在运行时,UnigineEditor不支持。

Modifiers are added to file or folder names as a postfix (only one can be specified). Any custom postfix can be used. For example, it could be:修饰符作为后缀添加到文件或文件夹名称中(只能指定一个)。可以使用任何自定义的后缀。例如,它可能是:

  • File name modifier: file.small.node or texture.eng.dds 文件名修饰符:file.small.nodetexture.eng.dds
  • Folder name modifier: textures.lowres
    注意
    If a folder has a modifier, files inside it should not have their own modifiers. Otherwise, file modifiers will be ignored.If a folder has a modifier, files inside it should not have their own modifiers. Otherwise, file modifiers will be ignored.
    If a folder has a modifier, files inside it should not have their own modifiers. Otherwise, file modifiers will be ignored.
    文件夹名称修饰符:textures.lowres
    注意
    If a folder has a modifier, files inside it should not have their own modifiers. Otherwise, file modifiers will be ignored.如果文件夹具有修饰符,则其中的文件不应具有自己的修饰符。否则,文件修饰符将被忽略。

Register necessary modifiers in code via addModifier(). When the project is running, resources with the registered modifiers are loaded automatically. Files without modifiers have the lowest priority (can be used for default resources).通过 addModifier() 在代码中注册必要的修饰符。当项目运行时,带有已注册修饰符的资源会自动加载。没有修饰符的文件具有最低优先级(可以用于默认资源)。

Usage Example使用范例#

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()指定要使用的修饰符。在系统脚本中调用此函数,因为需要在世界及其资源开始加载之前注册修饰符。例如,要加载德国初始屏幕和低分辨率纹理界面:

源代码 (UnigineScript)
// 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"
您也可以使用-extern_define CLI选项传递语言(例如,如果用户在启动器中选择一种语言)。

命令行
bin\main_x64d.exe -extern_define "LANG_DE"

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

源代码 (UnigineScript)
// 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;
}

Asynchronous Loading异步加载#

UNIGINE Engine allows you to control asynchronous loading of files by means of the AsyncQueue class. All file-related methods of this class will load a file and add it to the file system as a cached one. UNIGINE Engine允许您通过AsyncQueue类控制文件的异步加载。此类的所有与文件有关的方法都将加载文件,并将其作为缓存的文件添加到文件系统中。

最新更新: 2020-11-11