This page has been translated automatically.
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
CIGI Client Plugin
Rendering-Related Classes
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Unigine::Filesystem Class

Header:#include <UnigineFileSystem.h>

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


FileSystem * get()

int isBlobFile(const char * 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

  • const char * 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(const UGUID & guid)

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

Arguments

  • const UGUID & guid - File GUID.

Return value

1 if the file is loaded to a blob successfully; otherwise, 0.

int isCacheFile(const char * name)

Checks if the given file is loaded into cache. A path to the file should be relative to the data folder.

Arguments

  • const char * name - Relative path to the file (including its name).

Return value

1 if the file is added into cache; otherwise, 0.

int isCacheFile(const UGUID & guid)

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

Arguments

  • const UGUID & guid - File GUID.

Return value

1 if the file is added into cache; otherwise, 0.

int isFile(const char * name, int strict = 0)

Checks if a file with the given name exists in the file system.

Arguments

  • const char * 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(const UGUID & guid, int strict = 0)

Checks if a file with the given GUID exists in the file system.

Arguments

  • const 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.

const char * getFileName(const char * 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

  • const char * 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.

const char * getFileName(const 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

  • const 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(Vector< String > & names)

Fills the given vector with the list of unarchived files cached by the file system.

Arguments

  • Vector< String > & names - A vector where file names will be saved.

int isKnownFile(const char * 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

  • const char * 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(const UGUID & guid, int strict = 0)

Checks if a file with the given GUID is known to the file system.

Arguments

  • const 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.

const char * getModifier(int num)

Returns the name of the given modifier.

Arguments

  • int num - ID number of the modifier.

Return value

Modifier name.

int setMTime(const char * name, long long time, int strict = 0)

Sets the time of the file last modification.

Arguments

  • const char * name - File name.
  • long 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 long getMTime(const char * name, int strict = 0)

Returns the time of the file last modification.

Arguments

  • const char * 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(const char * name, int strict = 0)

Checks if a file with a given name exists in one of the loaded packages.

Arguments

  • const char * 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, const char * 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.
  • const char * 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(const UGUID & guid, int strict = 0)

Checks if a file with a given GUID exists in one of the loaded packages.

Arguments

  • const 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, const 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.
  • const 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.

const char * getPackageFileName(int num, const char * 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: %s\n",FileSystem::getPackageFilesystem(0,"material_ball.mesh"));
Output
A path to the file inside the package: meshes/material_ball.mesh

Arguments

  • int num - Number of the ZIP or UNG package in the array of the loaded packages.
  • const char * 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, Vector< 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.
  • Vector< String > & names - A vector where file names will be saved.

const char * 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: %s\n",FileSystem::getPackageName(0));
Output
A path to a package: D:/unigine_projects/unigine_project/data/core.ung

Arguments

  • 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(const char * 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

  • const char * 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(const char * name, const 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

  • const char * name - Absolute or relative path to the file (including its name).
  • const UGUID & guid - File GUID.

Return value

1 if the file is successfully added into a blob; otherwise, 0.

int addCacheFile(const char * 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

  • const char * 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(const char * name, const 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

  • const char * name - Relative path to the file (including its name) to add to cache.
  • const UGUID & guid - File GUID.

Return value

1 if the file is successfully added to cache; otherwise, 0.

void addDirectory(const char * name)

Adds an external directory to the file system.

Arguments

  • const char * name - Absolute path to the directory (including its name).

int addKnownFile(const char * name, int strict = 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

  • const char * 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.

Return value

1 if the file name is appended successfully; otherwise, 0.

int addKnownFile(const char * name, const UGUID & guid, int strict = 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

  • const char * name - Absolute or relative path to the file to register its name as known.
  • const 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 name is appended successfully; otherwise, 0.

int removeKnownFile(const char * name, int strict = 0)

Removes the known file with the given name.

Arguments

  • const char * 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(const UGUID & guid, int strict = 0)

Removes the known file with the given GUID.

Arguments

  • const 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(const char * name, const char * new_name, int strict = 0)

Renames the specified known file.

Arguments

  • const char * name - Absolute or relative path to the file.
  • const char * 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(const char * name, const char * new_name, const UGUID & new_guid, int strict = 0)

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

Arguments

  • const char * name - Absolute or relative path to the file.
  • const char * new_name - New path for the file.
  • const 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(const UGUID & guid, const char * new_name, int strict = 0)

Renames the known file with the given GUID.

Arguments

  • const UGUID & guid - File GUID.
  • const char * 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(const UGUID & guid, const char * new_name, const UGUID & new_guid, int strict = 0)

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

Arguments

  • const UGUID & guid - File GUID.
  • const char * new_name - New path for the file.
  • const 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(const char * name)

Registers a new modifier in the file system.

Arguments

  • const char * name - Modifier name.

void clearModifiers()

Unregister all modifiers in the file system.

int findPackage(const char * name)

Checks if an UNG or ZIP package has been added into the file system.

Arguments

  • const char * 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(const char * name, const char * 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

  • const char * name - Package name. It can be an absolute path or a path relative to data directory, if it is inside of it.
  • const char * extension - ung or zip package extension.

Return value

1 if the package is loaded; otherwise, 0.

int reloadPackage(const char * name)

Reloads package files.

Arguments

  • const char * name

Return value

Returns 1 if the package is reloaded successfully; otherwise, 0.

int removeBlobFile(const char * 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

  • const char * 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(const 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

  • const UGUID & guid - File GUID.

Return value

1 if the file is removed successfully; otherwise, 0.

int removeCacheFile(const char * 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

  • const char * 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(const 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

  • const UGUID & guid - File GUID.

Return value

1 if the file is successfully removed from cache; otherwise, 0.

void removeModifier(const char * name)

Unregisters a given modifier in the file system.

Arguments

  • const char * name - Modifier name.

int removePackage(const char * name)

Unloads an UNG or ZIP package from the file system.

Arguments

  • const char * name - An absolute path to the package (including its name).

Return value

1 if the package is removed; otherwise, 0.

const char * resolveName(const char * name, int strict = 0)

Returns the path to the file with the specified name.

Arguments

  • const char * 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

File path.

const char * resolveName(const UGUID & guid, int strict = 0)

Returns the path to the file with the specified GUID.

Arguments

  • const 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

File path.

int setGUID(const char * name, const UGUID & guid, int strict = 0)

Sets the specified GUID for the given file.

Arguments

  • const char * name - File path.
  • const 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(const char * name, int strict = 0)

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

Arguments

  • const char * 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 isGUID(const char * name)

Returns a value indicating if the given input string is a GUID.

Arguments

  • const char * name - Input string.

Return value

1 if the given input string is a GUID; otherwise, 0.

int saveGUIDs(const char * name)

Saves all file system GUIDs to the specified file.

Arguments

  • const char * name - Path to the file, where file system GUIDs are to be stored.

Return value

1 if all file system GUIDs are saved successfully; otherwise, 0.

int loadGUIDs(const char * name, int strict = 0)

Loads file system GUIDs from the specified file.

Arguments

  • const char * 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.

String getRelativeFileName(const char * name, int strict = 0)

Returns a path to the given file which is relative to the data folder.

Arguments

  • const char * 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(const UGUID & guid, int strict = 0)

Returns a path to the given file which is relative to the data folder.

Arguments

  • const 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.
Last update: 2017-12-21
Build: ()