Editor: Handling Files & Directories
Description
Although the Unreal Engine has several important functions in dealing with files, the functions exposed to the Blueprints are missing some key functionality. The File Library is a custom-made library of functions that can be useful for managing, reading and writing files safely. This guide will cover the important functions available in Blueprints and the methods in which they can be called.
File Paths
The Files functions can perform lookups for files that exist within certain special asset folders. These include the Data folder in the project and the Content directory. As such, it can look up any file that exists here that matches a unique name. To fetch the directory and path of these files, if they match the correct value, then the Get File Directory and Get Full Path functions can be called.
Additionally, to determine if a file path is valid and contains a file (or a directory), the Is Valid Path function can be called, which will return a flag of whether the path is valid.
Reading Files
Unreal has some standard functions for reading file texts. However, the functions provided in this library are safer and work with any of the asset-registered files as per the previous section. Two functions are present here; Read Text and Read Lines. The first function will return the full text found within the file if it exists. The second function will return an array of the lines split by a new line character as strings.
Note
In both function cases, if the file does not exist in the path, then it will return an empty string or an empty array of strings, depending on the function.
Creating Files
New files can be created using the Create File function. This will take in a directory and a file name. The directories can be fetched using the standard Unreal file paths, including the content, saved and project directories. Alternatively, a full path from disk can be used in this method if needing to add a file in a remote directory.
The method will also return a flag whether the file has been created successfully or not. If the file path is invalid, no file will be created. Additionally, if the directory does not exist, it will attempt to create all necessary directories to ensure that the path does exist.
Note
Ensure that the correct file type is defined (such as a.txt file) as not entering a file type may lead to a corrupted file.
Although this function does create new directories if required, to construct a new directory by itself, the Create Directory function can be called. This takes in a path which is the name of the new directory inside any other directories.
Note
To concatenate paths together, use the Append method on the string class, which will enable multiple strings to be added together. This can be useful for constructing paths for the directories.
Writing to Files
Files can also be written to. These can be done using the Write (String) and Write (Text) functions, which will write either an Unreal string or text to the file. Both cases return a flag of whether the data is valid and was written to. If the append flag is enabled, then the data will be added to the end of the file, rather than replace the entire file with the text that was written to initially.
Note
New files do not need to be created first. If the directory or file does not exist when attempting to write to the data, it will create the files beforehand and then write the data to the file.
Listing Files
To find a list of all files that match a particular filter, the List Files method is a pure function that can return a list of all files that exist in a directory. It has a few parameters that can be inputted and it will return an array of strings based on the conditions.
- Path: This is the full path to the directory that will be checked. If the directory does not exist, then no files will be returned.
- Filter: This is the filter to apply in the file listing. By default, a
*will select all files, but a*.txtwill select only files that have the text extension. - Recursive: This flag will determine whether it should look into only the base directory or all directories within that one and find all-recursive files.
- Relative: If this flag is turned on, then the return value strings will include the file path relative to the path that is provided. If it is disabled, then the return strings will be the full file path from the system root.
Similarly, the same functionality exists for searching for directories within a directory. The List Directories method has the same parameters and works in the same way, only with directories instead of files.
Metadata
It is possible to get the size of a file or directory in bytes. This will be the size of the entire file or directory, including any sub-directories and files, of the path that is passed in. This can be done by calling the Get Size function, which will return a 64-bit integer with the number of bytes that are occupied by the directory or file.
