Type to handle file reading and writing operations.
    public class File : Reference

File type. This is used to permanently store data into the user device’s file system and to read from it. This can be used to store game save data or player configuration files, for example.

Here’s a sample on how to write and read from a file:

[codeblock]

func save(content):

var file = File.new()

file.open(“user://save_game.dat”, File.WRITE)

file.store_string(content)

file.close()

func load():

var file = File.new()

file.open(“user://save_game.dat”, File.READ)

var content = file.get_as_text()

file.close()

return content

[/codeblock]

Inheritance Chain

Constructors

    public File()

Properties

    public bool EndianSwap { get; set; }

If true, the file’s endianness is swapped. Use this if you’re dealing with files written on big-endian machines.

Note: This is about the file format, not CPU type. This is always reset to false whenever you open the file.

Methods

    public void Close()

Closes the currently opened file.

    public bool EofReached()

Returns true if the file cursor has read past the end of the file.

Note: This function will still return false while at the end of the file and only activates when reading past it. This can be confusing but it conforms to how low-level file access works in all operating systems. There is always GetLen() and GetPosition() to implement a custom logic.

    public bool FileExists(string path)

Returns true if the file exists in the given path.

Note: Many resources types are imported (e.g. textures or sound files), and that their source asset will not be included in the exported game, as only the imported version is used (in the res://.import folder). To check for the existence of such resources while taking into account the remapping to their imported location, use ResourceLoader.Exists(string, string). Typically, using File.file_exists on an imported resource would work while you are developing in the editor (the source asset is present in res://, but fail when exported).

    public ushort Get16()

    public uint Get32()

    public ulong Get64()

    public byte Get8()

    public string GetAsText()

Returns the whole file as a String.

Text is interpreted as being UTF-8 encoded.

    public byte[] GetBuffer(int len)

Returns next len bytes of the file as a PoolByteArray.

    public string[] GetCsvLine(string delim = ",")

Returns the next value of the file in CSV (Comma-Separated Values) format. You can pass a different delimiter delim to use other than the default "," (comma). This delimiter must be one-character long.

Text is interpreted as being UTF-8 encoded.

    public double GetDouble()

    [Obsolete("GetEndianSwap is deprecated. Use the EndianSwap property instead.")]
    public bool GetEndianSwap()

Getter for EndianSwap

    public Error GetError()

Returns the last error that happened when trying to perform operations. Compare with the ERR_FILE_* constants from [enum Error].

    public float GetFloat()

Returns the next 32 bits from the file as a floating-point number.

    public long GetLen()

    public string GetLine()

Returns the next line of the file as a String.

Text is interpreted as being UTF-8 encoded.

    public string GetMd5(string path)

Returns an MD5 String representing the file at the given path or an empty String on failure.

    public ulong GetModifiedTime(string file)

    public string GetPascalString()

Returns a String saved in Pascal format from the file.

Text is interpreted as being UTF-8 encoded.

    public string GetPath()

Returns the path as a String for the current open file.

    public string GetPathAbsolute()

Returns the absolute path as a String for the current open file.

    public long GetPosition()

    public float GetReal()

Returns the next bits from the file as a floating-point number.

    public string GetSha256(string path)

Returns a SHA-256 String representing the file at the given path or an empty String on failure.

    public object GetVar(bool allowObjects = false)

Returns the next Variant value from the file. If allowObjects is true, decoding objects is allowed.

Warning: Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution.

    public bool IsOpen()

Returns true if the file is currently opened.

    public Error Open(string path, ModeFlags flags)

Opens the file for writing or reading, depending on the flags.

    public Error OpenCompressed(string path, ModeFlags modeFlags, CompressionMode compressionMode = CompressionMode.Fastlz)

Opens a compressed file for reading or writing.

    public Error OpenEncrypted(string path, ModeFlags modeFlags, byte[] key)

Opens an encrypted file in write or read mode. You need to pass a binary key to encrypt/decrypt it.

    public Error OpenEncryptedWithPass(string path, ModeFlags modeFlags, string pass)

Opens an encrypted file in write or read mode. You need to pass a password to encrypt/decrypt it.

    public void Seek(long position)

    public void SeekEnd(long position = 0L)

    [Obsolete("SetEndianSwap is deprecated. Use the EndianSwap property instead.")]
    public void SetEndianSwap(bool enable)

Setter for EndianSwap

    public void Store16(ushort value)

    public void Store32(uint value)

    public void Store64(ulong value)

    public void Store8(byte value)

    public void StoreBuffer(byte[] buffer)

Stores the given array of bytes in the file.

    public void StoreCsvLine(string[] values, string delim = ",")

Store the given PoolStringArray in the file as a line formatted in the CSV (Comma-Separated Values) format. You can pass a different delimiter delim to use other than the default "," (comma). This delimiter must be one-character long.

Text will be encoded as UTF-8.

    public void StoreDouble(double value)

    public void StoreFloat(float value)

Stores a floating-point number as 32 bits in the file.

    public void StoreLine(string line)

Stores the given String as a line in the file.

Text will be encoded as UTF-8.

    public void StorePascalString(string @string)

Stores the given String as a line in the file in Pascal format (i.e. also store the length of the string).

Text will be encoded as UTF-8.

    public void StoreReal(float value)

Stores a floating-point number in the file.

    public void StoreString(string @string)

Stores the given String in the file.

Text will be encoded as UTF-8.

    public void StoreVar(object value, bool fullObjects = false)

Stores any Variant value in the file. If fullObjects is true, encoding objects is allowed (and can potentially include code).

Inner Types

CompressionMode

Name Value Description
Fastlz 0 Uses the [url=http://fastlz.org/]FastLZ[/url] compression method.
Deflate 1 Uses the [url=https://en.wikipedia.org/wiki/DEFLATE]DEFLATE[/url] compression method.
Zstd 2 Uses the [url=https://facebook.github.io/zstd/]Zstandard[/url] compression method.
Gzip 3 Uses the [url=https://www.gzip.org/]gzip[/url] compression method.

ModeFlags

Name Value Description
Read 1 Opens the file for read operations.
Write 2 Opens the file for write operations. Create it if the file does not exist and truncate if it exists.
ReadWrite 3 Opens the file for read and write operations. Does not truncate the file.
WriteRead 7 Opens the file for read and write operations. Create it if the file does not exist and truncate if it exists.
Tags: