File

Inherits: Reference < Object

用于处理文件读写操作的类型。

描述

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:

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

In the example above, the file will be saved in the user data folder as specified in the Data paths documentation.

Note: To access project resources once exported, it is recommended to use ResourceLoader instead of the File API, as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package.

Note: Files are automatically closed only if the process exits “normally” (such as by clicking the window manager’s close button or pressing Alt + F4). If you stop the project execution by pressing F8 while the project is running, the file won’t be closed as the game process will be killed. You can work around this by calling flush at regular intervals.

教程

• File system

• 3D Voxel Demo

属性

方法

枚举

enum ModeFlags:

• READ = 1 —- 打开文件进行读取操作。光标位于文件的开头。

• WRITE = 2 —- 打开文件进行写操作。如果文件不存在，则创建该文件，如果存在则截断。

• READ_WRITE = 3 —- 打开文件用于读写操作。不截断文件。光标位于文件的开头。

• WRITE_READ = 7 —- 打开文件进行读写操作。如果文件不存在，则创建该文件，如果存在则截断。光标位于文件的开头。

enum CompressionMode:

• COMPRESSION_FASTLZ = 0 —- 使用 FastLZ 压缩方法。

• COMPRESSION_DEFLATE = 1 —- 使用 DEFLATE 压缩方法。

• COMPRESSION_ZSTD = 2 —- 使用 Zstandard 压缩方法。

• COMPRESSION_GZIP = 3 —- 使用 gzip 压缩方法。

属性说明

• bool endian_swap

为 true 时文件以大端字节序读取。为 false 时文件以小端字节序读取。如果不确定，请将其保留为 false，因为大多数文件都是以小端字节序编写的。

注意：endian_swap 只是文件格式，与 CPU 类型无关。 CPU 字节序不会影响写入文件的默认字节序。

注意：每当您打开文件时，它总是重置为 false。因此，必须在打开文件之后设置 endian_swap，而不是之前。

方法说明

• void close ( )

关闭当前打开的文件，并阻止后续的读/写操作。使用 flush 将数据持久化到磁盘，而不关闭文件。

• bool eof_reached ( ) const

如果文件光标已经读到了文件的末端，返回 true。

注意：eof_reached() == false 不能用来检查是否有更多的数据可用。要在有更多数据可用时进行循环，请使用：

while file.get_position() < file.get_len():
    # 读取数据

• bool file_exists ( String path ) const

如果文件存在于给定的路径中，返回 true。

注意：许多资源类型导入后，例如纹理或声音文件，其源资产不会包含在导出的游戏中，因为只使用导入的版本。有关考虑资源重新映射的替代方法，请参阅 ResourceLoader.exists。

• void flush ( )

将文件的缓冲区写入磁盘。关闭文件时会自动执行刷新。这意味着您不需要在使用 close 关闭文件之前手动调用 flush。尽管如此，即使项目崩溃而不是正常关闭，调用 flush 仍可用于确保数据安全。

注意：只有在你真正需要的时候才调用 flush。否则，它会由于不断的磁盘写入而降低性能。

• int get_16 ( ) const

以整数形式返回文件中接下来的 16 位。请参阅 store_16，以获取有关可以通过这种方式存储和检索哪些值的详细信息。

• int get_32 ( ) const

以整数形式返回文件中接下来的 32 位。请参阅store_32，以获取有关可以通过这种方式存储和检索哪些值的详细信息。

• int get_64 ( ) const

以整数形式返回文件中接下来的 64 位。请参阅 store_64，以获取有关可以通过这种方式存储和检索哪些值的详细信息。

• int get_8 ( ) const

以整数形式返回文件中接下来的 8 位。请参阅 store_8，详细了解哪些值可以通过这种方式存储和检索。

• String get_as_text ( ) const

将整个文件作为 String 字符串返回。

将按照 UTF-8 编码解析文本。

• PoolByteArray get_buffer ( int len ) const

