Unigine.FileSystem Class

On the Engine file system initialization, all files and packages stored in the data folder are added to the virtual file system automatically. At that, content of the ZIP and UNG packages is loaded into RAM as is (so, you'd better not store heavy content (e.g. terrains) in the packages).

Files and packages stored outside the data directory are also added to the virtual file system, if they are mounted (i.e. referenced by a mount point).

Notice

If you add new files at run time, the Engine won't know anything about such files. To add the files to the virtual file system, use addVirtualFile().

File System functions:

Provide control over asynchronous loading of files/meshes/images/nodes on demand under the data directory, including files in ZIP and UNG packages. Such packages are automatically handled by the Engine and all their files are automatically added to the file system.
Allow adding directories (even with ZIP and UNG packages) that are outside the data directory and provide control over loading such files.
Allow adding ZIP and UNG packages that are outside the data directory. After that, files in such packages are accessed in a usual way, by specifying a path to the file only inside the package.
Allow caching files in the memory and adding files to blobs if they are accessed or modified multiple times at run time.

Also methods of the FileSystem class can be used when implementing your own importer from an external format to UNIGINE-native ones. For example, you can store only the original file on the disk, files in UNIGINE-native formats can be stored in the virtual file system only.

Notice
					This class is in the Unigine namespace.
This class is a singleton.

				

Properties:

Name	Description
int NumModifiers	The total number of file modifiers registered in the file system.

Methods:

Name	Description View: Sort by:
IsBlobFile	Checks if the given file is loaded to a blob.
IsCacheFile	Checks if the given file is loaded into cache.
IsFileExist	Checks if the given file actually exists on the disk.
GetMTime	Returns the time of the last modification of the given file.
AddBlobFile	Adds a file into a blob.
AddCacheFile	Caches a file in the memory.
LoadPackage	Loads an UNG or ZIP package into the file system.
RemoveBlobFile	Removes a file from the blob.
RemoveCacheFile	Removes a cached file from the memory.
GetModifier	Returns the name of the given modifier.
AddModifier	Registers a new modifier in the file system.
RemoveModifier	Unregisters a given modifier in the file system.
ClearModifiers	Unregister all modifiers in the file system.
RemovePackage	Unloads an UNG or ZIP package from the file system.
IsAssetPath	Returns a value indicating if the given path has a valid asset path format.
GenerateGUID	Generates a new GUID.
SetGUID	Sets the specified GUID for the given file.
GetGUID	Returns the GUID (if it exists) for the given file.
IsGUIDPath	Returns a value indicating if the given path has a valid GUID path format.
SaveGUIDs	Saves all file system GUIDs to the specified file in the specified format (json or binary).
LoadGUIDs	Loads file system GUIDs from the specified file.
ClearExternPackages	Removes all external packages from the file system.
GetExtension	Returns the extension for the given file.
GetMount	Returns a mount point for the specified path.
SaveMountFile	Saves the specified *.
GetMount	Returns a mount point for the specified GUID.
GetMounts	Returns a list of all mount points currently used by the file system and puts the to the specified output buffer.
GetRootMount	Returns the root mount of the file system.
CreateMount	Adds a new mount point for the specified external folder/package, virtual path and access mode.
AddMount	Adds a new mount point using the data from the specified *.umount file.
RemoveMount	Unmounts a mount point with a given path.
ClearMounts	Unmounts all mount points.
GetPackageVirtualFiles	Saves the list of names for all virtual files stored in the specified package to the specified string buffer.
GetVirtualFiles	Saves the list of names for all known files registered in the file system to the specified string buffer.
IsVirtualFile	Checks if the given file is known to the virtual file system.
AddVirtualFile	Registers the regular file name as known virtual file with the given GUID and appends it to the map used for fast searching.
RenameVirtualFile	Renames the specified known virtual file.
RemoveVirtualFile	Removes the virtual file with the given name.
ChangeVirtualFile	Marks the virtual file with the given name as modified.
RemoveNonExistingVirtualFiles	Removes all non-existing virtual files from the File System.
IsDiskFile	Returns a value indicating if the specified file path is a path to a file on disk (i.e. not a package, a blob, or a cache file).
IsPackageFile	Returns a value indicating if the specified file path is a path to a file inside a ZIP or UNG package.
ResolvePartialVirtualPath	Converts the given partial path to a full virtual one.
GetVirtualPath	Resolves a virtual path for the given file path.
GetAbsolutePath	Resolves an absolute path for the given file path.
addExternPackage	Adds a custom package to the virtual file system.
preloadExternPackage	Loads the custom package before the file system initialization.
clearPreloadedExternPackages	Clears all preloaded custom packages (packages loaded before the file system initialization).

FileSystem Class

Properties

int NumModifiers#

The total number of file modifiers registered in the file system.

Members

bool IsBlobFile ( string path ) #

Checks if the given file is loaded to a blob.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is loaded to a blob successfully; otherwise, false.

bool IsBlobFile ( UGUID guid ) #

Checks if a file with the given GUID is loaded to a blob.

Arguments

UGUID guid - File GUID.

Return value

true if the file is loaded to a blob successfully; otherwise, false.

bool IsCacheFile ( string path ) #

Checks if the given file is loaded into cache.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is added into cache; otherwise, false.

bool IsCacheFile ( UGUID guid ) #

Checks if a file with the given GUID is loaded into cache.

Arguments

UGUID guid - File GUID.

Return value

true if the file is added into cache; otherwise, false.

bool IsFileExist ( string path ) #

Checks if the given file actually exists on the disk.

NoticeCalling this method every frame in the main thread, especially for multiple files, may cause a performance hit. It is better to optimize such checks and move them to a separate thread.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file exists; otherwise, false.

bool IsFileExist ( UGUID guid ) #

Checks if a file with the given GUID actually exists.

NoticeCalling this method every frame in the main thread, especially for multiple files, may cause a performance hit. It is better to optimize such checks and move them to a separate thread.

Arguments

UGUID guid - File GUID.

Return value

true if the file exists; otherwise, false.

long GetMTime ( string path ) #

Returns the time of the last modification of the given file.

NoticeCalling this method every frame in the main thread, especially for multiple files, may cause a performance hit. It is better to optimize such checks and move them to a separate thread.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

Time of the last file modification. If there is no such file, -1 will be returned.

long GetMTime ( UGUID guid ) #

Returns the time of the last modification of the file with the specified GUID.

NoticeCalling this method every frame in the main thread, especially for multiple files, may cause a performance hit. It is better to optimize such checks and move them to a separate thread.

Arguments

UGUID guid - File GUID.

Return value

Time of the last file modification. If there is no such file, -1 will be returned.

bool AddBlobFile ( string path ) #

Adds a file into a blob. It can be used for files that are frequently modified at run time (for example, images). After such file is loaded from a disk and written into a blob in the memory, its modifications can be saved fast into this blob.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is successfully added into a blob; otherwise, false.

bool AddBlobFile ( UGUID guid ) #

Adds a file with the given GUID into a blob. It can be used for files that are frequently modified at run time (for example, images). After such file is loaded from a disk and written into a blob in the memory, its modifications can be saved fast into this blob.

Arguments

UGUID guid - File GUID.

Return value

true if the file is successfully added into a blob; otherwise, false.

bool AddCacheFile ( string path ) #

Caches a file in the memory. It can be used for files that are accessed multiple times at run time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is successfully added to cache; otherwise, false.

bool AddCacheFile ( UGUID guid ) #

Caches a file in the memory with the given GUID. It can be used for files that are accessed multiple times at run time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading.

Arguments

UGUID guid - File GUID.

Return value

true if the file is successfully added to cache; otherwise, false.

bool LoadPackage ( string path ) #

Loads an UNG or ZIP package into the file system. Note that the package should be mounted, otherwise it won't be loaded.

NoticeUNG packages without password protection can be loaded even if the engine has built-in password for the file system packages. For example, it is possible to load both the core.ung package without a password and the my_assets.ung package protected with a password.

Arguments

string path - Package path. It can be a relative, absolute, network, or virtual path.

Return value

true if the package is loaded; otherwise, false.

bool LoadPackage ( string path, string extension ) #

Loads a package with the specified extension (ung, zip, or pak) into the file system. Note that the package should be mounted, otherwise it won't be loaded.

NoticeUNG packages without password protection can be loaded even if the engine has built-in password for the file system packages. For example, it is possible to load both the core.ung package without a password and the my_assets.ung package protected with a password.

Arguments

string path - Package path. It can be a relative, absolute, network, or virtual path.
string extension - Extension of a custom package, one of the following values:
- ung
- zip
- pak

Return value

true if the package is loaded; otherwise, false.

bool RemoveBlobFile ( string path ) #

Removes a file from the blob. Blobbing can be used for files that are frequently modified at run time (for example, images). After such file is loaded from a disk and written into a blob in the memory, its modifications can be saved fast into this blob.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is removed successfully; otherwise, false.

bool RemoveBlobFile ( UGUID guid ) #

Removes a file with the given GUID from the blob. Blobbing can be used for files that are frequently modified at run time (for example, images). After such file is loaded from a disk and written into a blob in the memory, its modifications can be saved fast into this blob.

Arguments

UGUID guid - File GUID.

Return value

true if the file is removed successfully; otherwise, false.

bool RemoveCacheFile ( string path ) #

Removes a cached file from the memory. Caching can be used for files that are accessed multiple times at run time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is successfully removed from cache; otherwise, false.

bool RemoveCacheFile ( UGUID guid ) #

Removes a cached file with the given GUID from the memory. Caching can be used for files that are accessed multiple times at run time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading.

Arguments

UGUID guid - File GUID.

Return value

true if the file is successfully removed from cache; otherwise, false.

string GetModifier ( int num ) #

Returns the name of the given modifier.

Arguments

int num - ID number of the modifier.

Return value

Modifier name.

void AddModifier ( string name ) #

Registers a new modifier in the file system.

Arguments

string name - Modifier name.

void RemoveModifier ( string name ) #

Unregisters a given modifier in the file system.

Arguments

string name - Modifier name.

void ClearModifiers ( ) #

Unregister all modifiers in the file system.

bool RemovePackage ( string path ) #

Unloads an UNG or ZIP package from the file system.

Arguments

string path - Package path. It can be a relative, absolute, network, or virtual path.

Return value

true if the package is removed; otherwise, false.

bool IsAssetPath ( string path ) #

Returns a value indicating if the given path has a valid asset path format (e.g. asset://1.tga).

Arguments

string path - Path to be checked.

Return value

true if the given path has a valid asset path format; otherwise, false.

UGUID GenerateGUID ( ) #

Generates a new GUID.

Return value

New filesystem GUID if is was generated successfully; otherwise, an empty GUID.

bool SetGUID ( string path, UGUID guid ) #

Sets the specified GUID for the given file.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.
UGUID guid - GUID to be set for the file.

Return value

true if the GUID is set successfully; otherwise, false.

UGUID GetGUID ( string path ) #

Returns the GUID (if it exists) for the given file.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

File GUID if it exists; otherwise, an empty GUID.

bool IsGUIDPath ( string path ) #

Returns a value indicating if the given path has a valid GUID path format (e.g. "guid://e231e15beff2309b8f87c30b2c105cc4d2399973)".

Arguments

string path - Path to be checked.

Return value

true if the given path has a valid GUID path format; otherwise, false.

bool SaveGUIDs ( string path, bool binary = false ) #

Saves all file system GUIDs to the specified file in the specified format (json or binary).

Arguments

string path - Path to the file, where file system GUIDs are to be stored.
bool binary - Binary file format flag. When the flag is set to true, the file system will save GUIDs to a binary file; otherwise, to a JSON file.

Return value

true if all file system GUIDs are saved successfully; otherwise, false.

bool LoadGUIDs ( string path ) #

Loads file system GUIDs from the specified file.

Arguments

string path - Path to the file, where file system GUIDs are stored.

Return value

true if file system GUIDs are loaded successfully; otherwise, false.

void ClearExternPackages ( ) #

Removes all external packages from the file system.

string GetExtension ( string path ) #

Returns the extension for the given file.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

File extension in lower case, if any; otherwise, an empty string.

string GetExtension ( UGUID guid ) #

Returns the extension for a file with the specified GUID.

Arguments

UGUID guid - GUID of the file for which extension is to be returned.

Return value

File extension in lower case if any; otherwise, an empty string.

FileSystemMount GetMount ( string path ) #

Returns a mount point for the specified path.

Notice

This method will return the root mount for all files located directly in the data folder or its subfolders.

Arguments

string path - File path, for which a mount point is to be found. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

FileSystemMount class instance on success; otherwise, nullptr.

bool SaveMountFile ( string umount_path ) #

Saves the specified *.umount file.

Arguments

string umount_path - Mount point file path.

Return value

true if the specified *.umount file is saved successfully; otherwise, false.

FileSystemMount GetMount ( UGUID guid ) #

Returns a mount point for the specified GUID.

Notice

This method will return the root mount for all files located directly in the data folder or its subfolders.

Arguments

UGUID guid - File GUID for which a mount point is to be found.

Return value

FileSystemMount class instance on success; otherwise, nullptr.

void GetMounts ( FileSystemMount[] container ) #

Returns a list of all mount points currently used by the file system and puts the to the specified output buffer.

Notice

This list will not include the root mount.

Arguments

FileSystemMount[] container - Output buffer to store the list of all currently used mount points.

FileSystemMount GetRootMount ( ) #

Returns the root mount of the file system. It mounts the data folder to the root of the virtual file system. The root mount cannot be unmounted.

Return value

FileSystemMount class instance for the root mount of the virtual file system.

FileSystemMount CreateMount ( string absolute_path, string virtual_path, int access ) #

Adds a new mount point for the specified external folder/package, virtual path and access mode. All mounted files are automatically added as known to the virtual file system.

Arguments

string absolute_path - Absolute path to the mounted folder/package.
string virtual_path - Virtual path to the folder to which the contents of the external folder/package is to be mounted.
int access - Mount point access mode, one of the FileSystemMount.ACCESS_* values.

Return value

FileSystemMount class instance, if it was created successfully; otherwise, nullptr.

FileSystemMount AddMount ( string umount_path ) #

Adds a new mount point using the data from the specified *.umount file. All mounted files are automatically added as known to the virtual file system.

Arguments

string umount_path - Absolute path to a *.umount file.

Return value

FileSystemMount class instance, if it was created successfully; otherwise, nullptr.

bool RemoveMount ( string path ) #

Unmounts a mount point with a given path.

Notice

The root mount cannot be removed.

Arguments

string path - Absolute path to the mounted folder/package.

Return value

true if the mount point with a given path is successfully unmounted; otherwise, false.

void ClearMounts ( ) #

Unmounts all mount points.

Notice

This method does not remove the root mount.

void GetPackageVirtualFiles ( string path, string[] files ) #

Saves the list of names for all virtual files stored in the specified package to the specified string buffer.

Arguments

string path - Path to a custom package. It can be a relative, absolute, network, or virtual path.
string[] files - String buffer to store the list of names for all virtual files stored in the specified package.

void GetPackageVirtualFiles ( string path, string extension, string[] files ) #

Saves the list of names for all virtual files stored in a package with the specified name and extension to the specified string buffer.

Arguments

string path - Path to a custom package. It can be a relative, absolute, network, or virtual path.
string extension - Extension of a custom package, one of the following values:
- ung
- zip
- pak
string[] files - String buffer to store the list of names for all virtual files stored in the specified package.

void GetVirtualFiles ( string[] files ) #

Saves the list of names for all known files registered in the file system to the specified string buffer.

Arguments

string[] files - String buffer to store the list of names for all known virtual files.

bool IsVirtualFile ( string path ) #

Checks if the given file is known to the virtual file system.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.

Return value

true if the file is known to the virtual file system; otherwise, false.

bool IsVirtualFile ( UGUID guid ) #

Checks if a file with the given GUID is known to the virtual file system and has a virtual path registered.

Arguments

UGUID guid - File GUID.

Return value

true if the file is known to the virtual file system; otherwise, false.

bool AddVirtualFile ( string path, UGUID guid, bool must_exist = false ) #

Registers the regular file name as known virtual file with the given GUID and appends it to the map used for fast searching. This method should be used when you need to add, for example, a new content to the project.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.
UGUID guid - File GUID.
bool must_exist - A flag indicating whether the specified file must exist.

Return value

true if the file name is appended successfully; otherwise, false.

UGUID AddVirtualFile ( string path, bool must_exist = false ) #

Registers the regular file name as known virtual file and appends it to the map used for fast searching. This method should be used when you need to add, for example, a new content to the project.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.
bool must_exist - A flag indicating whether the specified file must exist.

Return value

File GUID if it was registered successfully or an empty GUID, otherwise.

bool RenameVirtualFile ( string path, string new_path ) #

Renames the specified known virtual file.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.
string new_path - New path for the file.

Return value

true if the file is renamed successfully; otherwise, false.

bool RenameVirtualFile ( string path, string new_path, UGUID new_guid ) #

Renames the specified known file and assigns it the specified new GUID.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.
string new_path - New path for the file.
UGUID new_guid - New GUID for the file.

Return value

true if the file is renamed successfully; otherwise, false.

bool RenameVirtualFile ( UGUID guid, string new_path ) #

Renames the known virtual file with the given GUID.

Arguments

UGUID guid - File GUID.
string new_path - New path for the file.

Return value

true if the file is renamed successfully; otherwise, false.

bool RenameVirtualFile ( UGUID guid, string new_path, UGUID new_guid ) #

Renames the known virtual file with the given GUID and assigns it the specified new GUID.

Arguments

UGUID guid - File GUID.
string new_path - New path for the file.
UGUID new_guid - New GUID for the file.

Return value

true if the file is renamed successfully; otherwise, false.

bool RemoveVirtualFile ( string path ) #

Removes the virtual file with the given name.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is removed successfully; otherwise, false.

bool RemoveVirtualFile ( UGUID guid ) #

Removes the virtual file with the given GUID.

Arguments

UGUID guid - GUID of the known virtual file to remove.

Return value

true if the file is removed successfully; otherwise, false.

bool ChangeVirtualFile ( string path ) #

Marks the virtual file with the given name as modified. The corresponding CALLBACK_FILE_CHANGED signal is emitted. This method is used to notify the Engine that a resource has been modified and needs to be updated.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is successfully marked as modified; otherwise, false.

bool ChangeVirtualFile ( UGUID guid ) #

Marks the virtual file with the given GUID as modified. The corresponding CALLBACK_FILE_CHANGED signal is emitted. This method is used to notify the Engine that a resource has been modified and needs to be updated.

Arguments

UGUID guid - GUID of the known virtual file to remove.

Return value

true if the file is successfully marked as modified; otherwise, false.

void RemoveNonExistingVirtualFiles ( ) #

Removes all non-existing virtual files from the File System. These files aren't physically exist on the disk, however, they are added to the virtual file system. For example, it can be a blob or a cache file.

bool IsDiskFile ( string path ) #

Returns a value indicating if the specified file path is a path to a file on disk (i.e. not a package, a blob, or a cache file).

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the specified file path is a path to a file on disk; otherwise, false.

bool IsDiskFile ( UGUID guid ) #

Returns a value indicating if the file with the specified GUID is a file on disk.

Arguments

UGUID guid - Any file GUID.

Return value

true if the file with the specified GUID is a file on disk; otherwise, false.

bool IsPackageFile ( string path ) #

Returns a value indicating if the specified file path is a path to a file inside a ZIP or UNG package.

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path.

Return value

true if the specified file path is a path to a file inside a ZIP or UNG package; otherwise, false.

bool IsPackageFile ( UGUID guid ) #

Returns a value indicating if the file with the specified GUID is file inside a ZIP or UNG package.

Arguments

UGUID guid - Any file GUID.

Return value

true if the file with the specified GUID is file inside a ZIP or UNG package; otherwise, false.

string ResolvePartialVirtualPath ( string path ) #

Converts the given partial path to a full virtual one.

NoticeIf the file isn't added to the virtual file system, the full virtual path won't be returned.

For example, if you have the data/project/image_1.tga and want to use the partial virtual path image_1.tga, you should get the full virtual path first:

Source code (C#)

// convert partial virtual to full virtual path
String full_virtual_path = FileSystem.get().resolvePartialVirtualPath("image_1.tga"); // project/image_1.tga is returned
// use the converted path
Image.create(full_virtual_path);

Arguments

string path - Partial path to be resolved.

Return value

Full virtual path.

string GetVirtualPath ( string path ) #

Resolves a virtual path for the given file path. The following examples show particular cases of the method usage:

If the given path is known for the virtual file system, the following can be returned:

Source code (C#)

String s1, s2, s3, s4;
// absolute path to the folder
s1 = FileSystem.GetVirtualPath("D:/Unigine/data");			// an empty string
s2 = FileSystem.GetVirtualPath("D:/Unigine/data/");			// an empty string
// path to assets in the folder
s3 = FileSystem.GetVirtualPath("asset://D:/Unigine/data");	// an empty string
s4 = FileSystem.GetVirtualPath("asset://D:/Unigine/data/");	// an empty string

In all cases, an empty string is returned: a virtual path is always returned relative to the data directory, and in the example, the data directory itself is specified. If you specify a known file inside it, the corresponding virtual path will be returned:

Source code (C#)

String s = FileSystem.GetVirtualPath("D:/Unigine/data/1.tga");		// "1.tga"

If the given path is unknown for the virtual file system, the following can be returned:

Source code (C#)

// absolute path to the folder
s1 = FileSystem.GetVirtualPath("C:/temp");			// "C:/temp"
s2 = FileSystem.GetVirtualPath("C:/temp/");			// "C:/temp"
// path to assets in the folder
s3 = FileSystem.GetVirtualPath("asset://C:/temp");	// "C:/temp"
s4 = FileSystem.GetVirtualPath("asset://C:/temp/");	// "C:/temp"

In all cases, the normalized path to the folder is returned, as the specified folder is unknown for the virtual file system, and, therefore, no virtual path can be returned. The same is for files, for example:

Source code (C++)

s = FileSystem.GetVirtualPath("C:/temp/1.tga");		// "C:/temp/1.tga"

If the given path is the path to a mounted file. Here mount_1 is the mount_1.umount mount point. Note that in the example below, the 1.tga asset has no runtime files. If an asset has a runtime file, the virtual path to this runtime file (stored in the .runtimes folder of the mount point) will be returned.

Source code (C#)

// virtual path to the file specified as an absolute one
s1 = FileSystem.GetVirtualPath("D:/Unigine/data/mounts/mount_1/1.tga");	// "mounts/mount_1/1.tga"
// absolute path to the file
s2 = FileSystem.GetVirtualPath("D:/extern_content/1.tga");				// "mounts/mount_1/1.tga"
// full virtual path to the file
s3 = FileSystem.GetVirtualPath("mounts/mount_1/1.tga");					// "mounts/mount_1/1.tga"

If the given path is the path to a mounted file stored in the nested mount points. Here mount_1 and mount_2 are the mount_1.umount and mount_2.umount mount points correspondingly. Note that in the example below, the 1.tga asset has no runtime files. If an asset has a runtime file, the virtual path to this runtime file (stored in the .runtimes folder of the mount point) will be returned.

Source code (C#)

// virtual path to the file specified as an absolute one
s1 = FileSystem.GetVirtualPath("D:/UnigineGIT/data/mounts/mount_1/mount_2/1.tga");	// "mounts/mount_1/mount_2/1.tga"
// absolute path to the file
s2 = FileSystem.GetVirtualPath("D:/extern_content_2/1.tga");						// "mounts/mount_1/mount_2/1.tga"
// full virtual path to the file
s3 = FileSystem.GetVirtualPath("mounts/mount_1/mount_2/1.tga");						// "mounts/mount_1/mount_2/1.tga"

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path, including a path to a folder.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

Virtual path to the file relative to the data folder.

string GetVirtualPath ( UGUID guid ) #

Resolves a virtual path for the given file path.

Arguments

UGUID guid - File GUID.

Return value

Virtual path to the file relative to the data folder.

string GetAbsolutePath ( string path ) #

Resolves an absolute path for the given file path. The following examples show particular cases of the method usage:

If the given path is known for the virtual file system, the following can be returned:

Source code (C#)

String s1, s2, s3, s4;
// absolute path to the folder
s1 = FileSystem.GetAbsolutePath("D:/Unigine/data");			// "D:/Unigine/data"
s2 = FileSystem.GetAbsolutePath("D:/Unigine/data/");		// "D:/Unigine/data"
// absolute path to assets in the folder
s3 = FileSystem.GetAbsolutePath("asset://D:/Unigine/data");	// "D:/Unigine/data"
s4 = FileSystem.GetAbsolutePath("asset://D:/Unigine/data/");// "D:/Unigine/data"

If the given path is unknown for the virtual file system, the following can be returned:

Source code (C#)

// absolute path to the folder
s1 = FileSystem.GetAbsolutePath("C:/temp");				// "C:/temp"
s2 = FileSystem.GetAbsolutePath("C:/temp/");			// "C:/temp"
// absolute path to assets in the folder
s3 = FileSystem.GetAbsolutePath("asset://C:/temp");		// "C:/temp"
s4 = FileSystem.GetAbsolutePath("asset://C:/temp/");	// "C:/temp"

If the given path is the path to a mounted file. Here mount_1 is the mount_1.umount mount point. Note that in the example below, the 1.tga asset has no runtime files. If an asset has a runtime file, the absolute path to this runtime file (stored in the .runtimes folder of the mount point) will be returned.

Source code (C#)

// virtual path specified as an absolute one
s1 = FileSystem.GetAbsolutePath("D:/Unigine/data/mounts/mount_1/1.tga");	// "D:/extern_content/1.tga"
// absolute path
s2 = FileSystem.GetAbsolutePath("D:/extern_content/1.tga");					// "D:/extern_content/1.tga"
// virtual path
s3 = FileSystem.GetAbsolutePath("mounts/mount_1/1.tga");					// "D:/extern_content/1.tga"

If the given path is the path to a mounted file stored in the nested mount points. Here mount_1 and mount_2 are the mount_1.umount and mount_2.umount mount points correspondingly. Note that in the example below, the 1.tga asset has no runtime files. If an asset has a runtime file, the absolute path to this runtime file (stored in the .runtimes folder of the mount point) will be returned.
Source code (C#)
```
// virtual path specified as an absolute one
s1 = FileSystem.GetAbsolutePath("D:/Unigine/data/mounts/mount_1/mount_2/1.tga");	// "D:/extern_content_2/1.tga"
// absolute path
s2 = FileSystem.GetAbsolutePath("D:/extern_content_2/1.tga");						// "D:/extern_content_2/1.tga"
// virtual path
s3 = FileSystem.GetAbsolutePath("mounts/mount_1/mount_2/1.tga");					// "D:/extern_content_2/1.tga"
```

If the given path is a network path:

Source code (C#)

s1 = FileSystem.GetAbsolutePath("//studio/work/shared_content/images.zip");			// "//studio/work/shared_content/images.zip"
s2 = FileSystem.GetAbsolutePath("\\\\studio\\work\\shared_content\\images.zip");	// "//studio/work/shared_content/images.zip"

Arguments

string path - File path. It can be a relative, absolute, network, or virtual path, including a path to a folder.
Notice
If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

Absolute path to the file.

string GetAbsolutePath ( UGUID guid ) #

Resolves an absolute path for the given file GUID.

Arguments

UGUID guid - File GUID.

Return value

Absolute path to the file.

bool addExternPackage ( Package package ) #

Adds a custom package to the virtual file system.

Arguments

Package package - Custom package instance.

Return value

true if the package is added successfully; otherwise, false.

bool addExternPackage ( string path, Package package ) #

Adds a custom package to the virtual file system and assigns a virtual path to it. The virtual path is obtained by using the given path.

Arguments

string path - Path to a custom package. It can be a relative, absolute, network, or virtual path.
Package package - Custom package instance.

Return value

true if the package is added successfully; otherwise, false.

void preloadExternPackage ( Package package ) #

Loads the custom package before the file system initialization. The method should be called before the Engine init.

Source code (C#)

// preload package
MyPackage package = new MyPackage();
FileSystem.preloadExternPackage(package);
// init engine
Engine engine = Engine.init(Engine.VERSION, args);

Arguments

Package package - Custom package instance.

void preloadExternPackage ( string virtual_path, Package package ) #

Loads the custom package before the file system initialization and sets a virtual path to it. The method should be called before the Engine init.

Arguments

string virtual_path - Virtual path to a custom package.
Package package - Custom package instance.

void clearPreloadedExternPackages ( ) #

Clears all preloaded custom packages (packages loaded before the file system initialization).

Last update: 2020-07-31

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)

Unigine.FileSystem Class

See also#

Properties:

Methods:

FileSystem Class

Properties

int NumModifiers#

Members

bool IsBlobFile ( string path ) #

Arguments

Return value

bool IsBlobFile ( UGUID guid ) #

Arguments

Return value

bool IsCacheFile ( string path ) #

Arguments

Return value

bool IsCacheFile ( UGUID guid ) #

Arguments

Return value

bool IsFileExist ( string path ) #

Arguments

Return value

bool IsFileExist ( UGUID guid ) #

Arguments

Return value

long GetMTime ( string path ) #

Arguments

Return value

long GetMTime ( UGUID guid ) #

Arguments

Return value

bool AddBlobFile ( string path ) #

Arguments

Return value

bool AddBlobFile ( UGUID guid ) #

Arguments

Return value

bool AddCacheFile ( string path ) #

Arguments

Return value

bool AddCacheFile ( UGUID guid ) #

Arguments

Return value

bool LoadPackage ( string path ) #

Arguments

Return value

bool LoadPackage ( string path, string extension ) #

Arguments

Return value

bool RemoveBlobFile ( string path ) #

Arguments

Return value

bool RemoveBlobFile ( UGUID guid ) #

Arguments

Return value

bool RemoveCacheFile ( string path ) #

Arguments

Return value

bool RemoveCacheFile ( UGUID guid ) #

Arguments

Return value

string GetModifier ( int num ) #

Arguments

Return value

void AddModifier ( string name ) #

Arguments

void RemoveModifier ( string name ) #

Arguments

void ClearModifiers ( ) #

bool RemovePackage ( string path ) #

Arguments

Return value

bool IsAssetPath ( string path ) #

Arguments

Return value

UGUID GenerateGUID ( ) #

Return value

bool SetGUID ( string path, UGUID guid ) #

Arguments