File System

The virtual file system allows scripts to interact with files in the game's directory. It provides functions for reading, writing, and managing files.

For security reasons, only the directory scripts/maps/store/ or scripts/plugins/store/ can be accessed.

The CVirtualFileSystem class allows for opening and removing files. A single global instance exists: CVirtualFileSystem g_FileSystem

Opening a file is done as follows:

OpenFileFlags_t uiOpenFlags = WRITE;
File@ pFile = g_FileSystem.OpenFile( "scripts/maps/store/<your filename>.<your extension>", uiOpenFlags );

if( pFile is null || !pFile.IsOpen() ) // File does not exist/couldn't open
    return;
// Read file line by line
while( !pFile.EOFReached() )
{
    string sCurrentLine;
    // Read the current line, store line content in sCurrentLine
    pFile.ReadLine( sCurrentLine );
    sCurrentLine.Trim();
    // Write to the file. OpenFileFlags_t uiOpenFlags must be set to WRITE
    pFile.Write( "Hello World!\n" );
}

pFile.Close(); // Close the file, if we are done.

1 Methods

CVirtualFileSystem method	Description
const FileQuota@ GetFileQuota() const	Gets the file system quota object. Do not store a handle to this object, as it may be replaced at any time.
File@ OpenFile(const string& in szFilename, const OpenFileFlags_t uiOpenFlags)	Opens a file. Returns nullptr if the file could not be opened.
void RemoveFile(const string& in szFilename)	Removes a file.

2 OpenFile

These are values used for the OpenFile method and are of type OpenFileFlags_t. They belong to the OpenFile enumeration.

Name	Value	Description
READ	1	Open file for reading.
WRITE	2	Open file for writing.
APPEND	4	Open file for appending.
BINARY	8	Open in binary mode.

3 File

The File class represents an actual file object, which is returned by the CVirtualFileSystem method OpenFile.

Declaration	Description
bool IsOpen() const	Returns whether the file was successfully opened.
void Close()	Closes the file if it is open.
void Remove()	Removes the file. The file must be open, and you must have write access.
size_t GetSize() const	Returns the size of the file.
size_t Tell() const	Tells the position of the read/write pointer.
size_t Seek(const size_t uiPosition, const SeekFileFlags_t uiSeekMode)	Sets the read/write pointer to a new position. Returns the new position within the file.
bool EOFReached() const	Returns whether end of file was reached.
string ReadCharacter()	Reads a single character.
void ReadLine(string& out szOutLine, const string& in szDelim = ' ')	Reads a line from the file.
bool Read(BLOB@ pBlob, size_t uiSizeInBytes)	Reads a number of bytes into the given BLOB.
bool Read(BLOB@ pBlob)	Reads as much as possible data into the given BLOB.
BLOB@ ReadBlob(size_t uiSizeInBytes, bool fCanResize = true)	Reads a number of bytes into a BLOB.
BLOB@ ReadBlob()	Reads as much as possible data into a BLOB.
void Write(const string& in szString)	Writes a string to the file.
void Write(const BLOB@ pBlob)	Writes a blob to the file.

4 Associated Global Functions

These function exist in the FileSystem namespace.

Declaration	Description
bool FlagsValid(const OpenFileFlags_t uiOpenFlags)	Returns whether the given open flags are valid.
OpenFileFlags_t FilterFlags(OpenFileFlags_t uiOpenFlags)	Filters the given flags, removing unnecessary flags.
bool FormatOpenFlags(OpenFileFlags_t uiOpenFlags, string& out szOutFlags)	Formats the open flags into a string that represents the flags.