将文件中接下来的 len 个字节作为 PoolByteArray 返回。

• PoolStringArray get_csv_line ( String delim=”,” ) const

以 CSV（逗号分隔值）格式返回文件的下一个值。您可以传递不同的分隔符 delim 以使用默认 ","（逗号）以外的其他分隔符。此分隔符必须为一个字符长，并且不能是双引号。

将按照 UTF-8 编码解析文本。如果文本值包含分隔符，则必须用双引号括起来。文本值中的双引号可以通过将它们的出现次数加倍来转义。

例如，以下 CSV 行是有效的，每行将被正确解析为两个字符串：

Alice,"Hello, Bob!"
Bob,Alice! What a surprise!
Alice,"I thought you'd reply with ""Hello, world""."

请注意第二行如何省略封闭引号，因为它不包含分隔符。然而它可以很好地使用引号，它只是为了演示目的而没有编写。第三行必须使用 "" 来表示每个需要被解释为引号的引号，而不是文本值的结束。

• float get_double ( ) const

将文件中接下来的 64 位作为浮点数返回。

• Error get_error ( ) const

返回试图执行操作时发生的最后一个错误。请与 Error 中的 ERR_FILE_* 常量比较。

• float get_float ( ) const

将文件中接下来的 32 位作为浮点数返回。

• int get_len ( ) const

返回该文件的大小，单位为字节。

• String get_line ( ) const

将文件中的下一行作为 String 字符串返回。

将按照 UTF-8 编码解析文本。

• String get_md5 ( String path ) const

返回一个给定路径文件的MD5字符串，如果失败则返回一个空的String。

• int get_modified_time ( String file ) const

返回unix格式的时间戳file为文件的最后修改时间，或者返回一个String“ERROR IN file“。这个unix时间戳可以通过使用OS.get_datetime_from_unix_time转换为数据时间。

• String get_pascal_string ( )

返回文件中按照 Pascal 格式保存的 String 字符串。

将按照 UTF-8 编码解析文本。

• String get_path ( ) const

返回当前打开的文件的路径为String。

• String get_path_absolute ( ) const

返回当前打开的文件的绝对路径为String。

• int get_position ( ) const

返回文件光标的位置。

• float get_real ( ) const

将文件中接下来的若干位以浮点数形式返回。

• String get_sha256 ( String path ) const

返回一个给定路径的文件的 SHA-256 字符串，如果失败则返回一个空的 String。

• Variant get_var ( bool allow_objects=false ) const

返回文件中的下一个 Variant 值。allow_objects 为 true 时允许对对象进行解码。

警告：反序列化得到的对象可能包含被执行的代码。如果序列化的对象来自不受信任的来源，请不要使用这个选项，以避免潜在的安全威胁，如远程代码执行。

• bool is_open ( ) const

如果文件当前被打开，返回true。

• Error open ( String path, ModeFlags flags )

打开文件进行写入或读取，取决于标志。

• Error open_compressed ( String path, ModeFlags mode_flags, CompressionMode compression_mode=0 )

打开压缩文件进行读取或写入。

注意： open_compressed 只能读取Godot保存的文件，不能读取第三方压缩格式。有关解决方法，请参阅 ` GitHub 问题 #28999 <https://github.com/godotengine/godot/issues/28999>`__。

• Error open_encrypted ( String path, ModeFlags mode_flags, PoolByteArray key )

以写或读的模式打开一个加密文件。你需要传递一个二进制密钥来加密/解密它。

注意： 提供的密钥必须是32字节长。

• Error open_encrypted_with_pass ( String path, ModeFlags mode_flags, String pass )

以写或读的方式打开一个加密的文件。你需要传递一个密码来加密/解密它。

• void seek ( int position )

将文件的读/写光标改变到指定的位置（从文件开始的字节数）。

• void seek_end ( int position=0 )

将文件的读/写光标改变到指定的位置（从文件的末端算起，以字节为单位）。

