Unigine.Filesystem Class
On the engine file system initialization, all files and packages stored in the data folder are added to the 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 should be added to the file system on the application start-up or by using the corresponding functions (addDirectory(), loadPackage()).
Files, meshes, images, and nodes stored under and outside the data directory are loaded on demand only.
Filesystem 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 in run-time.
Notice
- This class is in the Unigine namespace.
- This class is a singleton.
See also
- AsyncQueue Class to manage loading resources (files, images, meshes, and nodes) on demand.
FileSystem Class
Members
int isBlobFile(string name)
Checks if the given file is loaded to a blob. A path to the file can be both absolute or relative to the data directory.Arguments
- string name - Absolute or relative path to the file (including its name).
Return value
1 if the file is loaded to a blob successfully; otherwise, 0.int isBlobFile(UGUID guid)
Checks if a file with the given GUID is loaded to a blob.Arguments
- UGUID guid - File GUID.
Return value
1 if the file is loaded to a blob successfully; otherwise, 0.int isCacheFile(string name)
Checks if the given file is loaded into cache. A path to the file should be relative to the data folder.Arguments
- string name - Relative path to the file (including its name).
Return value
1 if the file is added into cache; otherwise, 0.int isCacheFile(UGUID guid)
Checks if a file with the given GUID is loaded into cache.Arguments
- UGUID guid - File GUID.
Return value
1 if the file is added into cache; otherwise, 0.int isFile(string name, int strict = 0)
Checks if a file with the given name exists in the file system.Arguments
- string name - Absolute or relative path to the file (including its name).
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file exists; otherwise, 0.int isFile(UGUID guid, int strict = 0)
Checks if a file with the given GUID exists in the file system.Arguments
- UGUID guid - File GUID.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file exists; otherwise, 0.string getFileName(string name, int strict = 0)
Returns the relative path to the file by the given partial one. The path will be relative to the binary executable.Arguments
- string name - File name or the partial path to it.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
Path which is relative to the binary executable.string getFileName(UGUID guid, int strict = 0)
Returns the relative path to the file by the given file GUID. The path will be relative to the binary executable.Arguments
- UGUID guid - File GUID.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
Path which is relative to the binary executable.void getFileNames(string[] names)
Fills the given vector with the list of unarchived files cached by the file system.Arguments
- string[] names - A vector where file names will be saved.
int isKnownFile(string name, int strict = 0)
Checks if the given file is known to the file system. A path to the file can be both relative or absolute to the data directory.Arguments
- string name - An absolute or relative path to the file (including its name).
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file is known to the file system; otherwise, 0.int isKnownFile(UGUID guid, int strict = 0)
Checks if a file with the given GUID is known to the file system.Arguments
- UGUID guid - File GUID.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file is known to the file system; otherwise, 0.string getModifier(int num)
Returns the name of the given modifier.Arguments
- int num - ID number of the modifier.
Return value
Modifier name.int setMTime(string name, long time, int strict = 0)
Sets the time of the file last modification.Arguments
- string name - File name.
- long time - Time stamp to set.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the time stamp is set successfully; otherwise, 0.long getMTime(string name, int strict = 0)
Returns the time of the file last modification.Arguments
- string name - File name.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
Time of the last modification. If there is no file with such name, -1 will be returned.int getNumFiles()
Returns the number of files cached by the file system.Return value
Number of cached files.int getNumModifiers()
Returns the total number of file modifiers registered in the file system.Return value
Number of modifiers.int getNumPackageFiles(int num)
Returns the number of files inside of a given ZIP or UNG package.Arguments
- int num - Number of the ZIP or UNG package.
Return value
Number of files inside a package.int getNumPackages()
Returns the number of ZIP and UNG packages inside the data directory.Return value
Number of packages.int isPackageFile(string name, int strict = 0)
Checks if a file with a given name exists in one of the loaded packages.Arguments
- string name - File name.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file exists; otherwise, 0.int isPackageFile(int num, string name, int strict = 0)
Checks if a file with a given name exists in the specified package.Arguments
- int num - Number of the ZIP or UNG package in the array of the loaded packages.
- string name - File name.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file exists; otherwise, 0.int isPackageFile(UGUID guid, int strict = 0)
Checks if a file with a given GUID exists in one of the loaded packages.Arguments
- UGUID guid - File GUID.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file exists; otherwise, 0.int isPackageFile(int num, UGUID guid, int strict = 0)
Checks if a file with a given GUID exists in the specified package.Arguments
- int num - Number of the ZIP or UNG package in the array of the loaded packages.
- UGUID guid - File GUID.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file exists; otherwise, 0.string getPackageFileName(int num, string name, int strict = 0)
Returns the path to the given file relative to the package root directory. The path includes the name of the given file.Source code (UnigineScript)
Log.message("A path to the file inside the package: {0}\n",FileSystem.getPackageFilesystem(0,"material_ball.mesh"));Output
A path to the file inside the package: meshes/material_ball.meshArguments
- int num - Number of the ZIP or UNG package in the array of the loaded packages.
- string name - File name.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
A path to the file of the package.void getPackageFileNames(int num, string[] names)
Fills the given vector with the list of files in the specified ZIP or UNG package.Arguments
- int num - Number of the ZIP or UNG package.
- string[] names - A vector where file names will be saved.
string getPackageName(int num)
Returns an absolute path (including a name) to a given ZIP or UNG package.Source code (C#)
Log.message("A path to a package: {0}\n",FileSystem.getPackageName(0));Output
A path to a package: D:/unigine_projects/unigine_project/data/core.ungArguments
- int num - Number of the ZIP or UNG package in the array of the loaded packages.
Return value
An absolute path to the package (including its name).int addBlobFile(string name)
Adds a file into a blob. It can be used for files that are frequently modified in 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. A path to the file can be both absolute or relative to the data directory.Arguments
- string name - Absolute or relative path to the file (including its name).
Return value
1 if the file is successfully added into a blob; otherwise, 0.int addBlobFile(string name, UGUID guid)
Adds a file with the given GUID into a blob. It can be used for files that are frequently modified in 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. A path to the file can be both absolute or relative to the data directory.Arguments
- string name - Absolute or relative path to the file (including its name).
- UGUID guid - File GUID.
Return value
1 if the file is successfully added into a blob; otherwise, 0.int addCacheFile(string name)
Caches a file in the memory. It can be used for files that are accessed multiple times in run-time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading. A path to the file should be relative to the data folder.Arguments
- string name - Relative path to the file (including its name) to add to cache.
Return value
1 if the file is successfully added to cache; otherwise, 0.int addCacheFile(string name, UGUID guid)
Caches a file in the memory with the given GUID. It can be used for files that are accessed multiple times in run-time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading. A path to the file should be relative to the data folder.Arguments
- string name - Relative path to the file (including its name) to add to cache.
- UGUID guid - File GUID.
Return value
1 if the file is successfully added to cache; otherwise, 0.void addDirectory(string name)
Adds an external directory to the file system.Arguments
- string name - Absolute path to the directory (including its name).
UGUID addKnownFile(string name, int strict = 0, int exist = 0)
Registers the regular file name as known and appends it to the map used for fast searching. A path to the file can be both relative or absolute to the data directory.Arguments
- string name - Absolute or relative path to the file to register its name as known.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
- int exist
Return value
File GUID if it was registered successfully or an empty GUID, otherwise.int addKnownFile(string name, UGUID guid, int strict = 0, int exist = 0)
Registers the regular file name as known with the given GUID and appends it to the map used for fast searching. A path to the file can be both relative or absolute to the data directory.Arguments
- string name - Absolute or relative path to the file to register its name as known.
- UGUID guid - File GUID.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
- int exist
Return value
1 if the file name is appended successfully; otherwise, 0.int removeKnownFile(string name, int strict = 0)
Removes the known file with the given name.Arguments
- string name - Absolute or relative path to the known file to remove.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file is removed successfully; otherwise, 0.int removeKnownFile(UGUID guid, int strict = 0)
Removes the known file with the given GUID.Arguments
- UGUID guid - GUID of the known file to remove.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file is removed successfully; otherwise, 0.int renameKnownFile(string name, string new_name, int strict = 0)
Renames the specified known file.Arguments
- string name - Absolute or relative path to the file.
- string new_name - New path for the file.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file is renamed successfully; otherwise, 0.int renameKnownFile(string name, string new_name, UGUID new_guid, int strict = 0)
Renames the specified known file and assigns it the specified new GUID.Arguments
- string name - Absolute or relative path to the file.
- string new_name - New path for the file.
- UGUID new_guid - New GUID for the file.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file is renamed successfully; otherwise, 0.int renameKnownFile(UGUID guid, string new_name, int strict = 0)
Renames the known file with the given GUID.Arguments
- UGUID guid - File GUID.
- string new_name - New path for the file.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file is renamed successfully; otherwise, 0.int renameKnownFile(UGUID guid, string new_name, UGUID new_guid, int strict = 0)
Renames the known file with the given GUID and assigns it the specified new GUID.Arguments
- UGUID guid - File GUID.
- string new_name - New path for the file.
- UGUID new_guid - New GUID for the file.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the file is renamed successfully; otherwise, 0.void addModifier(string name)
Registers a new modifier in the file system.Arguments
- string name - Modifier name.
void clearModifiers()
Unregister all modifiers in the file system.int findPackage(string name)
Checks if an UNG or ZIP package has been added into the file system.Arguments
- string name - An absolute path to the package (including its name).
Return value
Number of the ZIP or UNG package if it is found; otherwise, -1.int loadPackage(string name, string extension = 0)
Loads an UNG or ZIP package into the file system. An archive can be located outside data directory ( an absolute path should be specified in this case).Notice
UNG 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 name - Package name. It can be an absolute path or a path relative to data directory, if it is inside of it.
- string extension - ung or zip package extension.
Return value
1 if the package is loaded; otherwise, 0.int reloadPackage(string name)
Reloads package files.Arguments
- string name
Return value
Returns 1 if the package is reloaded successfully; otherwise, 0.int removeBlobFile(string name)
Removes a blob with a file from the blob. Blobbing can be used for files that are frequently modified in 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. A path to the file can be both absolute or relative to the data directory.Arguments
- string name - An absolute or relative path to the file (including its name).
Return value
1 if the file is removed successfully; otherwise, 0.int removeBlobFile(UGUID guid)
Removes a file with the given GUID from the blob. Blobbing can be used for files that are frequently modified in 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
1 if the file is removed successfully; otherwise, 0.int removeCacheFile(string name)
Removes a cached file from the memory. Caching can be used for files that are accessed multiple times in run-time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading. A path to the file should be relative to the data folder.Arguments
- string name - A relative path to the file (including its name) to be removed from a cache.
Return value
1 if the file is successfully removed from cache; otherwise, 0.int 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 in 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
1 if the file is successfully removed from cache; otherwise, 0.void removeModifier(string name)
Unregisters a given modifier in the file system.Arguments
- string name - Modifier name.
int removePackage(string name)
Unloads an UNG or ZIP package from the file system.Arguments
- string name - An absolute path to the package (including its name).
Return value
1 if the package is removed; otherwise, 0.string getAbsoluteFileName(string name, int strict = 0)
Returns the absolute path to the file with the specified name.Arguments
- string name - File name.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
Absolute path to the file.string getAbsoluteFileName(UGUID guid, int strict = 0)
Returns the absolute path to the file with the specified GUID.Arguments
- UGUID guid - File GUID.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
Absolute path to the file.int isAssetPath(string name)
Returns a value indicating if the given path has a valid asset path format (e.g. "asset://1.tga)".Arguments
- string name - Path to be checked.
Return value
1 if the given path has a valid asset path format; otherwise, 0.string getExtension(string name, int strict = 0)
Returns the extension of the file registered with the given name.Arguments
- string name - File name.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
Extension of the file registered with the given name if it exists, or an emty string.string getExtension(UGUID guid, int strict = 0)
Returns the extension of the file registered with the given GUID.Arguments
- UGUID guid - File GUID.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
Extension of the file registered with the given GUID if it exists, or an emty string.UGUID generateGUID()
Generates a new GUID.Return value
New filesystem GUID if is was generated successfully; otherwise, an empty GUID.int setGUID(string name, UGUID guid, int strict = 0)
Sets the specified GUID for the given file.Arguments
- string name - File path.
- UGUID guid - GUID to be set for the file.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if the GUID is set successfully; otherwise, 0.UGUID getGUID(string name, int strict = 0)
Returns the GUID (if it exists) for the given file.Arguments
- string name - File path.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
File GUID if it exists, or an empty GUID, otherwise.int isGUIDPath(string name)
Returns a value indicating if the given path has a valid GUID path format (e.g. "guid://e231e15beff2309b8f87c30b2c105cc4d2399973)".Arguments
- string name - Path to be checked.
Return value
1 if the given path has a valid GUID path format; otherwise, 0.int saveGUIDs(string name, int binary = 1)
Saves all file system GUIDs to the specified file in the specified format (json or binary).Arguments
- string name - Path to the file, where file system GUIDs are to be stored.
- int binary - Binary file format flag. When the flag is set to 1, the filesystem will save GUIDs to a binary file; otherwise, to a JSON file.
Return value
1 if all file system GUIDs are saved successfully; otherwise, 0.int loadGUIDs(string name, int strict = 0)
Loads file system GUIDs from the specified file.Arguments
- string name - Path to the file, where file system GUIDs are stored.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
1 if file system GUIDs are loaded successfully; otherwise, 0.void clearGUIDs()
Clears all file system GUIDs.void clearNonexistentPaths()
Clears all file paths, that don't exist.string getRelativeFileName(string name, int strict = 0)
Returns a path to the given file which is relative to the data folder.Arguments
- string name - File name or the partial path to it.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
Path to the file relative to the data folder.string getRelativeFileName(UGUID guid, int strict = 0)
Returns a path to the given file which is relative to the data folder.Arguments
- UGUID guid - File GUID.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
Path to the file relative to the data folder.string getKnownFileName(string name, int strict = 0)
Returns a path to a known file with a given name.Arguments
- string name - File name or the partial path to it.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
Path to the specified known file.string getKnownFileName(UGUID guid, int strict = 0)
Returns a path to a known file with a given GUID.Arguments
- UGUID guid - File GUID.
- int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
Return value
Path to the specified known file.void getKnownAbsoluteFileNames(string[] names)
Saves the list of absolute names for all known files registered in the file system to the specified string buffer.Arguments
- string[] names - String buffer to store the list of absolute names for all known files.
void getKnownFileNames(string[] names)
Saves the list of names for all known files registered in the file system to the specified string buffer.Arguments
- string[] names - String buffer to store the list of names for all known files.
Last update: 2018-06-04
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)