engine.filesystem Functions

List of functions:

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 (engine.filesystem.addDirectory(), engine.filesystem.loadPackage()).

Files, meshes and images stored under and outside the data directory are loaded on demand only.

The functions given below:

Provide control over asynchronous loading of files/meshes/images 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.

Loading Files on Demand

Loading of files/meshes/images on demand is performed in a separate system thread, in addition to asynchronous content streaming. It is possible to control loading queue by organizing files in groups and setting individual weights inside these groups.

To load files on demand, call the functions in the following order:

First engine.filesystem.loadFile() function is called to place the file in the queue for loading.
After that, different operations can be performed:
Notice
If you specify an absolute path to a file in the engine.filesystem.loadFile() function, you should use this absolute path when performing operations on it. The same is true for relative paths.
- engine.filesystem.forceFile() to load the file immediately.
- engine.filesystem.removeFile() to remove the file from the queue in case there is no need to load it any more.
- engine.filesystem.validateFile() to check if the file is still pending in the queue or if it has already been loaded.
- engine.filesystem.checkFile() to check if the given file was requested to be loaded viaengine.filesystem.loadFile().

The same algorithm is true for meshes and images. For example:

When a mesh is stored in the data folder:

Source code (UnigineScript)

// specify a relative path when loading to the queue
engine.filesystem.loadMesh("box.mesh");
// check if the mesh is loaded into the queue
Mesh box = engine.filesystem.getMesh("box.mesh");
while(box == NULL) {
    // waiting...
}

When a mesh is stored outside the data folder:

Source code (UnigineScript)

// specify a relative path when loading to the queue
engine.filesystem.loadMesh("D:/meshes/box.mesh");
// check if the mesh is loaded into the queue
Mesh box = engine.filesystem.getMesh("D:/meshes/box.mesh");
while(box == NULL) {
    // waiting...
}

FileSystem Class

Members

int engine.filesystem.isBlobFile(string name)

Checks if the given file is loaded into a 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 loaded successfully; otherwise, 0.

int engine.filesystem.isCacheFile(string name)

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

Arguments

string name - A relative path to the file (including its name).

Return value

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

int engine.filesystem.isFile(string name)

Arguments

string name

string engine.filesystem.getFileName(string name)

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.

Return value

The path which is relative to the binary executable.

Image engine.filesystem.getImage(string name)

Checks whether the image is placed to the loading queue and return it if it is.

Arguments

string name - An absolute or relative path to the mesh (including its name).

Return value

The image if it is in the queue, otherwise, 0.

int engine.filesystem.isKnownFile(string name)

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

Return value

1 if the file is known to the file system; otherwise, 0.

Mesh engine.filesystem.getMesh(string name)

Checks whether the mesh is placed to the loaded queue.

Arguments

string name - An absolute or relative path to the mesh (including its name).

Return value

The mesh if it is placed in the queue; otherwise, 0.

string engine.filesystem.getModifier(int num)

Returns the name of the given modifier.

Arguments

int num - ID number of the modifier.

Return value

Modifier name.

int engine.filesystem.setMTime(string name, long time)

Sets the time of the file last modification.

Arguments

string name - File name.
long time - Time stamp to set.

Return value

1 if the time stamp is set successfully; otherwise, 0.

long engine.filesystem.getMTime(string name)

Returns the time of the file last modification.

Arguments

string name - File name.

Return value

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

int engine.filesystem.getNumFiles()

Returns the number of files cached by the file system.

Return value

Number of cached files.

int engine.filesystem.getNumModifiers()

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

Return value

Number of modifiers.

int engine.filesystem.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 engine.filesystem.getNumPackages()

Returns the number of ZIP and UNG packages inside the data directory.

Return value

Number of packages.

int engine.filesystem.getNumQueuedData()

Returns the number of queued file system data waiting for background loading. The return value also includes the currently processed data.

Return value

Number of queued file system data including the currently processed data.

int engine.filesystem.getNumQueuedFiles()

Returns the number of queued files waiting for the background loading. The return value also includes the currently processed file.

Return value

Number of queued files including the currently processed file.

int engine.filesystem.getNumQueuedImages()

Returns the number of queued images waiting for the background loading. The return value also includes the currently processed image.

Return value

Number of queued images including the currently processed image.

int engine.filesystem.getNumQueuedMeshes()

Returns the number of queued meshes waiting for the background loading. The return value also includes the currently processed mesh.

Return value

Number of queued meshes including the currently processed mesh.

int engine.filesystem.getNumQueuedResources()

Returns the number of queued file system resources waiting for the background loading. The return value represents the sum of the queued and the currently processed data, files, images and meshes.

Return value

Number of queued file system resources including the currently processed resources.

int engine.filesystem.isPackageFile(int num, string name)

Checks if the given file exists in the package.

Arguments

int num - Number of the ZIP or UNG package.
string name - File name.

Return value

1 if the file exists; otherwise, 0.

string engine.filesystem.getPackageFileName(int num, string name)

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",engine.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.
string name - File name.

Return value

A path to the file of the package.

string engine.filesystem.getPackageName(int num)

Returns an absolute path (including a name) to a given ZIP or UNG package.

Source code (UnigineScript)

log.message("A path to a package: %s\n",engine.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).

float engine.filesystem.getTotalTime()

Returns the total time (in milliseconds) of loading a file system resource.

Return value

The total time value, milliseconds.

int engine.filesystem.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 - An 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 engine.filesystem.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 - A relative path to the file (including its name) to add to a cache.

Return value

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

void engine.filesystem.addDirectory(string name)

Adds an external directory to the file system.

Arguments

string name - An absolute path to the directory (including its name).