注意：这是一个偏移量，所以你应该使用负数，否则光标会在文件的末端。

• void store_16 ( int value )

将一个整数以 16 位形式存储在文件中。

注意：value 应该位于 [0, 2^16 - 1] 区间内。任何其他的值都会溢出并进行环绕。

要存储有符号的整数，请使用 store_64 或者从区间 [-2^15, 2^15 - 1] 中存储一个有符号的整数（即保留一位作为有符号），在读取时手动计算其符号。比如说

const MAX_15B = 1 << 15
const MAX_16B = 1 << 16
func unsigned16_to_signed(unsigned):
    return (unsigned + MAX_15B) % MAX_16B - MAX_15B
func _ready():
    var f = File.new()
    f.open("user://file.dat", File.WRITE_READ)
    f.store_16(-42) # 会进行环绕，保存的是 65494 (2^16 - 42)。
    f.store_16(121) # 在范围内，会保存 121。
    f.seek(0) # 返回开头读取保存的值。
    var read1 = f.get_16() # 65494
    var read2 = f.get_16() # 121
    var converted1 = unsigned16_to_signed(read1) # -42
    var converted2 = unsigned16_to_signed(read2) # 121

• void store_32 ( int value )

将一个整数以 32 位形式存储在文件中。

注意：value 应该位于 [0, 2^32 - 1] 区间内。任何其他的值都会溢出并环绕。

要存储有符号的整数，请使用 store_64，或者手动转换（见 store_16 的例子）。

• void store_64 ( int value )

将一个整数以 64 位形式存储在文件中。

注意：value 必须位于 [-2^63, 2^63 - 1] 的区间内（即有效的 int 值）。

• void store_8 ( int value )

将一个整数以 8 位形式存储在文件中。

注意：value 应该位于 [0, 255] 的区间内。任何其他的值都会溢出并环绕。

要存储有符号的整数，请使用 store_64，或者手动转换（见 store_16 的例子）。

• void store_buffer ( PoolByteArray buffer )

在文件中存储给定的字节数组。

• void store_csv_line ( PoolStringArray values, String delim=”,” )

将给定的 PoolStringArray 作为 CSV（逗号分隔值）格式的行存储在文件中。您可以传递不同的分隔符 delim 以使用默认 ","（逗号）以外的其他分隔符。此分隔符的长度必须为一个字符。

将使用 UTF-8 编码文本。

• void store_double ( float value )

将一个浮点数以 64 位形式存储在文件中。

• void store_float ( float value )

将一个浮点数以 32 位形式存储在文件中。

• void store_line ( String line )

Appends line to the file followed by a line return character (\n), encoding the text as UTF-8.

• void store_pascal_string ( String string )

将给定的String以Pascal格式存储在文件中（例如，也将字符串长度存储）。

文本将被编码为UTF-8。

• void store_real ( float value )

将浮点数存储在文件中。

• void store_string ( String string )

将 string 字符串追加到文件中，不带换行，文本将被编码为 UTF-8。

注意：本方法是为写入文本文件准备的。字符串会被存储为 UTF-8 编码的缓冲区，不带字符串长度或末尾零，所以无法轻易读回。如果你想要在二进制文件中存储可取回的字符串，请考虑换用 store_pascal_string。要从文本文件中获取字符串，你可以使用 get_buffer(length).get_string_from_utf8()（需要已知长度）或 get_as_text。

• void store_var ( Variant value, bool full_objects=false )

在文件中存储任何 Variant 变量值。如果 full_objects 是 true，则允许编码对象（并且可能包含代码）。

注意： 并非所有属性都包括在内。只有使用 @GlobalScope.PROPERTY_USAGE_STORAGE 标志集配置的属性才会被序列化。您可以通过覆盖类中的 Object._get_property_list 方法向属性添加新的使用标志。您还可以通过调用 Object._get_property_list 来检查属性使用是如何配置的。有关可能的使用标志，请参阅 PropertyUsageFlags。