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

Иногда в случае совместной разработки недопустимый файл 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
ObjectMeshStatic cbox = new ObjectMeshStatic("../../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().

Способ доступа к определенному активу по пути определяется его типом:

• Собственные ресурсы доступны просто по их имени:
  Исходный код (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 (this is a default version of the texture. In our case, a texture with an English title)
    • splash.de.png (a German title)
    • splash.fr.png (a French title)

После этого нужно указать в коде, какой модификатор использовать через 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;
}