File System

Dynamic scanning allows the Engine to form a virtual file system for all files within the data folder. Dynamic scanning is performed on the Engine start-up. It enables tracking file changes in real-time and using partial and relative paths to address files.

If the dynamic scanning is not necessary or takes too many resources, you can use the pre-cached file hierarchy that is specified in the .ulist file. When the Engine finds this file in a folder during the start-up scanning, it stops and uses the list of files specified there to form the virtual file system.

The .ulist file is generated by using the special script <UnigineSDK>/utils/datalist.py that should be run from the data folder.

When the 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 the UnigineEditor isn't loaded, the changed files will be 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, so, in this case, you can add new files to the virtual file system via API by using addKnownFile().

When the first 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 (which is also not specified in an additional -data_path) 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
ObjectMeshStatic cbox = new ObjectMeshStatic("../../data/cbox.mesh");

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

UNG and ZIP archives are loaded automatically if they are found within the data folder. Files are added to the virtual file system just like in case with 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 or even file.txt (only if the file name is unique).

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

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

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. Unarchived files
2. Files in UNG archives
3. Files in ZIP archives

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

For the last variant, use the additional -data_path command-line options as follows:

-data_path "../" -data_path "D:/resources/my_project/test_0/" -data_path "../../resources/my_project/test_1/"

Paths can be both relative to the binary executable or absolute.

The list of all data paths specified on the application start-up can be obtained via API by using the following methods:

• getNumDataPaths()
• getDataPath()

The getDataPath() function without arguments will return the first specified-data_path directory.

*.ulink files can be used to add a folder (together with all its sub-folders and archives, if any) from outside the data directory to the virtual file system.

In such files, a path to the directory is stored. A link file can be stored anywhere inside data. On the start-up or when filesystem_reload is called to update the list of resources, the engine scans through files, finds a link file and adds a linked directory as if its root is a data folder.

Paths inside *.ulink files can be relative or absolute.

• Relative to the data directory:
  Source code

  ../../my_project/resources/

• An absolute path can be specified.
  For example, on Windows:
  Source code

  D:\resources\

  On Linux:
  Source code

  /username/resources/

It is possible to add archives to the virtual file system even if they are stored outside the data folder. External packages are added only on the start-up. Use one of the following methods for that:

• Add archives on the start-up via -extern_package CLI option (together with the rest of required ones). Relative and absolute paths can be used.
  Shell commands

  bin\main_x86d.exe -extern_package "../../my_project/archive.ung"

  Several packages:
  Shell commands

  bin\main_x64d.exe -extern_package "../2/core.ung" -extern_package "D:/Unigine/core.ung"

• Using UNIGINE API, via loadPackage() function.

As well as the data paths, the paths to external packages won't be saved into the configuration file. However, they can be added to it manually.

Partial paths simplify handling of files. If you want to load a file and you are sure that there is only one resource with the given name in the data folder, only a file name can be provided without a path.

Also you can refer files by GUIDs or use the strict flag to uniquely specify a file.

Sometimes, it is required to know whether the file with the specified name exists in the exact directory, not just somewhere inside the data. Setting the strict flag allows you to tell the file system to check the exact file location (i.e., the partial path won't be resolved if the strict flag is set).

This flag is used in most of the FileSystem methods.

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.

As file names are added to the virtual file system, usually the same name and path should be used to load and remove 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 the path is absolute or relative via the isAbsolute() function.

Also the file system allows you to get a path to a file relative to the data folder by using the getRelativeFileName() 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.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:

  Source code (C++)

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

  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:

  Source code (C++)

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

  In this case, the runtime .dds 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. In case if a GUID of a file is specified, the exact path corresponging to this GUID will be 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.dds

For example, three localization languages are supported in the project: English (by default), German and French. Depending on the language, different splash textures need to be loaded on the start-up.

To organize your resources, name them using the following file modifiers:

• data
  • splashes
    • splash.png (this would be 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, in the code you need to specify what modifier to use via engine.filesystem.addModifier(). This function is called in the system script (unigine.cpp) since a modifier need 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;
}