engine.filesystem Functions

List of Functions:

These set of functions allows for the following:

Gives control over loading of files 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.
Allows to add ZIP and UNG packages that are outside the data directory. After that, files in them are accessed in a usual way, by specifying a path to the file only inside the package.
Allows to add directories (even with ZIP and UNG packages) that are outside the data directory by specifying a link to it in a *.ulink.

Loading Files on Demand

To load files on demand, call these 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:
- 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 anymore
- 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 via engine.filesystem.loadFile()

Adding Directories via ULINK

To add a directory that is outside the data directory, add a special file that contains a link to this directory. This link file has *.ulink extension and is stored anywhere inside data. When the engine scans through files and comes across such link file, it adds all files from the specified directory. If ZIP and UNG packages are found between them, they are also added to the file system.

A directory path inside can be specified relative to the data directory. It must end with a slash:
Source code
```
../../my_project/resources/
```
An absolute path can be specified (slash in the end is required).
For example, on Windows:
Source code
```
D:\resources\
```
On Linux or Mac OS X:
Source code
```
/username/resources/
```

int engine.filesystem.addBlobFile (string name)

Adds a file in the memory. 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.

Arguments

string name - The file to add into the blob.

Return value

1 if the file is successfully added; 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.

Arguments

string name - File to add to a cache.

Return value

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

int engine.filesystem.addKnownFile (string name)

Registers the regular file name as known and appends it into the map used for fast searching.

Arguments

string name - File name to register 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)

Checks whether the file was loaded to the queue or not.

Arguments

string name - File name.

Return value

1 if the file is loaded to the file system; otherwise - 0.

int engine.filesystem.checkImage (string name)

Checks whether the image was loaded to the queue or not.

Arguments

string name - Name of the image.

Return value

1 if the image is loaded to the file system; otherwise - 0.

int engine.filesystem.checkMesh (string name)

Returns the value indicating if the mesh is loaded to the queue.

Arguments

string name - Mesh name.

Return value

1 if the mesh is loaded to the file system successfully; 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 - Package name. It can be an absolute path or a path relative to data (data_path) directory, if it is inside of it.

Return value

Number of the ZIP or UNG package, or -1 if it is not found.

int engine.filesystem.forceFile (string name)