int engine.filesystem.addKnownFile(string name)

Registers the regular file name as known and appends it into the map used for fast searching. 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 to register its name as known.

Return value

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

void engine.filesystem.addModifier(string name)

Registers a new modifier in the file system.

Arguments

string name - Modifier name.

int engine.filesystem.checkFile(string name)

Returns a value indicating if:

The given file was loaded to the file system.
The given file is being loaded to the file system at the moment.
The given file is in the loading queue.

Arguments

string name - An absolute or relative path to the file (including its name).

Return value

1 if the file is in the loading queue, already loaded to the file system or is being loaded to file system at the moment; otherwise, 0.

int engine.filesystem.checkImage(string name)

Returns a value indicating if:

The given image was loaded to the file system.
The given image is being loaded to the file system at the moment.
The given image is in the loading queue.

Arguments

string name - An absolute or relative path to the image (including its name).

Return value

1 if the image is in the loading queue, already loaded to the file system or is being loaded to file system at the moment; otherwise, 0.

int engine.filesystem.checkMesh(string name)

Returns a value indicating if:

The given mesh was loaded to the file system.
The given mesh is being loaded to the file system at the moment.
The given mesh is in the loading queue.

Arguments

string name - An absolute or relative path to the mesh (including its name).

Return value

1 if the mesh is in the loading queue, already loaded to the file system or is being loaded to file system at the moment; otherwise, 0.

void engine.filesystem.clearModifiers()

Unregister all modifiers in the file system.

int engine.filesystem.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 engine.filesystem.forceFile(string name)

Starts loading of the given file from the loading queue. The file will be loaded right after the currently loading file (if any) is processed. All other file system operations are suspended until the forced file is loaded. Note that the file won't be loaded immediately after calling the function as it can be large, for example.

Arguments

string name - An absolute or relative path to the file (including its name).

Return value

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

int engine.filesystem.forceImage(string name)

Starts loading of the given image from the loading queue. The image will be loaded right after the currently loading image (if any) is processed. All other file system operations are suspended until the forced image is loaded. Note that the image won't be loaded immediately after calling the function as it can be large, for example.

Arguments

string name - An absolute or relative path to the image (including its name).

Return value

1 if the image is successfully loaded; otherwise, 0.

int engine.filesystem.forceMesh(string name)

Starts loading of the given mesh from the loading queue. The mesh will be loaded right after the currently loading mesh (if any) is processed. All other file system operations are suspended until the forced mesh is loaded. Note that the mesh won't be loaded immediately after calling the function as it can be large, for example.

Arguments

string name - An absolute or relative path to the mesh (including its name).

Return value

1 if the mesh is successfully loaded; otherwise, 0.

int engine.filesystem.loadFile(string name, int group = 0, float weight = 0.0f)

Loads a file on demand: adds a file to the background loading queue (i.e. threaded file loading). Files with identical priorities and weights are loaded in the alphabetical order.

Arguments

string name - An absolute or relative path to the file (including its name).
int group - Group of the priority. Greater priority means faster loading. The default is 0.
float weight - Weight of the file priority inside the group. Greater weight means faster loading inside the same priority group. The default value is 0.

Return value

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

int engine.filesystem.loadImage(string name, int group = 0, float weight = 0.0f)

Adds an image to the background loading queue (i.e. threaded image loading). Images with the identical groups and weights are loaded in the alphabetical order.

Arguments

string name - An absolute or relative path to the image (including its name).
int group - Group of the priority. Greater priority means faster loading. The default is 0.
float weight - Weight of the image priority. Greater weight means faster loading inside the same priority group. The default value is 0.

Return value

1 if the image is successfully appended to the queue; otherwise, 0.

int engine.filesystem.loadMesh(string name, int group = 0, float weight = 0.0f)

Loads a mesh on demand: adds a mesh to the background loading queue (i.e. threaded mesh loading). Meshes with the identical groups and weights are loaded in the alphabetical order.

Arguments

string name - An absolute or relative path to the mesh (including its name).
int group - Group of the loading priority. The default is 0. Greater priority means faster loading.
float weight - Weight of the mesh priority inside the group. Greater weight means faster loading inside the same priority group. The default value is 0.

Return value

1 if the mesh is successfully appended to the queue; otherwise, 0.

int engine.filesystem.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).

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 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 engine.filesystem.reloadPackage(string name)

Reloads package files.

Arguments

string name

Return value

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

int engine.filesystem.removeBlobFile(string name)

Arguments

string name - An absolute or relative path to the file (including its name).

Return value

int engine.filesystem.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 a cache; otherwise, 0.

int engine.filesystem.removeFile(string name)

Removes a pending file from the loading queue.

Arguments

string name - An absolute or relative path to the file (including its name).

Return value

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

int engine.filesystem.removeImage(string name)

Removes a pending image from the loading queue.

Arguments

string name - An absolute or relative path to the image (including its name).

Return value

1 if the image is successfully removed, otherwise, 0.

int engine.filesystem.removeMesh(string name)

Removes a pending mesh from the loading queue.

Arguments

string name - An absolute or relative path to the mesh (including its name).

Return value

1 if the mesh is removed successfully; otherwise 0.

void engine.filesystem.removeModifier(string name)

Unregisters a given modifier in the file system.

Arguments

string name - Modifier name.

int engine.filesystem.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.

int engine.filesystem.validateFile(string name)

Checks whether the pending file placed in the loading queue has been loaded.

Arguments

string name - An absolute or relative path to the file (including its name).

Return value

1 if the file is loaded; 0 if it is still pending in the queue.

Last update: 2017-07-03

Help improve this article

Was this article helpful?

Report a problem related to this article

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