File System

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.

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.

If changes to the file system are made not by means of UnigineScript, you may need to call the filesystem_reload console command.

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.

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

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.

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:

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

{
    "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.

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

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.

The root_mount.umount file can be created manually or via code using API.

UNIGINE supports the following types of file archives to save space or pack the production version of resources:

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

  The maximum size for a file inside a UNG archive is limited to 2 GB.
• ZIP
• Custom C++ packages created via 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.

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.

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.

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.

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
3. Files in ZIP archives

From UNIGINE API, archives are handled using the FileSystem functions as well.

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.

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:

• Full virtual path - a path to a file inside the data folder
• 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:

external_images/1.tga

Partial#

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.

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.

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:

• For default resources, functions return full paths relative to the data folder.
• 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.

You can check whether a path is absolute or relative via the isAbsolute() function.

The file system also allows you to get a path to a file relative to the data folder by using the getVirtualPath() function.

The way of accessing a certain asset by path is determined by its type:

• Native assets are accessed simply by their name:
  Source code (C++)

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

• 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:
  Source code (C++)

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

  The image.texture 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:

  Source code (C++)

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

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

• 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:
  Source code (C++)

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

  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:

  Source code (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:

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.texture

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

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:

// 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"

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