Loads the pending file immediately after calling the function. (This means that 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.

Arguments

string name - File name.

Return value

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

int engine.filesystem.forceImage (string name)

Loads the pending image immediately after calling the function. (This means that 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.

Arguments

string name - Name of the image.

Return value

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

int engine.filesystem.forceMesh (string name)

Loads the pending mesh immediately after the function call. This means that 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.

Arguments

string name - Mesh name.

Return value

1 if the mesh is loaded successfully; otherwise 0.

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.

void engine.filesystem.getFileNames (int names = [])

Returns the list of unarchived files cached by the file system.

Arguments

int names - ID of return array with file names.

Image engine.filesystem.getImage (string name)

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

Arguments

string name - Name of the image.

Return value

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

long engine.filesystem.getMTime (string n)

Returns the time of the file last modification.

Arguments

string n - File name.

Return value

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

Mesh engine.filesystem.getMesh (string name)

Checks whether the mesh is placed to the loaded queue.

Arguments

string name - Mesh 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.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.

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

Returns the full path to the given file relative to the package root directory. The path includes the name of the given file.

Arguments

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

Return value

A path.

void engine.filesystem.getPackageFileNames (int num, int names = [])

Returns the list of files in the specified ZIP or UNG package.

Arguments

int num - Number of the ZIP or UNG package.
int names - ID of return array with file names.

string engine.filesystem.getPackageName (int num)

Returns a name of a given ZIP or UNG package.

Arguments

int num - Number of the ZIP or UNG package.

Return value

Name of the package.

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.isBlobFile (string name)

Checks if the given file is loaded into a blob.

Arguments

string name - The file to check.

Return value

1 if the file is loaded; otherwise, 0.

int engine.filesystem.isCacheFile (string name)

Checks if the given file is loaded into a cache.

Arguments

string name - File to check.

Return value

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

int engine.filesystem.isFile (string name)

Checks if a given file exists in the file system.

Arguments

string name - File name.

Return value

1 if the file is found; otherwise, 0.

int engine.filesystem.isKnownFile (string name)

Checks if the given file is known to the filesystem.

Arguments

string name - Name of the file.

Return value

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

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.

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

Adds a file to the background loading queue. Files with identical priorities and weights are loaded in the alphabetical order.

Arguments

string name - File name.
int priority - Group of the priority. Greater priority means faster loading.
float weight - Greater weight means faster loading inside the same priority group.

Return value

1 if the file was successfully appended to the queue, 0 if the operation failed.

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

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

Arguments

string name - Name of the image.
int priority - Group of the priority. Greater priority means faster loading.
float weight - Greater weight means faster loading inside the same priority group.

Return value

1 if the image was successfully appended to the queue, otherwise - 0.

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

Adds a mesh to the loading queue. Meshes with the identical groups and weights are loaded in the alphabetical order.

Arguments

string name - Mesh name.
int group - Group of the loading priority. Greater priority means faster loading.
float weight - Weight of the priority inside the group. Greater weight means faster loading inside the same priority group.

Return value

1 if the mesh was 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 if an absolute path is specified.

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 (data_path) 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.removeBlobFile (string name)

Removes a file from a blob.

Arguments

string name - The file to be removed.

Return value

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

int engine.filesystem.removeCacheFile (string name)

Removes a cache with a 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.

Arguments

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

Return value

1 if the file was successfully removed, otherwise - 0.

int engine.filesystem.removeImage (string name)

Removes a pending image from the loading queue.

Arguments

string name - Name of the image.

Return value

1 if the image was successfully removed, otherwise - 0.

int engine.filesystem.removeMesh (string name)

Removes a pending mesh from the loading queue.

Arguments

string name - Mesh 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. An archive can be located outside data directory if an absolute path is specified.

Arguments

string name - Package name. It can be an absolute path or a path relative to data (data_path) directory, if it is inside of it.

Return value

1 if the package is removed; otherwise, 0.

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.

Examples

Source code (UnigineScript)

// specify a name of a file located under the data directory
string name = "test.cpp";
// assign the current time stamp value to the variable
long time = engine.filesystem.getMTime(name);
// print the updated time stamp of the test.cpp
log.message("engine.filesystem.setMTime() return value: %d\n",engine.filesystem.setMTime(name,10L));
// print the saved and current time stamps to compare
log.message("Saved time stamp: %d\nUpdated time stamp: %d\n",time,engine.filesystem.getMTime(name));

Output

engine.filesystem.setMTime() return value: 1
Saved time stamp: 1404213050
Updated time stamp: 10

int engine.filesystem.validateFile (string name)

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

Arguments

string name - File name.

Return value

1 if the file has been 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)

engine.filesystem Functions

List of Functions:

Loading Files on Demand

Adding Directories via ULINK

See Also

int engine.filesystem.addBlobFile (string name)

Arguments

Return value

int engine.filesystem.addCacheFile (string name)

Arguments

Return value

int engine.filesystem.addKnownFile (string name)

Arguments

Return value

void engine.filesystem.addModifier (string name)

Arguments

int engine.filesystem.checkFile (string name)

Arguments

Return value

int engine.filesystem.checkImage (string name)

Arguments

Return value

int engine.filesystem.checkMesh (string name)

Arguments

Return value

void engine.filesystem.clearModifiers ()

int engine.filesystem.findPackage (string name)

Arguments

Return value

int engine.filesystem.forceFile (string name)

Arguments

Return value

int engine.filesystem.forceImage (string name)

Arguments

Return value

int engine.filesystem.forceMesh (string name)

Arguments

Return value

string engine.filesystem.getFileName (string name)

Arguments

Return value

void engine.filesystem.getFileNames (int names = [])

Arguments

Image engine.filesystem.getImage (string name)

Arguments

Return value

long engine.filesystem.getMTime (string n)

Arguments

Return value

Mesh engine.filesystem.getMesh (string name)

Arguments

Return value

string engine.filesystem.getModifier (int num)

Arguments

Return value

int engine.filesystem.getNumFiles ()

Return value

int engine.filesystem.getNumModifiers ()

Return value

int engine.filesystem.getNumPackageFiles (int num)

Arguments

Return value

int engine.filesystem.getNumPackages ()

Return value

int engine.filesystem.getNumQueuedData ()

Return value

int engine.filesystem.getNumQueuedFiles ()

Return value

int engine.filesystem.getNumQueuedImages ()

Return value

int engine.filesystem.getNumQueuedMeshes ()

Return value

int engine.filesystem.getNumQueuedResources ()

Return value

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

Arguments

Return value

void engine.filesystem.getPackageFileNames (int num, int names = [])

Arguments

string engine.filesystem.getPackageName (int num)