This variable holds status (true or false) of whether the native extension for NSFS was successfully loaded. The extension may not be loaded in a few cases:

• Extension is not supported on the target platform.
• Extension' file is amiss (e.g. the user did not unzip the game before running).

As per GameMaker rules, all calls to unavailable extensions return 0 instead, so you may want to check this and notify the user prior to performing any operations.

Some functions provide additional feedback aside of usual success/failure result.

In those cases, when the result is false, this global variable holds the status/error code that can be used for troubleshooting the issue.

On Windows, values are as per System Error Codes reference.

By default, when a relative path is specified, NSFS will read/write files in game's program directory. If you want to use some other directory instead (e.g. save directory), you can use this function to change the extension's working directory.

The function returns whether the working directory was successfully changed; nsfs_status contains the error code if it couldn't be.

One of the few reasons to failure of this function is the target directory not being a valid path (use directory_exists or directory_exists_ns to check).

Returns the extension's working directory.

If that somehow fails, returns an empty string and sets nsfs_status.

Returns whether the file exists at the given path.

Returns false if there's a directory of the same name at the path.

Copies a file between locations, returns whether successful.

In case of failure, nsfs_status contains the error code.

Renames a file, returns whether successful.

Note that if the oldname contains a path, newname should as well.

In case of failure, nsfs_status contains the error code.

Moves a file to a different location, returns whether successful.

In case of failure, nsfs_status contains the error code.

Deletes a file, returns whether successful.

In case of failure, nsfs_status contains the error code.

Note that you can't remove files currently in use by an application (incl. yours).

Returns whether the file exists at the given path.

Returns false if there's a directory of the same name at the path.

Copies a directory between locations, returns whether successful.

In case of failure, nsfs_status contains the error code.

Renames a directory, returns whether successful.

Note that if the oldname contains a path, newname should as well.

In case of failure, nsfs_status contains the error code.

Directories cannot be renamed if some of their files are currently in use by applications (incl. yours).

Moves a directory to a different location, returns whether successful.

In case of failure, nsfs_status contains the error code.

Directories cannot be moved if some of their files are currently in use by applications (incl. yours).

Creates a directory at a location, returns whether successful.

In case of failure, nsfs_status contains the error code.

Note that the parent directory must exist for this to work.

Deletes a directory, returns whether successful.

In case of failure, nsfs_status contains the error code.

Directories cannot be deleted if some of their files are currently in use by applications (incl. yours).

Returns attributes of a file/directory at given path.

Returned attributes (a set of bit flags) are as per MSDN specification.

If attributes cannot be retrieved (e.g. no object exists at path), returned value is -1, and nsfs_status contains the error code.

Changes the attributes of a file/directory at the given path, returns whether successful. The attributes (a set of bit flags) are as per MSDN specification.

If attributes cannot be changed, nsfs_status contains the error code.

Returns the size of the file at given path, in bytes.

If the size cannot be measured, returns -1 and sets nsfs_status.

Returns the creation time of the file at given path, in GameMaker (date_) format.

