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

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

Динамическое сканирование позволяет движку формировать виртуальную файловую систему для всех файлов в папке data (включая те, которые находятся внутри точек монтирования ). Динамическое сканирование выполняется при запуске двигателя. Для файлов, физически хранящихся в папке data, отслеживание изменений файлов включено в реальном времени с использованием относительных путей для адресации файлов.

Если изменения в файловой системе вносятся не с помощью UnigineScript, вам может потребоваться вызвать консольную команду filesystem_reload .

Когда UnigineEditor загружен, он отслеживает изменения, внесенные в файлы во время выполнения: он проверяет время последней модификации таких файлов и обновляет их в памяти. Если UnigineEditor не загружен, измененные файлы перезагружаются после перезагрузки мира .

Примечание

Однако это возможно, только если файлы добавлены в виртуальную файловую систему (при запуске было выполнено динамическое сканирование).

Если вы добавляете новые файлы во время выполнения, движок ничего не будет знать о таких файлах (поскольку виртуальная файловая система была сформирована при запуске). Повторное сканирование файловой системы требует значительных ресурсов, поэтому вы можете добавлять новые файлы в виртуальную файловую систему через API с помощью addVirtualFile() .

Если указанный -data_path является абсолютным, текущий рабочий каталог может отличаться от каталога с исполняемым двоичным файлом. Однако, когда путь к каталогу данных является относительным, Engine переключает текущий каталог на каталог с исполняемым двоичным файлом.

При доступе к файлу вне каталога 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");

Строительным блоком виртуальной файловой системы является монтирование : файловая система создается как корневое монтирование и может быть легко расширена с помощью дополнительных точек монтирования . Этот подход позволяет расширить виртуальную файловую систему вашего проекта, добавляя любые внешние папки и пакеты в каталог данных.

При создании проекта файл root_mount.umount создается в папке data. Это файл в формате 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
• Пользовательские пакеты C ++ , созданные с помощью UNIGINE API

Помимо экономии места, архивы также ускоряют загрузку ресурсов, поскольку файлы в архиве читаются линейно.

Архивы UNG и ZIP загружаются автоматически, если они находятся в папке data. Файлы добавляются в виртуальную файловую систему так же, как и неархивированные файлы.

Примечание

Пакет не может хранить другой пакет. Также нельзя упаковать точку монтирования . Однако он может относиться к пакету.

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

Из UNIGINE API архивы также обрабатываются с помощью функций FileSystem.

Файловая система UNIGINE строгая . Это означает, что виртуальная файловая система всегда проверяет точное местоположение файла, а не ищет где-нибудь внутри каталога data. Такой подход делает работу с файлами проекта понятной и прозрачной.

Виртуальная файловая система работает с виртуальными путями к файлам. Виртуальный путь - это путь к файлу внутри папки data (включая файлы в точках монтирования ). Движок всегда пытается преобразовать любой путь в виртуальный. Есть несколько типов виртуальных путей:

• Полный виртуальный путь - путь к файлу внутри папки data
• Частичный виртуальный путь
• Виртуальный путь указан как абсолютный один

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

external_images/1.tga

Частичные пути#

Использование частичных путей означает, что файловая система выполняет нестрогий поиск файлов. В этом случае можно указать только имя файла без пути. Частичные пути разрешены в случаях, когда пользователь может ввести путь вручную, например:

• Мировые операции по загрузке. Вы можете указать только имя мира, и оно будет найдено и загружено.
• Включение путей в исходный код.
• Пути в файлах пользовательского интерфейса .
• Пути в файлах материалов руководства .
• Пути к текстурам в файлах базового материала .
• Пути к файлам шрифтов.

Примечание

Если имя не уникальное, загружается первый найденный файл с таким именем.

Также можно указать вложенный путь, который однозначно определяет файл. Например, чтобы загрузить data/project/my_world/my_world.world, вы можете использовать my_world.world (если имя уникальное) или my_world/my_world.world.

Также вы можете ссылаться на файлы по GUID , чтобы однозначно указать файл.

Примечание

Частичный путь может быть разрешен с помощью метода resolvePartialVirtualPath() класса FileSystem. Он преобразует данный частичный виртуальный путь в полный виртуальный, а затем его можно обрабатывать по мере необходимости.

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

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

Файловая система также позволяет вам получить путь к файлу относительно папки data с помощью функции getVirtualPath().