Файловая система

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. Иногда в случае совместной разработки недопустимый файл guids.db может быть зафиксирован в репозитории (из-за неправильного слияния или иным образом), что приведет к ошибкам при работе с UnigineEditor . Вы можете заставить движок игнорировать файл guids.db с помощью параметра командной строки запуска -skip_guidsdb . В этом случае движок ищет идентификаторы GUID среди всех файлов .meta внутри папки data и всех смонтированных внешних каталогов и пакетов. 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(). Если вы добавляете новые файлы во время выполнения, движок ничего не будет знать о таких файлах (поскольку виртуальная файловая система была сформирована при запуске). Повторное сканирование файловой системы требует значительных ресурсов, поэтому вы можете добавлять новые файлы в виртуальную файловую систему через API с помощью addVirtualFile() .

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 является абсолютным, текущий рабочий каталог может отличаться от каталога с исполняемым двоичным файлом. Однако, когда путь к каталогу данных является относительным, Engine переключает текущий каталог на каталог с исполняемым двоичным файлом.

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: При доступе к файлу вне каталога data через API, путь к такому файлу должен быть указан относительно текущего каталога. Например:

// cbox.mesh is stored outside the data directory, so the path is specified relative to the current directory
ObjectMeshStaticPtr cbox = ObjectMeshStatic::create("../../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): При создании проекта файл root_mount.umount создается в папке data. Это файл в формате JSON, представляющий корневую точку монтирования. Он хранит версию UNIGINE SDK, в которой было создано корневое монтирование, и игнорирует фильтры (т.е. указание на папки , которые следует игнорировать):

{
	"ignore_filters": [
		".svn/",
		".git/",
		".teamcity/",
	]
}

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/).

Примечание

Folder filters must end with a slash symbol ("/").Фильтры для каталогов следует указывать со слешем ("/") в конце.

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) UNG (собственный формат UNIGINE для архивов, созданных с помощью инструмента Archiver)
• ZIPZIP
• Custom C++ packages created via UNIGINE API Пользовательские пакеты C ++ , созданные с помощью UNIGINE API

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. Архивы полностью прозрачны для Engine. Нет необходимости явно распаковывать архивы, поскольку их содержимое автоматически обрабатывается как незапакованное. К архивным файлам обращаются как к неархивированным. Например, если у вас есть 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 Файлы в in ZIP-архивах

From UNIGINE API, archives are handled using the FileSystem functions as well. Из UNIGINE API архивы также обрабатываются с помощью функций FileSystem.

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 строгая . Это означает, что виртуальная файловая система всегда проверяет точное местоположение файла, а не ищет где-нибудь внутри каталога 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: При указании виртуального пути к файлу внутри точки монтирования он всегда включает имя точки монтирования. Например, если у вас есть точка монтирования data/external_images.umount, которая относится к D:\external_content, вы должны получить доступ к любому файлу в этой папке следующим образом:

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. Пути в файлах пользовательского интерфейса .
• 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. Частичный путь может быть разрешен с помощью метода resolvePartialVirtualPath() класса FileSystem. Он преобразует данный частичный виртуальный путь в полный виртуальный, а затем его можно обрабатывать по мере необходимости.

Virtual Path Specified as Absolute

Виртуальный путь задан как абсолютный#