If the time cannot be measured (file doesn't exist / cannot be accessed), returns 0 and sets nsfs_status.

Returns the "last write" time of the file at given path, in GameMaker (date_) format.

If the time cannot be measured (file doesn't exist / cannot be accessed), returns 0 and sets nsfs_status.

Returns the "last access" time of the file at given path, in GameMaker (date_) format.

Note that this time marker is throttled by Windows to avoid excessive disk use.

If the time cannot be measured (file doesn't exist / cannot be accessed), returns 0 and sets nsfs_status.

Begins the search for files/directories matching the given mask and returns the first result. Returns "" and sets nsfs_status if nothing can be found.

This is much akin to file_find_first, but with one remark: instead of taking attributes as a second parameter (which gives very limited freedom to filtering results), there is a file_find_attributes_ns function that returns the attributes of the current file in search.

For example, if you wanted to pick through just files (no directories) in maps subdirectory in game's directory, you would do that like so:

for (var f = file_find_first_ns("maps/*.*"); f != ""; f = file_find_next_ns()) {
    if (file_find_attributes_ns() & fa_directory) continue;
    // file is not a directory - do something here
    show_debug_message(f + ": " + string(file_find_size_ns() / 1024) + "KB");
}
file_find_close();

which would display results like some.map (given maps/some.map).

Returns the next result matching the mask (from file_find_first_ns).

Returns "" if there are no more results left.

Finalizes the current search and frees up the related resources.

file_find_first_ns will automatically do this prior to starting the next search if you forget, but it is recommended that you do this by yourself when a search is complete.

Returns the attributes (much like file_get_attributes_ns) of the current (most recently returned) file in search. Due to how file search works, this is generally faster than retrieving the attributes by absolute path.

Returns the size (in bytes) of the current (most recently returned) file in search. This is generally faster than retrieving the size by absolute path.

This function considers directories to have size of 0 bytes.

Opens a text file at given path for reading and returns file ID.

Codepage numbers can be found on MSDN.

-1 can be specified as a codepage to use UTF-8 (GMS default).

If the file cannot be opened for reading, returns -1 and sets nsfs_status.

IDs used by these functions are separate from those used by built-in ones.

Opens a text file at given path for writing and returns file ID.

If the file is already present, it is overwritten.

Codepage numbers can be found on MSDN.

-1 can be specified as a codepage to use UTF-8 (GMS default).

If the file cannot be opened for writing, returns -1 and sets nsfs_status.

Opens a text file at given path for writing and returns file ID.

If the file is already present, appends to the end of the file.

Codepage numbers can be found on MSDN.

-1 can be specified as a codepage to use UTF-8 (GMS default).

If the file cannot be opened for writing, returns -1 and sets nsfs_status.

Closes the given text file, freeing it for operations or use by other applications.

Returns whether the file was actually open (and thus could be closed).

Returns whether end of file was reached for the given file.

Only makes sense for files opened for reading.

Returns true for invalid file IDs.

Reads and returns the next line from the given file.

This is equivalent to file_text_read_string + file_text_readln. That is, it reads and returns the text on the current line, and skips the line delimiter (CRLFCRLFLFCR).

Returns "" if the file handle is invalid or end of file has been reached.

Writes a string to the given file, returns whether successful.

Adds a linebreak (CRLF) prior to writing automatically if it is not the first line.

Opens an INI file from absolute path.

This is a wrapper around string_load_ns and ini_open_from_string.

You can subsequently use the regular ini_ functions to work with it and use ini_close_ns to close the file while applying changes (or regular ini_close if you have made none)

Closes an INI file previously opened via ini_open_ns and overwrites the file on disk if there have been changes.

If the file cannot be written to, returns -1 and sets nsfs_status.

Loads a GM buffer from the file and returns it's ID.

Is a direct equivalent of the built-in buffer_load function.

Second argument can be specified to use a different buffer kind for loaded information. If it isn't, GM default (buffer_grow) will be used.

If the file cannot be read, returns -1 and sets nsfs_status.

Saves the contents of the given buffer to a file, returns whether successful.

Is akin to the built-in buffer_save function (but has a return value).

If the file cannot be written to, returns false and sets nsfs_status.

Saves a subsection of the given buffer to a file, returns whether successful.

Is akin to the built-in buffer_save_ext function (but has a return value).

If the file cannot be written to, returns false and sets nsfs_status.

Returns the contents of the file at given path as a string.

This can be a little faster than reading the file via buffer or file_text functions.

If the file is missing or there is an error, returns "" and sets nsfs_status.

Overwrites the contents of the file at given path with the given string.

If the file cannot be written to, returns false and sets nsfs_status.

Converts contents of a string between codepages.

Codepage numbers can be found on MSDN.

-1 can be specified as a codepage to use UTF-8 (GMS default).

This can be handy if you are getting strings in different encoding from non-filesystem sources.

An equivalent of sprite_add.

If the file cannot be read, returns -1 and sets nsfs_status.

An equivalent of sprite_replace.

If the file cannot be read, returns false and sets nsfs_status.

An equivalent of surface_save.

If the file cannot be written to, returns false and sets nsfs_status.

An equivalent of surface_save_part.

If the file cannot be written to, returns false and sets nsfs_status.

An equivalen of screen_save.

If the file cannot be written to, returns false and sets nsfs_status.

An equivalen of screen_save_part.

If the file cannot be written to, returns false and sets nsfs_status.

You can copy the file in/out of sandbox for processing, but you should seriously consider using a buffer_fast buffer for reading or buffer_grow buffer for writing instead - both are much faster than the legacy binary file functions.

A thing to note here is that, unlike other functions, you'll need to keep the file around for the duration of using it. For this reason there is no "built-in" function included for this in nsfs.